@trim21/personal-pi-extensions 0.1.489 → 0.1.491

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.489",
+  "version": "0.1.491",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/bwrap/approval-suggest.ts

@@ -18,7 +18,7 @@ import { type BashCommand, parseBashCommands } from "./approval-rules.js";
  */
 const ARITY = JSON.parse(readFileSync(new URL("arity.json", import.meta.url), "utf8")) as Record<
   string,
-  number
+  number | undefined
 >;
 
 /**

package/src/bwrap/core.ts

@@ -105,11 +105,11 @@ export function resolveBwrap(config: BwrapConfig): ResolvedBwrap {
   const base = {
     mode: config.mode,
     bwrapPath: config.bwrapPath,
-    writablePaths: config.writablePaths ?? [".", "/tmp"],
+    writablePaths: config.writablePaths,
     extraWritablePaths: config.extraWritablePaths,
-    denyPaths: config.denyPaths ?? [],
-    extraArgs: config.extraArgs ?? [],
-    networkAllowlist: config.networkAllowlist ?? [],
+    denyPaths: config.denyPaths,
+    extraArgs: config.extraArgs,
+    networkAllowlist: config.networkAllowlist,
     mihomoPath: config.mihomoPath,
     slirp4netnsPath: config.slirp4netnsPath,
     approvalRules: config.approvalRules ?? [],
@@ -529,8 +529,8 @@ export function createBwrapBashOperations(
             }, timeout * 1000)
           : undefined;
         const onAbort = () => killChild(child);
-        child.stdout?.on("data", onData);
-        child.stderr?.on("data", onData);
+        child.stdout.on("data", onData);
+        child.stderr.on("data", onData);
         signal?.addEventListener("abort", onAbort, { once: true });
         child.once("error", reject);
         child.once("close", (exitCode) => {

package/src/bwrap/mihomo-config.ts

@@ -81,7 +81,9 @@ function parseAllowlistEntry(entry: string): AllowlistEntry {
     const match = /^\[(.+)\](?::(\d+))?$/.exec(entry);
     if (match?.[1] === undefined) throw new Error(`Invalid allowlist entry "${entry}"`);
     host = match[1];
-    port = match[2] === undefined ? undefined : parsePort(match[2]);
+    // 端口组 (?::(\d+))? 可选：无端口时 match[2] 在运行时是 undefined
+    const portPart = match[2] as string | undefined;
+    port = portPart === undefined ? undefined : parsePort(portPart);
   } else {
     const colon = entry.lastIndexOf(":");
     if (colon === -1) {

package/src/bwrap/network-stack.ts

@@ -332,8 +332,8 @@ export async function startNetworkStack(options: NetworkStackOptions): Promise<N
             killChild(child.pid);
           };
 
-          child.stdout?.on("data", execOptions.onData);
-          child.stderr?.on("data", execOptions.onData);
+          child.stdout.on("data", execOptions.onData);
+          child.stderr.on("data", execOptions.onData);
           execOptions.signal?.addEventListener("abort", onAbort, { once: true });
 
           child.once("error", (error) => {

package/src/claude-code/edit-utils.ts

@@ -73,10 +73,10 @@ function applyCurlySingleQuotes(str: string): string {
   for (let i = 0; i < chars.length; i++) {
     if (chars[i] === "'") {
       // 缩写中的撇号（如 don't）用右花引号，不做开/闭判断
-      const prev = chars[i - 1];
-      const next = chars[i + 1];
-      const prevIsLetter = prev !== undefined && /\p{L}/u.test(prev);
-      const nextIsLetter = next !== undefined && /\p{L}/u.test(next);
+      const prev = i > 0 ? chars[i - 1] : "";
+      const next = i + 1 < chars.length ? chars[i + 1] : "";
+      const prevIsLetter = /\p{L}/u.test(prev);
+      const nextIsLetter = /\p{L}/u.test(next);
       if (prevIsLetter && nextIsLetter) {
         result.push(RIGHT_SINGLE_CURLY_QUOTE);
       } else {

package/src/claude-code/files.ts

@@ -15,7 +15,8 @@ import {
 import { Type } from "typebox";
 
 import { appendLspDiagnosticText } from "../lib/lsp/diagnostic.js";
-import { type LspService, registerLsp } from "../lib/lsp/lsp.js";
+import { registerLspInspectTools } from "../lib/lsp/inspect-tool.js";
+import { createLspManager, type LspService, type LspServiceOptions } from "../lib/lsp/lsp.js";
 import { registerLspRenameTool } from "../lib/lsp/rename-tool.js";
 import { formatSubtitlePath } from "../lib/path.js";
 import type { ToolPendant } from "../lib/pendant.ts";
@@ -228,7 +229,7 @@ function requireCurrentRead(
 export function registerFileTools(
   pi: ExtensionAPI,
   state: ClaudeCodeState,
-  service: LspService,
+  getService: () => LspService,
 ): void {
   pi.registerTool({
     name: "Read",
@@ -351,9 +352,11 @@ export function registerFileTools(
       const snapshot = { ...snapshotOf(buffer), offset, limit };
       state.reads.set(key, snapshot);
       // LSP 文件事件通知是后台任务，失败不影响读取（read 不驻留文档）
-      void service.notifyFile(filePath, ctx.cwd).catch(() => {
-        // 后台通知失败不影响读取
-      });
+      void getService()
+        .notifyFile(filePath, ctx.cwd)
+        .catch(() => {
+          // 后台通知失败不影响读取
+        });
       return {
         content: [{ type: "text", text: formatted.text }],
         details: {
@@ -443,7 +446,7 @@ export function registerFileTools(
                 text: diagnosticText,
                 errorCount,
                 warningCount,
-              } = await service.lspDiagnosticsForFile(filePath, ctx.cwd, {
+              } = await getService().lspDiagnosticsForFile(filePath, ctx.cwd, {
                 notify: (message, level) => ctx.ui.notify(message, level),
                 signal,
               });
@@ -546,7 +549,7 @@ export function registerFileTools(
               text: diagnosticText,
               errorCount,
               warningCount,
-            } = await service.lspDiagnosticsForFile(filePath, ctx.cwd, {
+            } = await getService().lspDiagnosticsForFile(filePath, ctx.cwd, {
               notify: (message, level) => ctx.ui.notify(message, level),
             });
             return [
@@ -645,7 +648,7 @@ export function registerFileTools(
               text: diagnosticText,
               errorCount,
               warningCount,
-            } = await service.lspDiagnosticsForFile(filePath, ctx.cwd, {
+            } = await getService().lspDiagnosticsForFile(filePath, ctx.cwd, {
               notify: (message, level) => ctx.ui.notify(message, level),
             });
             return [
@@ -674,21 +677,8 @@ export function registerFileTools(
     },
   });
 
-  // lsp-rename 工具壳与 opencode 共享（lib/lsp/rename-tool.ts）；本工具集
-  // 跟踪 read-before-write 状态，rename 落盘的文件要标记为已读并随 details
-  // 持久化（FILE_TOOL_NAMES 的 restoreFileReads 依赖 details.reads）。
-  registerLspRenameTool(pi, service, {
-    recordReads: async (applied) => {
-      const reads: Record<string, FileSnapshot> = {};
-      for (const fileEdit of applied) {
-        const key = await readStateKey(fileEdit.path);
-        const snapshot = snapshotOf(fileEdit.newText);
-        state.reads.set(key, snapshot);
-        reads[key] = snapshot;
-      }
-      return reads;
-    },
-  });
+  // 只读符号查询工具（find-definition / find-reference / inspect）与 opencode 共享；
+  // 它们由 manager 的 onEnabled 回调注册，不在这里注册。
 }
 
 /** 会更新 reads state 并随 details 持久化快照的工具名。 */
@@ -720,10 +710,34 @@ function restoreFileReads(
  * state 归本文件所有：扩展实例内创建，并随 session 事件从历史分支恢复，
  * 与主进程 index.ts 聚合加载时的行为一致。
  */
-export default function claudeCodeFileTools(pi: ExtensionAPI): void {
-  const service = registerLsp(pi);
+export default function claudeCodeFileTools(pi: ExtensionAPI, options?: LspServiceOptions): void {
   const state = createClaudeCodeState();
 
+  // LSP 专属工具（lsp-rename / inspect 族）仅在 lsp.json 存在 enabled 服务器时
+  // 注册（session_start 校验后）；本工具集跟踪 read-before-write 状态，rename
+  // 落盘的文件要标记为已读并随 details 持久化（restoreFileReads 依赖 details.reads）。
+  const manager = createLspManager(
+    pi,
+    {
+      onEnabled: (pi, service) => {
+        registerLspRenameTool(pi, service, {
+          recordReads: async (applied) => {
+            const reads: Record<string, FileSnapshot> = {};
+            for (const fileEdit of applied) {
+              const key = await readStateKey(fileEdit.path);
+              const snapshot = snapshotOf(fileEdit.newText);
+              state.reads.set(key, snapshot);
+              reads[key] = snapshot;
+            }
+            return reads;
+          },
+        });
+        registerLspInspectTools(pi, service);
+      },
+    },
+    options,
+  );
+
   // 扩展实例在进程启动 / /reload / /new / /resume / /fork 时重建，内存里的
   // 已读记账随之丢失。这里从当前分支的历史工具结果里恢复：digest 是当时的值，
   // 若文件在此期间被外部修改，Edit/Write 时的指纹对比仍会要求重新 Read，
@@ -739,5 +753,6 @@ export default function claudeCodeFileTools(pi: ExtensionAPI): void {
     restoreFileReads(state, ctx.sessionManager);
   });
 
-  registerFileTools(pi, state, service);
+  // 文件工具无条件注册；service 惰性获取，disabled 时为 no-op。
+  registerFileTools(pi, state, () => manager.mustLazyGetService());
 }

package/src/claude-code/glob.ts

@@ -34,7 +34,7 @@ function extractGlobBaseDirectory(pattern: string): {
 } {
   const globChars = /[*?[{]/;
   const match = globChars.exec(pattern);
-  if (!match || match.index === undefined) {
+  if (!match) {
     // 无 glob 特殊字符：字面路径，目录部分作为 baseDir
     return { baseDir: dirname(pattern), relativePattern: basename(pattern) };
   }

package/src/gh-readonly.ts

@@ -122,12 +122,12 @@ export function runGh(
       timeoutId = setTimeout(() => killProcess("timeout"), timeout);
     }
 
-    proc.stdout?.on("data", (data: Buffer) => {
+    proc.stdout.on("data", (data: Buffer) => {
       const text = data.toString();
       stdout += text;
       combined.push(text);
     });
-    proc.stderr?.on("data", (data: Buffer) => {
+    proc.stderr.on("data", (data: Buffer) => {
       const text = data.toString();
       stderr += text;
       combined.push(text);
@@ -793,7 +793,7 @@ export async function renderStepLog(
   const totalLines = clean.split("\n").length;
   let logToShow = clean;
   let appliedOffset = false;
-  if (offset !== undefined && offset !== null && offset > 1) {
+  if (offset !== undefined && offset > 1) {
     if (offset > totalLines) {
       return {
         content: [
@@ -867,7 +867,7 @@ export async function renderJobLogs(
 ): Promise<CiLogsResult> {
   const { job, offset, limit, full } = params;
 
-  if (!jobs || jobs.length === 0) {
+  if (jobs.length === 0) {
     return {
       content: [{ type: "text", text: `No jobs found for run ${params.runId}` }],
       details: {},
@@ -923,7 +923,7 @@ export async function renderJobLogs(
 
         // Apply offset on the cleaned text, then truncate.
         let logToShow = clean;
-        if (offset !== undefined && offset !== null && offset > 1) {
+        if (offset !== undefined && offset > 1) {
           if (offset > totalLines) {
             steps.push({ name: s.name });
             continue;
@@ -1037,9 +1037,12 @@ export async function writeLogFile(
 
   let content: string;
   let what: string;
-  if (step !== undefined && step !== null) {
+  if (step === undefined) {
+    content = stripAnsi(rawLog);
+    what = `job "${targetJob.name}" (id: ${targetJob.id})`;
+  } else {
     const found = targetJob.steps.find((s) => s.name.toLowerCase() === step.toLowerCase());
-    if (!found) {
+    if (found === undefined) {
       return {
         content: [
           {
@@ -1064,9 +1067,6 @@ export async function writeLogFile(
     }
     content = cleanStepOutput(stepLog);
     what = `step ${found.number} ("${found.name}") of job "${targetJob.name}"`;
-  } else {
-    content = stripAnsi(rawLog);
-    what = `job "${targetJob.name}" (id: ${targetJob.id})`;
   }
 
   const target = resolve(cwd ?? process.cwd(), outputFile);
@@ -1480,7 +1480,7 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
         getJobLog(String(run_id), jobId, effectiveRepo, signal, ctx.cwd, params);
 
       // ── Write the complete log to a file ───────────────────────────────
-      if (output_file !== undefined && output_file !== null && output_file !== "") {
+      if (output_file !== undefined && output_file !== "") {
         const result = await writeLogFile(
           { runId: String(run_id), job, step, outputFile: output_file },
           jobs,
@@ -1492,7 +1492,7 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
       }
 
       // ── Fetch a specific step's logs (requires `job`) ─────────────────
-      if (step !== undefined && step !== null) {
+      if (step !== undefined) {
         onUpdate?.({
           content: [{ type: "text", text: `Fetching job list...` }],
           details: {},

package/src/lib/cli.ts

@@ -238,7 +238,7 @@ export function parseCommand<TFlags extends TObject>(
       } else if (info.kind === "boolean") {
         rawFlags[info.key] = true;
       } else {
-        const next = tokens[i + 1];
+        const next = tokens.at(i + 1);
         if (next !== undefined && !looksLikeFlag(next)) {
           rawFlags[info.key] = next;
           i++;
@@ -266,7 +266,7 @@ export function parseCommand<TFlags extends TObject>(
         } else if (j + 1 < rest.length) {
           rawFlags[info.key] = rest.slice(j + 1);
         } else {
-          const next = tokens[i + 1];
+          const next = tokens.at(i + 1);
           if (next !== undefined && !looksLikeFlag(next)) {
             rawFlags[info.key] = next;
             i++;
@@ -327,10 +327,7 @@ export function parseCommand<TFlags extends TObject>(
     parsed = Value.Convert(spec.flags, Value.Clone(parsed));
     if (!Value.Check(spec.flags, parsed)) {
       const [first] = [...Value.Errors(spec.flags, parsed)];
-      return errorResult(
-        spec,
-        `Invalid arguments: ${first?.message ?? "value does not match flags"}`,
-      );
+      return errorResult(spec, `Invalid arguments: ${first.message}`);
     }
   } catch {
     return errorResult(spec, "Invalid arguments");

package/src/lib/lsp/client.ts

@@ -20,7 +20,14 @@ import {
   StreamMessageReader,
   StreamMessageWriter,
 } from "vscode-jsonrpc/node";
-import type { Diagnostic as VSCodeDiagnostic, WorkspaceEdit } from "vscode-languageserver-types";
+import type {
+  Diagnostic as VSCodeDiagnostic,
+  Hover,
+  Location as LspLocation,
+  LocationLink,
+  Range,
+  WorkspaceEdit,
+} from "vscode-languageserver-types";
 
 import type { LspServerHandle } from "./adapter.js";
 import { LANGUAGE_EXTENSIONS } from "./language.js";
@@ -72,6 +79,20 @@ const LSP_CONTENT_MODIFIED = -32801;
  */
 export class RenameNotPossibleError extends Error {}
 
+/**
+ * 服务器不支持某 LSP 方法（MethodNotFound）。与传输失败区分，供服务层跳过
+ * 该服务器尝试下一个，而不是把整个操作当作失败。
+ */
+export class LspMethodNotSupportedError extends Error {
+  readonly serverID: string;
+  readonly method: string;
+  constructor(serverID: string, method: string) {
+    super(`LSP server "${serverID}" does not support ${method}`);
+    this.serverID = serverID;
+    this.method = method;
+  }
+}
+
 /**
  * rename edit 未覆盖 references 看到的全部文件：服务器索引可能仍在后台加载。
  * 抛出时发生在写盘之前，整个 rename 无副作用，可稍后重试。
@@ -148,6 +169,50 @@ export interface RenameSymbolResult {
   placeholder?: string;
 }
 
+/** definition / references / hover 请求的输入（line / character 为 0-based LSP position）。 */
+export interface InspectPositionRequest {
+  path: string;
+  line: number;
+  character: number;
+}
+
+/** definition / references 归一化后的位置（0-based；1-based 格式化由工具层负责）。 */
+export interface InspectLocation {
+  path: string;
+  line: number;
+  character: number;
+}
+
+type DefinitionResult = LspLocation | LspLocation[] | LocationLink | LocationLink[] | null;
+
+/** Location / LocationLink → path + 0-based 坐标；非 file: URI 是服务器的意外行为，跳过。 */
+function toInspectLocations(result: DefinitionResult): InspectLocation[] {
+  if (result === null) return [];
+  const items = Array.isArray(result) ? result : [result];
+  const locations: InspectLocation[] = [];
+  for (const item of items) {
+    if ("targetUri" in item) {
+      if (!item.targetUri.startsWith("file:")) continue;
+      const range =
+        (item as Omit<LocationLink, "targetSelectionRange"> & { targetSelectionRange?: Range })
+          .targetSelectionRange ?? item.targetRange;
+      locations.push({
+        path: normalize(fileURLToPath(item.targetUri)),
+        line: range.start.line,
+        character: range.start.character,
+      });
+    } else {
+      if (!item.uri.startsWith("file:")) continue;
+      locations.push({
+        path: normalize(fileURLToPath(item.uri)),
+        line: item.range.start.line,
+        character: item.range.start.character,
+      });
+    }
+  }
+  return locations;
+}
+
 export class InitializeError extends Error {
   readonly serverID: string;
   constructor(serverID: string, cause: unknown) {
@@ -241,6 +306,21 @@ export interface LspClient {
    * 位置不在符号上 / 服务器不支持 rename 时抛 RenameNotPossibleError。
    */
   renameSymbol(request: RenameSymbolRequest): Promise<RenameSymbolResult>;
+  /**
+   * textDocument/definition：归一化后的定义位置列表（Location / LocationLink
+   * 统一转 path + 0-based 坐标；无结果返回空数组）。
+   */
+  definition(request: InspectPositionRequest): Promise<InspectLocation[]>;
+  /**
+   * textDocument/references：归一化后的引用位置列表（是否含声明处由服务器
+   * 按 includeDeclaration 决定，此处固定包含，对齐 rename 覆盖校验口径）。
+   */
+  references(request: InspectPositionRequest): Promise<InspectLocation[]>;
+  /**
+   * textDocument/hover：服务器返回的 contents 原样透传，不做内容归一化；
+   * 服务器无信息时返回 null（合法应答，非错误）。
+   */
+  hover(request: InspectPositionRequest): Promise<Hover | null>;
   shutdown(): Promise<void>;
 }
 
@@ -347,7 +427,7 @@ export async function create(input: CreateInput): Promise<LspClient> {
     new StreamMessageReader(input.server.process.stdout),
     new StreamMessageWriter(input.server.process.stdin),
   );
-  input.server.process.stderr?.resume();
+  input.server.process.stderr.resume();
   /** 连接或服务器进程已关闭；pull 重试循环以此终止，避免无界等待。 */
   let connectionClosed = false;
   input.server.process.once("exit", () => {
@@ -504,7 +584,7 @@ export async function create(input: CreateInput): Promise<LspClient> {
     await connection.sendNotification("workspace/didChangeConfiguration", { settings });
   }
 
-  const files: Record<string, { version: number; text: string }> = {};
+  const files: Record<string, { version: number; text: string } | undefined> = {};
 
   // ── 驻留 LRU ────────────────────────────────────────────────────────────────
 
@@ -746,16 +826,16 @@ export async function create(input: CreateInput): Promise<LspClient> {
     if (timeout <= 0) return Promise.resolve(false);
     return new Promise<boolean>((resolve) => {
       let finished = false;
+      const timer = setTimeout(() => finish(false), timeout);
       const finish = (result: boolean) => {
         if (finished) return;
         finished = true;
-        if (timer) clearTimeout(timer);
+        clearTimeout(timer);
         registrationListeners.delete(listener);
         resolve(result);
       };
       const listener = () => finish(true);
       registrationListeners.add(listener);
-      const timer = setTimeout(() => finish(false), timeout);
     });
   }
 
@@ -769,12 +849,14 @@ export async function create(input: CreateInput): Promise<LspClient> {
     return new Promise<boolean>((resolve) => {
       let finished = false;
       let debounceTimer: ReturnType<typeof setTimeout> | undefined;
+      const timeoutTimer = setTimeout(() => finish(false), request.timeout);
+      const unsub = () => diagnosticListeners.delete(listener);
       const finish = (result: boolean) => {
         if (finished) return;
         finished = true;
         if (debounceTimer) clearTimeout(debounceTimer);
-        if (timeoutTimer) clearTimeout(timeoutTimer);
-        unsub?.();
+        clearTimeout(timeoutTimer);
+        unsub();
         resolve(result);
       };
       const schedule = () => {
@@ -789,13 +871,11 @@ export async function create(input: CreateInput): Promise<LspClient> {
         );
       };
 
-      const timeoutTimer = setTimeout(() => finish(false), request.timeout);
       const listener = (event: { path: string; serverID: string }) => {
         if (event.path !== request.path || event.serverID !== input.serverID) return;
         schedule();
       };
       diagnosticListeners.add(listener);
-      const unsub = () => diagnosticListeners.delete(listener);
       schedule();
     });
   }
@@ -922,6 +1002,31 @@ export async function create(input: CreateInput): Promise<LspClient> {
     return 0;
   };
 
+  // ── 只读符号查询（definition / references / hover）──────────────────────────
+
+  /** 请求前先同步磁盘内容（didOpen/didChange），保证服务器基于最新文本应答。 */
+  const preparePositionRequest = async (request: InspectPositionRequest) => {
+    const resolvedPath = normalize(
+      isAbsolute(request.path) ? request.path : resolve(input.directory, request.path),
+    );
+    await openDocument({ path: resolvedPath });
+    return {
+      uri: pathToFileURL(resolvedPath).href,
+      position: { line: request.line, character: request.character },
+    };
+  };
+
+  const sendInspectRequest = async <T>(method: string, message: object): Promise<T> => {
+    try {
+      return await retryOnContentModified(() => connection.sendRequest<T>(method, message));
+    } catch (error) {
+      if (error instanceof ResponseError && error.code === LSP_METHOD_NOT_FOUND) {
+        throw new LspMethodNotSupportedError(input.serverID, method);
+      }
+      throw error;
+    }
+  };
+
   return {
     root: input.root,
     get serverID() {
@@ -1101,6 +1206,31 @@ export async function create(input: CreateInput): Promise<LspClient> {
         current = toPaths(await referencesRequest());
       }
     },
+    async definition(request: InspectPositionRequest): Promise<InspectLocation[]> {
+      const { uri, position } = await preparePositionRequest(request);
+      return toInspectLocations(
+        await sendInspectRequest<DefinitionResult>("textDocument/definition", {
+          textDocument: { uri },
+          position,
+        }),
+      );
+    },
+    async references(request: InspectPositionRequest): Promise<InspectLocation[]> {
+      const { uri, position } = await preparePositionRequest(request);
+      const locations = await sendInspectRequest<LspLocation[] | null>("textDocument/references", {
+        textDocument: { uri },
+        position,
+        context: { includeDeclaration: true },
+      });
+      return toInspectLocations(locations);
+    },
+    async hover(request: InspectPositionRequest): Promise<Hover | null> {
+      const { uri, position } = await preparePositionRequest(request);
+      return await sendInspectRequest<Hover | null>("textDocument/hover", {
+        textDocument: { uri },
+        position,
+      });
+    },
     get diagnostics() {
       const result = new Map<string, Diagnostic[]>();
       for (const key of new Set([...pushDiagnostics.keys(), ...pullDiagnostics.keys()])) {