1st-pi 0.3.3 → 0.3.4

package/README.md

@@ -8,7 +8,15 @@
 
 ## 安装
 
-需要 Pi `>=1.1.0`；`@tintinweb/pi-subagents` 0.20 起要求该版本，`pi-btw` 0.7 起要求 `>=0.85.1`。
+需要 Pi `>=1.1.0`；`@tintinweb/pi-subagents` 0.20 起要求该版本，`pi-btw` 0.7 起要求 `>=0.85.1`。`pi-web-access` 0.44 要求 Node `>=22.19.0`。
+
+macOS 上 `pi-readseek` 的原生二进制动态链接 Homebrew 库，缺少任意一个时 `read`/`edit`/`write` 会因 dyld 报错失败（0.11 起新增 `ftxui`，0.12.1 起新增 `re2`）：
+
+```bash
+brew install abseil fmt ftxui gettext glib openssl@4 re2 vips xxhash
+```
+
+preset 的 readseek adapter 会在启动时读取该二进制的 Mach-O load commands，若有 dylib 缺失，就在 session 开始时给出 warning 和对应的 `brew install` 命令（会遵循 `READSEEK_BINARY` 覆盖）。
 
 ### GitHub
 
@@ -131,7 +139,7 @@ Preset 默认开启以下 TUI 增强，session 中持久化的个人选择优先
 | [@juicesharp/rpiv-ask-user-question](https://www.npmjs.com/package/@juicesharp/rpiv-ask-user-question) | 多问题、选项预览和自由输入的结构化提问 UI |
 | [@narumitw/pi-goal](https://www.npmjs.com/package/@narumitw/pi-goal) | Session-scoped `/goal` 持续执行与完成/阻塞门禁；可选 experimental ordered-goal queue |
 | [@ff-labs/pi-fff](https://www.npmjs.com/package/@ff-labs/pi-fff) | 本地 Rust 模糊文件/内容搜索与 `@` 自动补全；`find`/`grep` 支持 workspace-relative 约束和 workspace 外的绝对路径 |
-| [pi-readseek](https://www.npmjs.com/package/pi-readseek) | Parser-backed code map/search、PDF index/view、definition/reference、hashline edit 与 workspace rename；其 edit 可进行带警告的 fuzzy anchor relocation，不等同于严格 stale rejection |
+| [pi-readseek](https://www.npmjs.com/package/pi-readseek) | Parser-backed code map/search、PDF index/view、definition/reference、syntax check、hashline edit 与 workspace rename；caption/OCR/object detection 只在显式调用对应工具时使用本地已安装模型，不会自动下载；其 edit 可进行带警告的 fuzzy anchor relocation，不等同于严格 stale rejection |
 | [pi-btw](https://www.npmjs.com/package/pi-btw) | 不污染主上下文的并行 `/btw` 旁路对话 |
 | [@mrclrchtr/supi-context](https://www.npmjs.com/package/@mrclrchtr/supi-context) | `/supi-context` 上下文组成与 token 占用报告 |
 | [@tintinweb/pi-subagents](https://www.npmjs.com/package/@tintinweb/pi-subagents) | Claude Code 风格 sub-agents |
@@ -140,7 +148,7 @@ Preset 默认开启以下 TUI 增强，session 中持久化的个人选择优先
 
 这些包位于普通 npm `dependencies`，安装 preset 时由 npm 获取，不会塞入 `1st-pi` tarball。`extensions/packages/*.ts` 是只负责调用 dependency extension entrypoint 的 thin adapters；因此依赖可以正常 hoist，同时 Pi manifest 只引用本包内稳定路径。FFF 也会由 npm 在 macOS、Linux 和 Windows 上选择正确的原生 binary。
 
-当前 dependency extension 版本以 `package.json` 与 lockfile 为准；维护时使用 npm `latest` 稳定标签，并通过 `npm outdated` 确认没有落后版本。
+当前 dependency extension 版本以 `package.json` 与 lockfile 为准；维护时使用 npm `latest` 稳定标签，并运行 `npm run check:outdated` 确认没有落后版本。该检查会指出 `package.json` 范围挡住最新版的依赖（例如 `^0.20.0` 不包含 0.21.0，`npm install` 不会提示），以及 lockfile 落后于范围的依赖。
 
 Themes 以及 `pi-init` skill 是发布所需的静态资源，会从锁定依赖同步到本包。`pi-web-access` 从 0.14.0 起不再提供 `librarian` skill，preset 同步移除该过期副本，保留 extension 自身的搜索、抓取与 source-check surface。更新 dependencies 后运行：
 
@@ -190,6 +198,14 @@ Tool Call Markers 默认分组相邻调用并折叠工具详情；可用 `PI_TOO
 
 该 SOP 覆盖 license/compatibility/ownership gate、thin adapter、README 同步、hoisted npm 安装、native binary、tarball size 与 clean-room smoke tests。
 
+`npm run smoke` 在隔离的 `PI_CODING_AGENT_DIR` 中通过 Pi SDK 加载 preset，不访问网络、不调用模型，检查：
+
+- 扩展加载无错误且与 `package.json#pi.extensions` 一致；工具无重名 owner；`read/edit/write`、`grep/find`、`bash/ls` 的 owner 符合上文
+- 全新安装时写入 preset 默认值，已有的显式 `subagents.json` / workflow 设置保持不变
+- `pi-tasks` 与 `pi-subagents` 的 RPC 协议版本匹配
+- readseek 在临时文件上执行 read → anchored edit → write，以及 macOS dylib 检测与 `otool -L` 一致
+- 工具与命令集合与 `scripts/smoke-surface.json` 快照一致；有意变更时用 `npm run smoke -- --update` 更新快照，并在 diff 中审阅
+
 ## 发布
 
 ```bash
@@ -197,9 +213,11 @@ npm login
 npm publish
 ```
 
-发布前建议检查包内容：
+发布前建议运行检查并确认包内容：
 
 ```bash
+npm run check:outdated
+npm run smoke
 npm pack --dry-run
 ```
 

package/extensions/packages/readseek-dylibs.ts

@@ -0,0 +1,109 @@
+import { closeSync, existsSync, openSync, readSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+
+const MH_MAGIC_64 = 0xfeedfacf;
+const FAT_MAGIC = 0xcafebabe;
+const CPU_TYPE_BY_ARCH: Record<string, number> = { arm64: 0x0100000c, x64: 0x01000007 };
+const LC_LOAD_DYLIB = 0x0c;
+const LC_LOAD_WEAK_DYLIB = 0x80000018;
+const LC_REEXPORT_DYLIB = 0x8000001f;
+const LC_LOAD_UPWARD_DYLIB = 0x80000023;
+const DYLIB_COMMANDS = new Set([LC_LOAD_DYLIB, LC_LOAD_WEAK_DYLIB, LC_REEXPORT_DYLIB, LC_LOAD_UPWARD_DYLIB]);
+const BREW_FORMULA = /^(?:\/opt\/homebrew|\/usr\/local)\/opt\/([^/]+)\//;
+
+function readAt(fd: number, position: number, length: number): Buffer {
+  const buffer = Buffer.alloc(length);
+  return buffer.subarray(0, readSync(fd, buffer, 0, length, position));
+}
+
+/**
+ * Reads only the 64-bit Mach-O header and load commands for `arch`, selecting
+ * the matching slice of a universal binary. Returns undefined for other formats.
+ */
+export function readMachOLoadCommands(path: string, arch: string = process.arch): Buffer | undefined {
+  const fd = openSync(path, "r");
+  try {
+    let offset = 0;
+    const head = readAt(fd, 0, 4096);
+    if (head.length >= 8 && head.readUInt32BE(0) === FAT_MAGIC) {
+      const count = head.readUInt32BE(4);
+      const slice = Array.from({ length: count }, (_, i) => 8 + i * 20)
+        .find((at) => at + 20 <= head.length && head.readUInt32BE(at) === CPU_TYPE_BY_ARCH[arch]);
+      if (slice === undefined) return undefined;
+      offset = head.readUInt32BE(slice + 8);
+    }
+    const header = readAt(fd, offset, 32);
+    if (header.length < 32 || header.readUInt32LE(0) !== MH_MAGIC_64) return undefined;
+    return readAt(fd, offset, 32 + header.readUInt32LE(20));
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** Returns the dylib install names linked by a thin 64-bit Mach-O header plus its load commands. */
+export function machODylibs(binary: Buffer): string[] {
+  if (binary.length < 32 || binary.readUInt32LE(0) !== MH_MAGIC_64) return [];
+
+  const commandCount = binary.readUInt32LE(16);
+  const dylibs: string[] = [];
+  let at = 32;
+  for (let i = 0; i < commandCount && at + 8 <= binary.length; i++) {
+    const cmd = binary.readUInt32LE(at);
+    const size = binary.readUInt32LE(at + 4);
+    if (size < 8) break;
+    if (DYLIB_COMMANDS.has(cmd)) {
+      const nameStart = at + binary.readUInt32LE(at + 8);
+      const nameEnd = binary.indexOf(0, nameStart);
+      dylibs.push(binary.toString("utf8", nameStart, nameEnd < 0 || nameEnd > at + size ? at + size : nameEnd));
+    }
+    at += size;
+  }
+  return dylibs;
+}
+
+/**
+ * Dylibs that dyld would fail to load. System libraries live in the dyld shared
+ * cache rather than on disk, and `@rpath`-style names are relative, so only
+ * other absolute paths can be checked.
+ */
+export function missingDylibs(dylibs: string[], exists: (path: string) => boolean = existsSync): string[] {
+  return dylibs.filter(
+    (dylib) => dylib.startsWith("/") && !dylib.startsWith("/usr/lib/") && !dylib.startsWith("/System/") && !exists(dylib),
+  );
+}
+
+export function missingDylibsMessage(missing: string[]): string {
+  const formulas = [...new Set(missing.map((dylib) => BREW_FORMULA.exec(dylib)?.[1]).filter((f): f is string => !!f))];
+  const unknown = missing.filter((dylib) => !BREW_FORMULA.test(dylib));
+  const lines = ["pi-readseek's native binary is missing shared libraries, so read/edit/write will fail until they are installed."];
+  if (formulas.length > 0) lines.push(`Run: brew install ${formulas.join(" ")}`);
+  if (unknown.length > 0) lines.push(`Missing: ${unknown.join(", ")}`);
+  return lines.join("\n");
+}
+
+/** Mirrors pi-readseek's own lookup: READSEEK_BINARY, then the platform package beside @jarkkojs/readseek. */
+export function resolveReadseekBinary(): string | undefined {
+  const override = process.env.READSEEK_BINARY;
+  if (override) return override;
+  if (process.platform !== "darwin") return undefined;
+  try {
+    const require = createRequire(createRequire(import.meta.url).resolve("pi-readseek"));
+    const metaDir = dirname(require.resolve("@jarkkojs/readseek/package.json"));
+    const platformJson = require.resolve(`@jarkkojs/readseek-darwin-${process.arch}/package.json`, { paths: [metaDir] });
+    return join(dirname(platformJson), "bin", "readseek");
+  } catch {
+    // pi-readseek reports a missing platform package itself.
+    return undefined;
+  }
+}
+
+/** Returns a warning when the readseek binary cannot load on this machine, otherwise undefined. */
+export function readseekDylibWarning(): string | undefined {
+  if (process.platform !== "darwin") return undefined;
+  const binary = resolveReadseekBinary();
+  if (!binary || !existsSync(binary)) return undefined;
+  const commands = readMachOLoadCommands(binary);
+  const missing = commands ? missingDylibs(machODylibs(commands)) : [];
+  return missing.length > 0 ? missingDylibsMessage(missing) : undefined;
+}

package/extensions/packages/readseek.ts

@@ -1,10 +1,21 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import registerReadseek from "pi-readseek";
+import { readseekDylibWarning } from "./readseek-dylibs.ts";
 import { registerWithToolTransform } from "./tool-registration-transform.ts";
 
 const READSEEK_GREP_PREFERENCE = "Prefer readSeek_grep over grep when both are available;";
 
 export default function readseekAdapter(pi: ExtensionAPI): void {
+  // The macOS binary links Homebrew dylibs it does not ship; surface the exact
+  // brew command up front instead of a dyld crash on the first read.
+  const dylibWarning = readseekDylibWarning();
+  if (dylibWarning) {
+    pi.on("session_start", async (_event, ctx) => {
+      if (ctx.hasUI) ctx.ui.notify(dylibWarning, "warning");
+      else console.warn(dylibWarning);
+    });
+  }
+
   registerWithToolTransform(pi, registerReadseek, (tool) => {
     if (tool.name !== "readSeek_grep") return tool;
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "1st-pi",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "est7's Pi coding agent preset — skills, extensions, prompts, and themes.",
   "license": "MIT",
   "author": "est7",
@@ -33,23 +33,25 @@
   "homepage": "https://github.com/est7/1st-pi#readme",
   "dependencies": {
     "@ff-labs/pi-fff": "^0.11.0",
-    "@juicesharp/rpiv-ask-user-question": "^2.12.0",
-    "@mrclrchtr/supi-context": "^8.0.1",
-    "@narumitw/pi-goal": "^0.54.11",
+    "@juicesharp/rpiv-ask-user-question": "^2.15.0",
+    "@mrclrchtr/supi-context": "^11.0.1",
+    "@narumitw/pi-goal": "^0.54.13",
     "@pi-kaush/pi-tool-call-markers": "^0.3.19",
     "@quintinshaw/pi-dynamic-workflows": "^3.14.0",
-    "@tintinweb/pi-subagents": "^0.20.0",
-    "@tintinweb/pi-tasks": "^0.9.0",
-    "pi-btw": "^0.7.1",
+    "@tintinweb/pi-subagents": "^0.22.0",
+    "@tintinweb/pi-tasks": "^0.9.1",
+    "pi-btw": "^0.8.0",
     "pi-everforest-tui": "^0.2.1",
     "pi-init": "^1.0.0",
-    "pi-readseek": "^0.10.4",
+    "pi-readseek": "^0.12.3",
     "pi-session-name": "^0.1.7",
-    "pi-web-access": "^0.38.0"
+    "pi-web-access": "^0.44.0"
   },
   "scripts": {
     "sync:resources": "node scripts/sync-package-resources.mjs",
     "check:resources": "node scripts/sync-package-resources.mjs --check",
+    "check:outdated": "node scripts/check-outdated.mjs",
+    "smoke": "node scripts/smoke.mjs",
     "prepack": "npm run check:resources",
     "pack:dry-run": "npm pack --dry-run --json"
   },

package/skills/add-extension-to-1st-agent/SKILL.md

@@ -67,11 +67,15 @@ Run:
 
 ```bash
 npm run check:resources
+npm run check:outdated
+npm run smoke
 npm audit --omit=dev
 npm pack --dry-run --json
 git diff --check
 ```
 
+`npm run smoke` fails when the tool or command surface differs from `scripts/smoke-surface.json`. Review the reported additions and removals against the intended change, then run `npm run smoke -- --update` and commit the snapshot with the dependency change. When adding a preset default or ownership rule, extend `scripts/smoke.mjs` with the fresh-install and explicit-preference cases.
+
 Then verify:
 
 1. local source: `pi --no-extensions -e .`