@averyyy/pi-client 0.80.3-piclient.10

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+## [Unreleased]
+
+### Added
+
+- Initial `pi-client` package as a lightweight wrapper that exposes only the `pi-client` bin without `pi`.
+- Global install wrapper that launches the local forked coding-agent entrypoint while sharing the original `~/.pi/agent` configuration.
+- `pi-client update` command for updating the fork checkout and reinstalling both `pi-client` and `pi-server`.
+- npm global package updates during `pi-client update`.
+- `pi-client web` command that starts the client backend in Tau mirror mode on port `1838` by default.
+
+### Fixed
+
+- Used `--legacy-peer-deps` for npm-global fork updates and documented installs so existing upstream Pi installs do not trigger peer override warnings for forked prerelease aliases.

package/README.md

@@ -0,0 +1,50 @@
+# @averyyy/pi-client
+
+Client CLI for connecting Pi to a `pi-server` instance.
+
+## Install
+
+```bash
+npm i -g --ignore-scripts --legacy-peer-deps @averyyy/pi-client
+```
+
+`--legacy-peer-deps` avoids npm peer override warnings when upstream Pi is already installed globally.
+
+## Use
+
+Connect to the hosted server:
+
+```bash
+PI_SERVER_URL=https://pi.yreva.asia pi-client
+```
+
+Send one prompt and exit:
+
+```bash
+PI_SERVER_URL=https://pi.yreva.asia pi-client -p "Say exactly: ok"
+```
+
+Start the browser UI:
+
+```bash
+pi install npm:tau-mirror
+PI_SERVER_URL=https://pi.yreva.asia pi-client web
+```
+
+The web command starts `pi-client` in Tau mirror mode. Tau listens on `http://127.0.0.1:1838` by default and uses the same shared `~/.pi/agent` extension install as local `pi`, so installing Tau with either `pi` or `pi-client` works.
+
+## Server Auth
+
+If your server uses an auth token, set it on the client:
+
+```bash
+PI_SERVER_AUTH_TOKEN=your-token PI_SERVER_URL=http://127.0.0.1:4217 pi-client
+```
+
+## Related Package
+
+Install the server separately:
+
+```bash
+npm i -g --ignore-scripts @averyyy/pi-server
+```

package/bin/pi-client.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const args = process.argv.slice(2);
+const modulePromise =
+	args[0] === "update"
+		? import("./update.js").then(async ({ runPiClientUpdate }) => {
+				process.exitCode = await runPiClientUpdate(args.slice(1));
+			})
+		: args[0] === "web"
+			? import("./web.js").then(async ({ runPiClientWeb }) => {
+					process.exitCode = await runPiClientWeb(args.slice(1));
+				})
+			: runPiClientCli(args);
+
+Promise.resolve(modulePromise).catch((e) => {
+	console.error(e);
+	process.exit(1);
+});
+
+function runPiClientCli(args) {
+	const entry = fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"));
+	const result = spawnSync(process.execPath, [join(dirname(entry), "cli.js"), ...args], {
+		env: {
+			...process.env,
+			PI_CODING_AGENT: "true",
+			PI_SERVER_MODE: "true",
+		},
+		stdio: "inherit",
+	});
+	if (result.error) throw result.error;
+	process.exitCode = result.status ?? (result.signal === "SIGINT" ? 130 : 1);
+}

package/bin/update.js

@@ -0,0 +1,88 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+function defaultPackageRoot() {
+	return dirname(dirname(fileURLToPath(import.meta.url)));
+}
+
+function defaultRepoRoot() {
+	return resolve(defaultPackageRoot(), "..", "..");
+}
+
+function readPackageMetadata(packageRoot) {
+	return JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf-8"));
+}
+
+function runStep(runner, command, args, cwd, stdio = "inherit") {
+	return runner(command, args, { cwd, stdio, encoding: "utf-8" });
+}
+
+function isMissingGitCheckout(result) {
+	const text = `${String(result.stdout ?? "")}\n${String(result.stderr ?? "")}`;
+	return result.status !== 0 && text.includes("not a git repository");
+}
+
+async function runNpmGlobalUpdate(runner, repoRoot, stdout, stderr) {
+	stdout.write("Updating npm packages: @averyyy/pi-client@latest @averyyy/pi-server@latest\n");
+	const result = runStep(
+		runner,
+		"npm",
+		["install", "-g", "--ignore-scripts", "--legacy-peer-deps", "@averyyy/pi-client@latest", "@averyyy/pi-server@latest"],
+		repoRoot,
+	);
+	if (result.status !== 0) {
+		stderr.write(
+			"pi-client update failed: npm install -g --ignore-scripts --legacy-peer-deps @averyyy/pi-client@latest @averyyy/pi-server@latest\n",
+		);
+		return result.status ?? 1;
+	}
+	stdout.write("pi-client update complete\n");
+	return 0;
+}
+
+export async function runPiClientUpdate(_args = [], options = {}) {
+	const packageRoot = options.packageRoot ?? defaultPackageRoot();
+	const repoRoot = options.repoRoot ?? defaultRepoRoot();
+	const runner = options.runner ?? spawnSync;
+	const stdout = options.stdout ?? process.stdout;
+	const stderr = options.stderr ?? process.stderr;
+	const pkg = readPackageMetadata(packageRoot);
+	const baseVersion = pkg.piClient?.basePiVersion ?? "unknown";
+	const baseCommit = pkg.piClient?.basePiCommit ?? "unknown";
+
+	stdout.write(`pi-client ${pkg.version} (based on pi ${baseVersion}, upstream ${baseCommit})\n`);
+	stdout.write(`Updating checkout: ${repoRoot}\n`);
+
+	const status = runStep(runner, "git", ["status", "--porcelain"], repoRoot, "pipe");
+	if (status.status !== 0) {
+		if (isMissingGitCheckout(status)) {
+			return runNpmGlobalUpdate(runner, repoRoot, stdout, stderr);
+		}
+		stderr.write("pi-client update failed: unable to inspect git status\n");
+		return status.status ?? 1;
+	}
+	if (String(status.stdout ?? "").trim().length > 0) {
+		stderr.write("pi-client update failed: working tree has uncommitted changes\n");
+		return 1;
+	}
+
+	const steps = [
+		["git", ["pull", "--ff-only"]],
+		["npm", ["install", "--ignore-scripts"]],
+		["npm", ["run", "install:pi-client"]],
+		["npm", ["run", "install:pi-server"]],
+	];
+
+	for (const [command, args] of steps) {
+		const result = runStep(runner, command, args, repoRoot);
+		if (result.status !== 0) {
+			stderr.write(`pi-client update failed: ${command} ${args.join(" ")}\n`);
+			return result.status ?? 1;
+		}
+	}
+
+	stdout.write("pi-client update complete\n");
+	return 0;
+}

package/bin/web.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const defaultPort = "1838";
+const defaultPiServerUrl = "http://127.0.0.1:4217";
+const tauCodexPackage = "@averyyy/pi-tau-codex";
+const tauCodexInstallTarget = "npm:@averyyy/pi-tau-codex";
+const tauCodexGitTarget = "git:github.com/Averyyy/pi-tau-codex";
+
+export async function runPiClientWeb(args = process.argv.slice(2)) {
+	const parsed = parseArgs(args);
+	if (parsed.help) {
+		printHelp();
+		return 0;
+	}
+
+	if (!hasTauCodexExtensionInstalled(process.env)) {
+		printInstallRequired();
+		return 1;
+	}
+
+	process.title = "pi-client web";
+	const entry = fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"));
+	const port = parsed.port;
+	const host = process.env.TAU_HOST ?? "127.0.0.1";
+	const child = spawn(process.execPath, [join(dirname(entry), "cli.js"), ...parsed.clientArgs], {
+		env: piClientWebEnv(process.env, { port, host }),
+		stdio: "inherit",
+	});
+
+	console.log(`pi-client web uses Tau at http://${host}:${port}`);
+
+	return await new Promise((resolve, reject) => {
+		child.once("error", reject);
+		child.once("exit", (code, signal) => {
+			resolve(code ?? (signal === "SIGINT" ? 130 : 1));
+		});
+	});
+}
+
+export function piClientWebEnv(env = process.env, options) {
+	return {
+		...env,
+		PI_CODING_AGENT: "true",
+		PI_SERVER_MODE: "true",
+		PI_SERVER_URL: env.PI_SERVER_URL ?? defaultPiServerUrl,
+		TAU_HOST: options.host,
+		TAU_MIRROR_PORT: options.port,
+	};
+}
+
+export function hasTauCodexExtensionInstalled(env = process.env) {
+	if (env.TAU_STATIC_DIR) return true;
+	const settingsPath = env.PI_CODING_AGENT_SETTINGS_PATH ?? join(
+		env.PI_CODING_AGENT_DIR ?? join(env.HOME ?? homedir(), ".pi", "agent"),
+		"settings.json",
+	);
+	if (!existsSync(settingsPath)) return false;
+	const settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+	const packages = Array.isArray(settings.packages) ? settings.packages : [];
+	return packages.some(packageSpecMatchesTauCodex);
+}
+
+function packageSpecMatchesTauCodex(spec) {
+	if (typeof spec === "string") return specMatchesTauCodex(spec);
+	if (!spec || typeof spec !== "object") return false;
+	return ["source", "package", "name", "spec"].some((key) => specMatchesTauCodex(spec[key]));
+}
+
+function specMatchesTauCodex(spec) {
+	return typeof spec === "string" && (
+		spec === tauCodexPackage ||
+		spec === tauCodexInstallTarget ||
+		spec.startsWith(`${tauCodexPackage}@`) ||
+		spec.startsWith(`${tauCodexInstallTarget}@`) ||
+		spec === tauCodexGitTarget ||
+		spec.includes("github.com/Averyyy/pi-tau-codex")
+	);
+}
+
+function parseArgs(args) {
+	let port = process.env.TAU_MIRROR_PORT ?? defaultPort;
+	const clientArgs = [];
+
+	for (let i = 0; i < args.length; i += 1) {
+		const arg = args[i];
+		if (arg === "--help" || arg === "-h") return { help: true, port, clientArgs };
+		if (arg === "--") {
+			clientArgs.push(...args.slice(i + 1));
+			break;
+		}
+		if (arg === "--port" || arg === "-p") {
+			port = requireValue(args, (i += 1), arg);
+			continue;
+		}
+		if (arg.startsWith("--port=")) {
+			port = arg.slice("--port=".length);
+			continue;
+		}
+		throw new Error(`Unknown pi-client web argument: ${arg}`);
+	}
+
+	validatePort(port);
+	return { help: false, port, clientArgs };
+}
+
+function requireValue(args, index, name) {
+	const value = args[index];
+	if (value === undefined || value.startsWith("-")) throw new Error(`${name} requires a value`);
+	return value;
+}
+
+function validatePort(port) {
+	const parsed = Number(port);
+	if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+		throw new Error(`--port must be an integer from 1 to 65535: ${port}`);
+	}
+}
+
+function printHelp() {
+	console.log(`Usage: pi-client web [--port <port>] [-- <pi-client args...>]
+
+Start pi-client in Tau mirror mode.
+
+Options:
+  -p, --port <port>  Tau port to listen on (default: ${defaultPort})
+  -h, --help         Show this help
+
+Environment:
+  PI_SERVER_URL          pi-server URL used by pi-client sessions
+  PI_SERVER_AUTH_TOKEN   pi-server auth token
+  TAU_HOST               Tau bind host (default: 127.0.0.1)
+  TAU_MIRROR_PORT        Tau port (default: ${defaultPort})
+
+Tau must be installed in the shared Pi agent settings:
+  pi-client install npm:@averyyy/pi-tau-codex
+  # or: pi install npm:@averyyy/pi-tau-codex
+  # dev fallback: pi-client install git:github.com/Averyyy/pi-tau-codex
+`);
+}
+
+function printInstallRequired() {
+	console.error(`请安装 ${tauCodexPackage}:`);
+	console.error("  pi-client install npm:@averyyy/pi-tau-codex");
+	console.error("  # or: pi install npm:@averyyy/pi-tau-codex");
+	console.error("  # dev fallback: pi-client install git:github.com/Averyyy/pi-tau-codex");
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "@averyyy/pi-client",
+	"version": "0.80.3-piclient.10",
+	"description": "Lightweight CLI wrapper that connects to a pi-server instance",
+	"type": "module",
+	"piClient": {
+		"basePiVersion": "0.80.3",
+		"basePiCommit": "85b7c247"
+	},
+	"bin": {
+		"pi-client": "bin/pi-client.js"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"bin",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"scripts": {
+		"clean": "shx echo ok",
+		"build": "shx echo ok",
+		"test": "vitest --run",
+		"prepublishOnly": "npm run build"
+	},
+	"dependencies": {
+		"@earendil-works/pi-coding-agent": "npm:@averyyy/pi-coding-agent@0.80.3-piclient.10"
+	},
+	"devDependencies": {
+		"shx": "0.4.0",
+		"vitest": "4.1.9"
+	},
+	"keywords": [
+		"pi-client",
+		"llm",
+		"agent"
+	],
+	"author": "Pi Contributors",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/Averyyy/pi-client",
+		"directory": "packages/pi-client"
+	},
+	"engines": {
+		"node": ">=22.19.0"
+	}
+}