pier-setup 0.2.5 → 0.2.7

package/README.md

@@ -90,12 +90,39 @@ herdr plugin link ./packages/pier-workbench                        # development
 
 The extension degrades gracefully outside a herdr environment (see Scope below).
 
-### Scope (only the herdr × pi intersection is affected)
+### Scope (what the pi extension mutates)
+
+`pi-pier` is not dormant outside herdr. After install it is live in every pi session:
+
+| Surface | Bare `pi` | Inside herdr |
+|---|---|---|
+| `todo_write`, `/todos`, widget, anti-freeze, stop reminder | live | live |
+| `ask_user_question` | live | live + blocked marker |
+| Hidden inject (`before_agent_start` todo-read; settle reminder) | live | live |
+| `subagent`, `terminal` | **not registered** | live |
+| `/locks`, write-lock, slim-frame, pane title, pipe | off | live |
+| `setActiveTools` role visible layer | off | on (herdr master) |
+
+Session JSONL custom types (`pi-herdr.todo-edit`, `.subs`, `.terminals`, `.todo-read`, `.todo-reminder`, …) persist across `/resume` even without herdr.
+
+### Plugin conflicts
+
+pi overwrites tools/commands by name; event listeners stack. Two todo or subagent plugins will silently replace each other.
+
+**Do not install alongside** (same-name overwrite → wrong handler, split JSONL):
+
+- [`@nguyenquangthai/pi-todo`](https://pi.dev/packages/@nguyenquangthai/pi-todo) — `todo_write` + overlay
+- [`@josephyoung/pi-ask-user-question`](https://pi.dev/packages/@josephyoung/pi-ask-user-question) — `ask_user_question`
+- [`pi-herdr-subagents`](https://pi.dev/packages/pi-herdr-subagents) — `subagent` + herdr panes
+
+**Soft conflict** (two orchestrators / two injectors — the agent “talks to itself”):
+
+- [`@tintinweb/pi-subagents`](https://pi.dev/packages/@tintinweb/pi-subagents) (`Agent`)
+- [`@minhduydev/pi-subagents`](https://pi.dev/packages/@minhduydev/pi-subagents) (`task`)
+- any other extension that calls `setActiveTools`, `ui.custom` overlay, `before_agent_start`, or `sendUserMessage`/`sendMessage` followUp
+
+**Designed coexistence:** herdr’s official `herdr:pi` reporter. Keep it. pier emits `herdr:blocked` so that plugin remains lifecycle authority.
 
-- **pi outside herdr**: the extension degrades — reporting is free, workbench tools
-  (`subagent`, terminal family) return a clear "requires a herdr-managed pane" error;
-  `todo_write` / `ask_user_question` stay available (session JSONL is the authority,
-  no herdr dependency).
 - **other agents inside herdr (claude code / codex etc.)**: tabs without a pi pane
   are excluded from heat reflow; blocked notifications are pi-only; master-tab
   auto-bootstrap can be disabled with `autoBootstrap: false` in boot-config.

package/install.mjs

@@ -86,8 +86,17 @@ function which(bin) {
   }
 }
 
-function run(cmd, args) {
-  return execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+function run(cmd, args, opts = {}) {
+  // win32: npm 全局 bin 是 .cmd shim，无 shell 直接 spawn 会 ENOENT/EINVAL，须走 cmd.exe；
+  // 且 shell:true 时 Node 把 args 按空格裸拼接（不加引号），含空格的路径参数会被拆碎，故预拼接并加引号。
+  // POSIX 走原生分支，保持 execFileSync(cmd, args) 原语义。
+  if (IS_WIN) {
+    const cmdline = [cmd, ...args]
+      .map((a) => (/[\s"]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a))
+      .join(' ');
+    return execFileSync(cmdline, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], shell: true, ...opts }).trim();
+  }
+  return execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], ...opts }).trim();
 }
 
 function tryRun(cmd, args) {
@@ -126,9 +135,7 @@ function readPkgVersion(dir) {
 
 function npmLatest(name) {
   try {
-    return execFileSync('npm', ['view', name, 'version'], {
-      encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 15000,
-    }).trim();
+    return run('npm', ['view', name, 'version'], { timeout: 15000 });
   } catch {
     return null;
   }
@@ -185,6 +192,25 @@ function piAgentDir() {
   return process.env.PI_CODING_AGENT_DIR || join(homedir(), '.pi', 'agent');
 }
 
+/* ── 旧版 git 模式注册迁移 ──────────────────────────────────────── */
+// 早期 `pi install git:github.com/July24/pier` 的遗留注册与 npm:pi-pier 并存时，
+// 两份扩展会注册同名工具（todo_write / ask_user_question…），pi 启动即报 conflict。
+const LEGACY_GIT_SPEC = 'git:github.com/July24/pier';
+
+function registeredPiPackages() {
+  try {
+    return JSON.parse(readFileSync(join(piAgentDir(), 'settings.json'), 'utf8'))?.packages ?? [];
+  } catch { return []; }
+}
+
+/** install/update 前清理旧 git 模式注册；--pi-spec 显式指定该 git 源时视为目标源，不动。 */
+function removeLegacyGitRegistration() {
+  if (piSource() === LEGACY_GIT_SPEC) return;
+  if (!registeredPiPackages().includes(LEGACY_GIT_SPEC)) return;
+  if (tryRun('pi', ['remove', LEGACY_GIT_SPEC])) log(`✓ removed legacy git-mode registration (${LEGACY_GIT_SPEC}); using ${piSource()}`);
+  else { console.error('✗ failed to remove legacy git-mode registration'); log(`  manual: pi remove ${LEGACY_GIT_SPEC}`); process.exitCode = 1; }
+}
+
 function npmNameFromSpec(spec) {
   if (!spec.startsWith('npm:')) return null;
   const rest = spec.slice(4);
@@ -358,6 +384,7 @@ function version() {
 
 function update() {
   checkEnv();
+  removeLegacyGitRegistration();
   const me = readPkgVersion(ROOT);
   const latestSetup = npmLatest('pier-setup');
   if (latestSetup && me && cmpSemver(me, latestSetup) < 0) {
@@ -383,6 +410,7 @@ function install() {
   const hmrDev = flags.has('--hmr-dev');
   const force = flags.has('--force');
   checkEnv();
+  removeLegacyGitRegistration();
 
   if (dev) {
     if (tryRun('pi', ['install', piSource()])) log('✓ pi extension installed (packages/pier-ext, local)');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pier-setup",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "One-shot installer for pier: install / update / version / uninstall for pi-pier + pier.workbench",
   "license": "MIT",
   "type": "module",