@sukeai/pi-logfwd 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 robotnoname
+
+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

@@ -0,0 +1,131 @@
+# pi-logfwd
+
+实时命令日志转发：当 pi 运行命令时，把输出**实时流式**转发回来（而不是内置 bash 工具那样攒到最后一次性返回 + 截断）。
+
+- **bash_logged 工具**：pi 扩展，经 Go 二进制 `pi-logfwd` 在伪终端（PTY）中运行命令，JSONL 事件流逐块推送，可选追加日志文件。
+- **pi-logfwd 二进制**：跨平台预编译二进制，作为 npm 平台包随主包一起分发（见下方「平台支持」）。
+
+动机：pi 内置 bash/process 工具是缓冲式的——输出攒到最后一次性返回，且截断为末尾 2000 行 / 50KB；没有 TTY、没有交互输入通道。pi-logfwd 补上：实时流式输出、PTY 支持、日志落盘。
+
+> 密码提示与 GUI 授权弹窗**不支持**（PTY 只能渲染提示、无人应答；弹窗无法程序化操作）——此时告诉用户手动执行。
+
+## 架构
+
+```
+pi (agent)
+  │  bash_logged 工具（@sukeai/pi-logfwd 扩展）
+  ▼
+pi-logfwd run -- "shell script"          ← 接收 shell 脚本 / 任意命令
+  │  内部：PTY 分配（默认）或管道（--no-pty）
+  │  实时：每块输出 → JSONL 事件 → stdout + 可选 --log-file
+  ▼
+{ "ts":…, "event":"start",  "pid":123,  "command":"echo hi" }
+{ "ts":…, "event":"output", "stream":"stdout", "data":"hi\n" }
+{ "ts":…, "event":"exit",   "code":0,   "durationMs":12 }
+```
+
+## 安装
+
+```bash
+# 推荐：npm 安装（自动带上当前平台的预编译二进制）
+pi install npm:@sukeai/pi-logfwd
+
+# 从 GitHub（仓库公开后可用；需在 settings 或命令行指定版本 tag）
+pi install git:github.com/lazyfury/pi-log-forwarder@v0.1.0
+
+# 本地路径开发（不安装依赖，适合改源码）
+pi install /path/to/pi-log-forwarder
+
+# 试用一次（不写 settings）
+pi -e npm:@sukeai/pi-logfwd
+```
+
+装完在 pi 里 `/reload`，即可调用 `bash_logged` 工具（参数 `command` / `timeout` / `cwd` / `logFile` / `noPty`）。
+
+## 平台支持
+
+二进制分发模型：npm **platform companion 包**（esbuild 同款机制）。主包把全部平台包列为 `optionalDependencies`，npm 只安装与当前 `os`/`cpu` 匹配的那一个，其余静默跳过；扩展在运行时按平台定位二进制。
+
+| 平台 | 预编译包 | 状态 |
+| --- | --- | --- |
+| macOS arm64 | `@sukeai/pi-logfwd-darwin-arm64` | ✅ 实机验证 |
+| macOS amd64 | `@sukeai/pi-logfwd-darwin-amd64` | ⚠️ 交叉编译，未实机验证 |
+| Linux arm64 | `@sukeai/pi-logfwd-linux-arm64` | ⚠️ 交叉编译，未实机验证 |
+| Linux amd64 | `@sukeai/pi-logfwd-linux-amd64` | ⚠️ 交叉编译，未实机验证 |
+| Windows | 无 | ❌ 不支持 |
+
+**Windows 为什么不支持**：`pi-logfwd` 的 PTY 层用 creack/pty，它在 Windows 上直接返回 `ErrUnsupported`（`--no-pty` 管道模式理论上可行，但需额外改 shell 默认值/信号处理，成本高收益低），因此不发布 win32 平台包。
+
+**不支持的平台如何提醒**：全部平台包被 npm 跳过 → 二进制缺失 → `bash_logged` 不会静默报 ENOENT，而是返回明确说明：
+
+- **win32**：提示「Windows 不受支持（creack/pty ErrUnsupported），建议在 WSL/容器中运行 pi」；自行编译仅管道版可设 `PI_LOG_FWD_BIN` 绕过。
+- **其他缺二进制**：给出三种装法（`pi install npm:@sukeai/pi-logfwd` / `go build` / 放入 PATH 或 `~/.pi/agent/bin`）。
+
+### 二进制解析顺序（每次调用时）
+
+```
+1. env PI_LOG_FWD_BIN                     （显式指定，设了但缺失会直接报错）
+2. 平台 companion 包                      （@sukeai/pi-logfwd-<os>-<arch>）
+3. ~/.pi/agent/bin/pi-logfwd              （兼容旧的本地安装方式）
+4. PATH 上的 pi-logfwd                    （兼容旧的 PATH 安装方式）
+```
+
+## pi-logfwd CLI 用法（独立于 pi 使用）
+
+```bash
+pi-logfwd run [flags] [--] <shell-script>   # PTY 模式（默认），JSONL 事件流
+pi-logfwd run [flags] -                     # 从 stdin 读脚本
+pi-logfwd version | help
+
+# flags: --no-pty --plain --timeout D --cwd DIR --log-file FILE
+```
+
+示例：
+
+```bash
+pi-logfwd run 'echo hi; echo err >&2'                    # JSONL
+pi-logfwd run --plain 'make test'                        # 人类可读
+cat deploy.sh | pi-logfwd run --log-file /tmp/deploy.log -
+pi-logfwd run --timeout 30s 'npm run build'
+```
+
+退出码：透传子进程退出码；超时被杀死为 124；信号终止为 128+信号。
+
+## 开发者
+
+### 仓库结构
+
+```
+cmd/pi-logfwd/           Go 源码（main.go / runner.go）
+extension/extension.ts   pi 扩展：注册 bash_logged 工具（平台解析 + 提醒逻辑）
+package.json             主包（pi manifest + optionalDependencies 平台包列表）
+scripts/release.sh       交叉编译 + 发布（Go build → 平台包 → npm publish）
+scripts/set-version.js   主包/平台包版本同步
+.pi/skills/log-forwarding.md  pi 项目 skill（用法 + 边界调研结论）
+```
+
+### 本地构建（不经 npm）
+
+```bash
+go build -o ~/.pi/agent/bin/pi-logfwd ./cmd/pi-logfwd   # 单二进制，无配置依赖
+# 或放 PATH；扩展解析顺序第 3/4 步会找到它
+```
+
+### 发布（Go 二进制 + npm 包一体）
+
+所有包共用同一版本号（主包 + 4 个平台包），一条命令完成：
+
+```bash
+scripts/release.sh 0.1.0                 # 构建矩阵 + 打包 dry-run（验证内容，不发）
+scripts/release.sh 0.1.0 --publish       # 真发布
+# 然后 git tag v0.1.0 && git push --tags
+```
+
+发布流程：`go build`（CGO_ENABLED=0，`GOOS/GOARCH` 矩阵）→ 每个平台生成只含二进制的 npm 平台包（`os`/`cpu` 字段匹配）→ 依次 `npm publish --access public` → 主包最后发。
+
+> 平台包命名 `@sukeai/pi-logfwd-<os>-<arch>`，每个包 `bin: { "pi-logfwd": "bin/pi-logfwd" }`——npm 会把匹配平台的二进制链入 `node_modules/.bin`。
+
+### 备注
+
+- 新增平台：在 `scripts/release.sh` 的 `PLATFORMS` 加一行 + `package.json` 的 `optionalDependencies` 加对应项；Windows 除外（见上）。
+- 本仓库 LICENSE 沿用 pi-fun-placeholder 先例（MIT / robotnoname）；如需改署名，替换 `LICENSE` 与两处 `package.json` 的 license 说明即可。

package/extension/extension.ts

@@ -0,0 +1,226 @@
+/**
+ * pi-logfwd - pi package extension registering a "bash_logged" tool.
+ *
+ * Runs commands through the Go binary `pi-logfwd` (PTY, real-time log
+ * forwarding, optional log file). Streaming chunks are pushed into the
+ * conversation via onUpdate, so output appears as it happens instead of
+ * being buffered and truncated by the built-in bash tool.
+ *
+ * Binary resolution order (checked on every execute):
+ *   1. env PI_LOG_FWD_BIN                      (explicit override)
+ *   2. bundled platform package                (@sukeai/pi-logfwd-<os>-<arch>,
+ *                                              installed via optionalDependencies)
+ *   3. ~/.pi/agent/bin/pi-logfwd               (legacy local install)
+ *   4. PATH 上的 pi-logfwd                     (legacy, spawn-by-name fallback)
+ *
+ * Platform support: darwin (arm64/amd64) + linux (arm64/amd64) ship prebuilt
+ * binaries through npm optionalDependencies; npm installs only the package
+ * matching the current os/cpu and silently skips the rest. Windows is NOT
+ * supported (creack/pty returns ErrUnsupported on Windows, so the PTY core
+ * cannot work) - on win32 the tool returns an explicit notice instead of a
+ * cryptic spawn failure.
+ *
+ * Install:
+ *   pi install npm:@sukeai/pi-logfwd    # 推荐：随包自动装当前平台二进制
+ *
+ * Dev / manual overrides:
+ *   PI_LOG_FWD_BIN=/path/to/pi-logfwd   # 指向自建/自编译二进制
+ *   cd cmd/pi-logfwd && go build -o ~/.pi/agent/bin/pi-logfwd ./cmd/pi-logfwd
+ */
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+const require = createRequire(import.meta.url);
+const MAX_CHARS = 60_000;
+const STREAM_INTERVAL_MS = 150;
+
+/** Prebuilt binary platform packages published alongside this package. */
+const COMPANION_PREFIX = "@sukeai/pi-logfwd-";
+const COMPANION_ARCHES = new Set(["arm64", "x64"]);
+
+type Resolution =
+	| { ok: true; bin: string }
+	| { ok: false; bin: string | null; notice: string };
+
+/**
+ * Resolve the pi-logfwd binary for the current platform. Returns a binary
+ * path when found, or a human-readable notice explaining how to fix it
+ * (or why the platform is unsupported).
+ */
+function resolveBin(): Resolution {
+	// 1. Explicit override. If it is set but missing, say so - do not
+	//    silently fall through, the user clearly wanted this exact path.
+	const fromEnv = process.env.PI_LOG_FWD_BIN;
+	if (fromEnv) {
+		if (existsSync(fromEnv)) return { ok: true, bin: fromEnv };
+		return {
+			ok: false,
+			bin: null,
+			notice: `PI_LOG_FWD_BIN 指向的文件不存在: ${fromEnv}`,
+		};
+	}
+
+	// 2. Windows is unsupported by design: creack/pty (the PTY layer pi-logfwd
+	//    relies on) returns ErrUnsupported on Windows, so no win32 prebuilt
+	//    package is published and the PTY core cannot work there.
+	if (process.platform === "win32") {
+		return {
+			ok: false,
+			bin: null,
+			notice:
+				"Windows 不受支持: pi-logfwd 的 PTY 依赖 (creack/pty) 在 Windows 上返回 ErrUnsupported，未发布 win32 预编译包。\n" +
+				"建议: 在 WSL / 容器中运行 pi 以使用 bash_logged。\n" +
+				"自行交叉编译仅管道版本 (--no-pty，无 PTY) 后，可设 PI_LOG_FWD_BIN 指向该二进制以绕过此提示。",
+		};
+	}
+
+	// 3. Bundled platform package (installed by npm from optionalDependencies,
+	//    only the one matching os/cpu is present).
+	const archOk = COMPANION_ARCHES.has(process.arch);
+	if (archOk) {
+		const companion = COMPANION_PREFIX + `${process.platform}-${process.arch}`;
+		try {
+			const pkgRoot = dirname(require.resolve(`${companion}/package.json`));
+			const bin = join(pkgRoot, "bin", "pi-logfwd");
+			if (existsSync(bin)) return { ok: true, bin };
+		} catch {
+			/* companion not installed - keep resolving */
+		}
+	}
+
+	// 4. Legacy local install location (keep working for existing setups).
+	const agentBin = join(homedir(), ".pi", "agent", "bin", "pi-logfwd");
+	if (existsSync(agentBin)) return { ok: true, bin: agentBin };
+
+	// 5. PATH fallback: spawn by name and let ENOENT surface a clear error.
+	const platformTag =
+		process.platform === "darwin" || process.platform === "linux"
+			? `${process.platform}-${process.arch}`
+			: process.platform;
+	return {
+		ok: false,
+		bin: "pi-logfwd",
+		notice:
+			`未找到 pi-logfwd 二进制 (平台 ${platformTag}${archOk ? "" : "，无对应预编译包"})。安装方式任选其一:\n` +
+			"  1. pi install npm:@sukeai/pi-logfwd    # 推荐: 随包自动安装当前平台预编译二进制\n" +
+			"  2. go build -o <bin> ./cmd/pi-logfwd   # 本仓库自行编译后设 PI_LOG_FWD_BIN=<bin>\n" +
+			"  3. 把 pi-logfwd 放入 PATH 或 ~/.pi/agent/bin/pi-logfwd",
+	};
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "bash_logged",
+		label: "Bash (streamed log forward)",
+		description:
+			"Run a shell command or script through pi-logfwd and stream its logs back in real time. " +
+			"Prefer bash_logged over bash when you need: (a) real-time output streaming instead of " +
+			"end-buffered/truncated output, (b) a command that requires a pseudo-terminal (PTY), or " +
+			"(c) a persistent log file. " +
+			"NOT supported by any pi tool (including this one): interactive secret prompts " +
+			"(sudo/ssh password) and GUI authorization dialogs - PTY can render a prompt but nothing " +
+			"can answer it. For those, tell the user to run the command manually.",
+		promptSnippet: "Run a shell command with real-time log forwarding (PTY support)",
+		// 自定义 renderCall：TUI 里完整显示命令（不定义时兜底渲染只显示工具名）
+		renderCall(args, theme, _context) {
+			const command = typeof args.command === "string" ? args.command : "";
+			const commandDisplay = command || theme.fg("toolOutput", "...");
+			let text = theme.fg("toolTitle", theme.bold(`bash_logged ${commandDisplay}`));
+			if (typeof args.timeout === "number") {
+				text += theme.fg("muted", ` (timeout ${args.timeout}s)`);
+			}
+			return new Text(text, 0, 0);
+		},
+		parameters: Type.Object({
+			command: Type.String({ description: "Shell script or command to run" }),
+			timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (default: none)" })),
+			cwd: Type.Optional(Type.String({ description: "Working directory (default: session cwd)" })),
+			logFile: Type.Optional(Type.String({ description: "Append forwarded logs to this file" })),
+			noPty: Type.Optional(
+				Type.Boolean({ description: "Run without a pseudo-terminal (stdout/stderr stay separate)" }),
+			),
+		}),
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			// Resolve the binary on every call: the package (and with it the
+			// companion binary) may be added/updated between pi restarts, and a
+			// missing binary should produce a clear notice instead of ENOENT.
+			const res = resolveBin();
+			if (!res.ok) {
+				return {
+					content: [{ type: "text", text: `bash_logged 不可用:\n${res.notice}` }],
+					details: { exitCode: null, forwarded: false, reason: "binary-unavailable" },
+				};
+			}
+
+			const args = ["run"];
+			if (params.noPty) args.push("--no-pty");
+			if (params.cwd) args.push("--cwd", params.cwd);
+			if (params.logFile) args.push("--log-file", params.logFile);
+			if (params.timeout) args.push("--timeout", `${params.timeout}s`);
+			args.push("--", params.command);
+
+			const child = spawn(res.bin, args, { cwd: ctx.cwd, env: process.env });
+
+			let accumulated = "";
+			let lastStream = 0;
+			const push = (chunk: string) => {
+				accumulated += chunk;
+				if (accumulated.length > MAX_CHARS * 2) accumulated = accumulated.slice(-MAX_CHARS);
+				const now = Date.now();
+				if (now - lastStream > STREAM_INTERVAL_MS) {
+					lastStream = now;
+					onUpdate?.({ content: [{ type: "text", text: accumulated.slice(-MAX_CHARS) }] });
+				}
+			};
+
+			const rl = createInterface({ input: child.stdout });
+			rl.on("line", (line) => {
+				try {
+					const ev = JSON.parse(line);
+					if (ev.event === "output") push(ev.data);
+				} catch {
+					/* ignore malformed lines */
+				}
+			});
+
+			let exitCode: number | null = null;
+			let errText = "";
+			child.stderr.on("data", (d: Buffer) => (errText += d.toString()));
+			child.on("error", (e: Error) => {
+				if (e && (e as NodeJS.ErrnoException).code === "ENOENT") {
+					errText += `\nbash_logged 不可用: ${res.bin} 不存在或不可执行。\n${res.notice}`;
+				} else {
+					errText += `pi-logfwd: ${e.message}\n`;
+				}
+			});
+			child.on("close", (c) => (exitCode = c));
+			signal?.addEventListener("abort", () => child.kill("SIGTERM"), { once: true });
+
+			await new Promise<void>((resolve) => {
+				let settled = false;
+				const finish = () => {
+					if (settled) return;
+					settled = true;
+					resolve();
+				};
+				child.on("close", finish);
+				child.on("error", finish);
+			});
+
+			const text = (accumulated || "(no output)").slice(-MAX_CHARS);
+			const resultText = errText ? `${text}\n${errText.trimEnd()}` : text;
+			return {
+				content: [{ type: "text", text: resultText }],
+				details: { exitCode, forwarded: true, logFile: params.logFile ?? null },
+			};
+		},
+	});
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+	"name": "@sukeai/pi-logfwd",
+	"version": "0.1.0",
+	"description": "pi package: bash_logged tool that streams command logs in real time through the pi-logfwd Go binary (PTY, JSONL events, optional log file) / pi 实时命令日志转发扩展",
+	"type": "module",
+	"license": "MIT",
+	"keywords": [
+		"pi-package",
+		"pi",
+		"pi-extension",
+		"extension",
+		"log-forwarder",
+		"pty",
+		"logs",
+		"streaming"
+	],
+	"files": [
+		"extension/extension.ts",
+		"README.md",
+		"LICENSE"
+	],
+	"main": "extension/extension.ts",
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
+		"typebox": "*"
+	},
+	"optionalDependencies": {
+		"@sukeai/pi-logfwd-darwin-arm64": "0.1.0",
+		"@sukeai/pi-logfwd-darwin-amd64": "0.1.0",
+		"@sukeai/pi-logfwd-linux-arm64": "0.1.0",
+		"@sukeai/pi-logfwd-linux-amd64": "0.1.0"
+	},
+	"pi": {
+		"extensions": [
+			"./extension/extension.ts"
+		]
+	}
+}