@falling-ts/pi-start-command 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 falling-ts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# pi-start-command
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+pi 扩展：在会话真正开始前运行一条配置好的启动命令。参考 [dsh-start-command](https://github.com/falling-ts/dsh-start-command)（DSH 同名插件）移植到 pi 扩展 API。
+
+## 工作原理
+
+挂点为 `before_agent_start`：pi 会 await 全部 handler 之后才组装并派发模型请求，因此在这里 await 命令即满足「先跑命令、再发请求」。命令完成后本轮 prompt 才到达模型。
+
+触发条件（全部满足才运行）：
+
+1. 配置了命令（`PI_START_COMMAND` 未设或空白时插件完全静默，零副作用）；
+2. `event.messageType === "user"`——只对用户提交的 prompt 生效。pi v1.2.0 起 `before_agent_start` 也会为 `pi.sendMessage(..., { triggerTurn: true })` 触发（`"custom"` 变体），程序化启动的 run 不算「用户发起了会话」；
+3. `before_agent_start` 是 run 级事件，一轮内的后续工具循环步不会再次进入，天然幂等。
+
+失败策略：任何失败（非零退出、超时、spawn 失败）只经 `ctx.ui.notify` 告知并放行，绝不抛进事件分发——启动命令必须无法破坏模型请求。
+
+## 配置（环境变量）
+
+| 变量 | 说明 | 默认 |
+| --- | --- | --- |
+| `PI_START_COMMAND` | 要运行的命令行；未设或空白则插件完全静默 | （未配置） |
+| `PI_START_COMMAND_TIMEOUT_MS` | 超时毫秒数，到点 kill 进程并放行 | `10000` |
+| `PI_START_COMMAND_QUIET` | 设为 `1` 时成功也不弹通知，只报失败 | （关闭） |
+
+工作目录为当前会话的 `ctx.cwd`。命令行整体交给系统 shell 解析（Windows 为 cmd），`windowsHide` 避免闪终端窗口。
+
+## 安装
+
+方式一（软链本仓库，随仓库更新）：
+
+```powershell
+New-Item -ItemType SymbolicLink `
+  -Path "$env:USERPROFILE\.pi\agent\extensions\pi-start-command" `
+  -Target "D:\AI\pi-s\pi-start-command"
+```
+
+方式二（npm 包）：`pi install npm:pi-start-command`（需代理）。
+
+pi 通过 jiti 直接加载 `.ts`，无需构建。
+
+## 使用示例
+
+```powershell
+# 每次会话开始前同步一次远程状态
+$env:PI_START_COMMAND = "git fetch --all --quiet"
+
+# 自定义超时 30 秒，成功静默
+$env:PI_START_COMMAND_TIMEOUT_MS = "30000"
+$env:PI_START_COMMAND_QUIET = "1"
+```
+
+通知示例：
+
+- 成功：`[start-command] "git fetch --all --quiet" exit=0 812ms`
+- 失败：`[start-command] "npm test" exit=1 4503ms stdout=… stderr=…`
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,186 @@
+/**
+ * pi-start-command — 在会话真正开始前运行一条配置好的启动命令。
+ *
+ * 参考 dsh-start-command（DSH 同名插件）的语义移植到 pi 扩展 API：
+ *
+ *   dsh 挂点 `agent/pre-step`（UserPromptSubmit 的 waterfall，请求派生前最后
+ *   一个扩展点）↔ pi 挂点 `before_agent_start`（pi await 全部 handler 后才
+ *   组装并派发模型请求）。在 handler 里 await 命令即满足"先跑命令、
+ *   再发请求"，且不触碰 agent 循环本身。
+ *
+ * 触发条件（对应 dsh 版的五道门槛中 pi 可表达的部分）：
+ *   1. 配置了命令（环境变量 `PI_START_COMMAND`，空/未设 = 整个插件静默跳过）；
+ *   2. `event.messageType === "user"` —— 只对用户提交的 prompt 生效。pi v1.2.0 起
+ *      `before_agent_start` 也为 `pi.sendMessage(..., { triggerTurn: true })` 触发
+ *      （`"custom"` 变体），程序化启动的 run 不算"用户发起了会话"；
+ *   3. 每个 run 只触发一次 —— `before_agent_start` 本身就是 run 级事件，
+ *      一轮内的后续工具循环步不会再次进入，天然具备 dsh 版 turn latch 的幂等性。
+ *
+ * 失败策略与 dsh 版一致：任何失败（非零退出、超时、spawn 失败）只经
+ * `ctx.ui.notify` 告知并放行，绝不让异常逃进事件分发 —— 启动命令必须
+ * 无法破坏模型请求。
+ *
+ * 配置（环境变量）：
+ *   - `PI_START_COMMAND`           要运行的命令行；未设或空白则插件完全静默。
+ *   - `PI_START_COMMAND_TIMEOUT_MS` 超时毫秒数，默认 10000；到点 kill 进程并放行。
+ *   - `PI_START_COMMAND_QUIET`     设为 `1` 时成功也不弹通知，只报失败。
+ *
+ * 工作目录：`ctx.cwd`（当前会话的工作目录），与 dsh 版取 session cwd 对齐。
+ *
+ * 安装：把本目录软链到 `~/.pi/agent/extensions/pi-start-command` 即可
+ * （pi 扫描 extensions 目录，按目录内的 `index.ts` 入口经 jiti 加载）。
+ */
+import { spawn } from "node:child_process";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/** 默认超时：启动命令不应长期阻塞会话开始。 */
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/** stdout/stderr 尾部带入通知的字符上限（日志边界，不是行为边界）。 */
+const LOG_TAIL_CHARS = 400;
+
+/** 读取配置的启动命令，规范化：非字符串或空白视为未配置。 */
+function readStartCommand(): string | undefined {
+	const raw = process.env.PI_START_COMMAND;
+	if (typeof raw !== "string") return undefined;
+	const command = raw.trim();
+	return command === "" ? undefined : command;
+}
+
+/** 解析超时毫秒数：非法或非正数回退默认值。 */
+function resolveTimeoutMs(): number {
+	const raw = Number(process.env.PI_START_COMMAND_TIMEOUT_MS);
+	return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_TIMEOUT_MS;
+}
+
+/** 是否静默成功（只报失败）。 */
+function isQuiet(): boolean {
+	return process.env.PI_START_COMMAND_QUIET === "1";
+}
+
+/** 文本末尾至多 `LOG_TAIL_CHARS` 字符；空白返回 undefined。 */
+function tail(text: string | undefined): string | undefined {
+	if (typeof text !== "string") return undefined;
+	const trimmed = text.trim();
+	if (trimmed === "") return undefined;
+	return trimmed.length > LOG_TAIL_CHARS ? `…${trimmed.slice(-LOG_TAIL_CHARS)}` : trimmed;
+}
+
+/** 一次命令执行的结果；`ran` 区分"进程起来了"与"根本没起来"。 */
+interface CommandOutcome {
+	ran: boolean;
+	reason: string;
+	exitCode?: number;
+	timedOut?: boolean;
+	aborted?: boolean;
+	durationMs: number;
+	stdoutTail?: string;
+	stderrTail?: string;
+	error?: string;
+}
+
+/**
+ * 运行一条启动命令。绝不抛出。
+ *
+ * 用 `spawn` 而非 `exec`：命令行整体交给系统 shell 解析（Windows 为 cmd），
+ * `windowsHide` 避免闪终端窗口；超时到点 kill；输出只取尾部用于通知。
+ */
+function runStartCommand(command: string, cwd: string, timeoutMs: number): Promise<CommandOutcome> {
+	return new Promise((resolve) => {
+		const started = Date.now();
+		let child: ReturnType<typeof spawn>;
+		try {
+			child = spawn(command, {
+				shell: true,
+				cwd,
+				windowsHide: true,
+				stdio: ["ignore", "pipe", "pipe"],
+			});
+		} catch (error) {
+			resolve({
+				ran: false,
+				reason: "spawn-failed",
+				durationMs: Date.now() - started,
+				error: error instanceof Error ? error.message : String(error),
+			});
+			return;
+		}
+
+		let stdout = "";
+		let stderr = "";
+		let timedOut = false;
+		let aborted = false;
+		child.stdout?.on("data", (chunk: Buffer) => {
+			stdout += chunk.toString();
+		});
+		child.stderr?.on("data", (chunk: Buffer) => {
+			stderr += chunk.toString();
+		});
+
+		const timer = setTimeout(() => {
+			timedOut = true;
+			child.kill();
+		}, timeoutMs);
+
+		child.on("error", (error) => {
+			clearTimeout(timer);
+			resolve({
+				ran: false,
+				reason: "spawn-failed",
+				durationMs: Date.now() - started,
+				error: error.message,
+			});
+		});
+		child.on("close", (code, signal) => {
+			clearTimeout(timer);
+			resolve({
+				ran: true,
+				reason: "completed",
+				...(code !== null ? { exitCode: code } : {}),
+				...(timedOut ? { timedOut: true } : {}),
+				...(signal !== null ? { aborted: true } : {}),
+				durationMs: Date.now() - started,
+				...(tail(stdout) !== undefined ? { stdoutTail: tail(stdout) } : {}),
+				...(tail(stderr) !== undefined ? { stderrTail: tail(stderr) } : {}),
+			});
+		});
+	});
+}
+
+/** 把一次结果渲染成单行通知文本；失败时级别为 warning。 */
+function describeOutcome(command: string, outcome: CommandOutcome): { level: "info" | "warning"; text: string } {
+	const parts = [`[start-command] "${command}"`];
+	if (outcome.ran !== true) {
+		parts.push(`未运行 (${outcome.reason})`);
+		if (outcome.error !== undefined) parts.push(`error=${outcome.error}`);
+	} else {
+		parts.push(`exit=${outcome.exitCode ?? "signal"}`);
+		if (outcome.timedOut === true) parts.push("超时");
+	}
+	parts.push(`${outcome.durationMs}ms`);
+	if (outcome.stdoutTail !== undefined) parts.push(`stdout=${outcome.stdoutTail}`);
+	if (outcome.stderrTail !== undefined) parts.push(`stderr=${outcome.stderrTail}`);
+	const failed =
+		outcome.ran !== true ||
+		outcome.timedOut === true ||
+		outcome.aborted === true ||
+		(outcome.exitCode !== undefined && outcome.exitCode !== 0);
+	return { level: failed ? "warning" : "info", text: parts.join(" ") };
+}
+
+export default function piStartCommand(pi: ExtensionAPI): void {
+	pi.on("before_agent_start", async (event, ctx) => {
+		// 只对用户提交的 prompt 生效；程序化触发的 run（custom message）跳过。
+		if (event.messageType !== "user") return;
+
+		const command = readStartCommand();
+		if (command === undefined) return;
+
+		const outcome = await runStartCommand(command, ctx.cwd, resolveTimeoutMs());
+		const line = describeOutcome(command, outcome);
+		if (ctx.hasUI && (line.level === "warning" || !isQuiet())) {
+			ctx.ui.notify(line.text, line.level);
+		}
+		return;
+	});
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@falling-ts/pi-start-command",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "会话开始前运行一条配置好的启动命令（PI_START_COMMAND）",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": "falling-ts <zgh.yuanshang@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/falling-ts/pi-start-command.git"
+  },
+  "homepage": "https://github.com/falling-ts/pi-start-command#readme",
+  "bugs": {
+    "url": "https://github.com/falling-ts/pi-start-command/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "pi-coding-agent",
+    "start-command",
+    "hook"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "pi": {
+    "extensions": ["./index.ts"]
+  },
+  "files": [
+    "index.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  }
+}