@caph42/pi-ccline 0.0.0-stage → 0.1.1

package/extensions/pi-ccline/binary.ts

@@ -0,0 +1,228 @@
+import { spawn } from "node:child_process";
+import { accessSync, constants, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join, resolve } from "node:path";
+
+export type BinarySource = "config" | "home" | "path" | "missing";
+
+export interface ResolvedBinary {
+	path: string | null;
+	source: BinarySource;
+}
+
+export interface ResolveOptions {
+	home?: string;
+	pathEnv?: string;
+	platform?: string;
+}
+
+/** Cap on captured output per stream; the footer only needs a couple of lines. */
+const MAX_STREAM_BYTES = 256 * 1024;
+
+export function isExecutableFile(path: string): boolean {
+	try {
+		const stats = statSync(path);
+		if (!stats.isFile()) return false;
+		if (process.platform === "win32") return true;
+		accessSync(path, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function expandHome(path: string, home: string): string {
+	if (path === "~") return home;
+	if (path.startsWith("~/") || path.startsWith("~\\")) return join(home, path.slice(2));
+	return path;
+}
+
+let cached: { key: string; result: ResolvedBinary } | null = null;
+
+/** Drop the resolution cache, e.g. after the config or PATH changed. */
+export function clearBinaryCache(): void {
+	cached = null;
+}
+
+/**
+ * Resolve the ccline binary in the documented order:
+ * config.binary -> ~/.claude/ccline/ccline -> PATH.
+ * A configured path that does not exist falls through instead of failing.
+ */
+export function resolveBinary(configured: string | null | undefined, options: ResolveOptions = {}): ResolvedBinary {
+	const home = options.home ?? homedir();
+	const pathEnv = options.pathEnv ?? process.env.PATH ?? "";
+	const platform = options.platform ?? process.platform;
+	const key = [configured ?? "", home, pathEnv, platform].join("\u0000");
+
+	if (cached && cached.key === key) return cached.result;
+
+	const result = resolveBinaryUncached(configured, home, pathEnv, platform);
+	cached = { key, result };
+	return result;
+}
+
+function resolveBinaryUncached(configured: string | null | undefined, home: string, pathEnv: string, platform: string): ResolvedBinary {
+	const configuredPath = typeof configured === "string" ? configured.trim() : "";
+	if (configuredPath) {
+		const candidate = expandHome(configuredPath, home);
+		if (isExecutableFile(candidate)) return { path: candidate, source: "config" };
+	}
+
+	const homeCandidate = join(home, ".claude", "ccline", "ccline");
+	if (isExecutableFile(homeCandidate)) return { path: homeCandidate, source: "home" };
+
+	const names = platform === "win32" ? ["ccline.exe", "ccline.cmd", "ccline"] : ["ccline"];
+	for (const directory of pathEnv.split(delimiter)) {
+		const trimmedDirectory = directory.trim();
+		if (!trimmedDirectory) continue;
+		for (const name of names) {
+			const candidate = resolve(trimmedDirectory, name);
+			if (isExecutableFile(candidate)) return { path: candidate, source: "path" };
+		}
+	}
+
+	return { path: null, source: "missing" };
+}
+
+export interface SpawnOptions {
+	binary: string;
+	args?: string[];
+	/** Written to stdin, then stdin is closed. */
+	payload?: string;
+	timeoutMs: number;
+	/** Exported to the child as COLUMNS, which drives ccline's line wrapping. */
+	columns?: number;
+	env?: Record<string, string>;
+	signal?: AbortSignal;
+}
+
+export interface SpawnResult {
+	ok: boolean;
+	stdout: string;
+	stderr: string;
+	code: number | null;
+	timedOut: boolean;
+	aborted: boolean;
+	error?: string;
+}
+
+function emptyResult(overrides: Partial<SpawnResult> = {}): SpawnResult {
+	return { ok: false, stdout: "", stderr: "", code: null, timedOut: false, aborted: false, ...overrides };
+}
+
+/**
+ * Run the binary once. Never rejects: timeouts, spawn failures, early exits and
+ * aborts all resolve to a result the caller can degrade from.
+ */
+export function spawnCcline(options: SpawnOptions): Promise<SpawnResult> {
+	return new Promise<SpawnResult>((resolvePromise) => {
+		const stdoutChunks: Buffer[] = [];
+		const stderrChunks: Buffer[] = [];
+		let stdoutBytes = 0;
+		let stderrBytes = 0;
+		let timedOut = false;
+		let settled = false;
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		let child: ReturnType<typeof spawn> | undefined;
+
+		const onAbort = () => {
+			if (settled) return;
+			try {
+				child?.kill("SIGKILL");
+			} catch {
+				// already gone
+			}
+			finish(emptyResult({ aborted: true, stdout: collect(stdoutChunks), stderr: collect(stderrChunks) }));
+		};
+
+		const finish = (result: SpawnResult) => {
+			if (settled) return;
+			settled = true;
+			if (timer) clearTimeout(timer);
+			options.signal?.removeEventListener("abort", onAbort);
+			try {
+				child?.stdin?.destroy();
+				child?.stdout?.destroy();
+				child?.stderr?.destroy();
+			} catch {
+				// ignore teardown errors
+			}
+			resolvePromise(result);
+		};
+
+		const collect = (chunks: Buffer[]): string => Buffer.concat(chunks).toString("utf8");
+
+		if (options.signal?.aborted) {
+			resolvePromise(emptyResult({ aborted: true }));
+			return;
+		}
+
+		const env: NodeJS.ProcessEnv = { ...process.env };
+		if (options.columns !== undefined && Number.isFinite(options.columns)) {
+			env.COLUMNS = String(Math.max(1, Math.round(options.columns)));
+		}
+		Object.assign(env, options.env ?? {});
+
+		try {
+			child = spawn(options.binary, options.args ?? [], { env, stdio: ["pipe", "pipe", "pipe"] });
+		} catch (error) {
+			finish(emptyResult({ error: error instanceof Error ? error.message : String(error) }));
+			return;
+		}
+
+		timer = setTimeout(() => {
+			timedOut = true;
+			try {
+				child?.kill("SIGKILL");
+			} catch {
+				// already gone
+			}
+			finish(emptyResult({ timedOut: true, stdout: collect(stdoutChunks), stderr: collect(stderrChunks) }));
+		}, Math.max(1, options.timeoutMs));
+
+		options.signal?.addEventListener("abort", onAbort, { once: true });
+
+		child.on("error", (error) => {
+			finish(emptyResult({ error: error.message, stdout: collect(stdoutChunks), stderr: collect(stderrChunks) }));
+		});
+
+		child.stdout?.on("data", (chunk: Buffer) => {
+			stdoutBytes += chunk.length;
+			if (stdoutBytes <= MAX_STREAM_BYTES) stdoutChunks.push(chunk);
+		});
+		child.stderr?.on("data", (chunk: Buffer) => {
+			stderrBytes += chunk.length;
+			if (stderrBytes <= MAX_STREAM_BYTES) stderrChunks.push(chunk);
+		});
+
+		// The child may exit before reading stdin; a failed write is expected then.
+		child.stdin?.on("error", () => {});
+		try {
+			if (options.payload !== undefined) child.stdin?.write(options.payload);
+			child.stdin?.end();
+		} catch {
+			// ignore: the close handler still settles the promise
+		}
+
+		child.on("close", (code) => {
+			finish(
+				emptyResult({
+					ok: code === 0 && !timedOut,
+					stdout: collect(stdoutChunks),
+					stderr: collect(stderrChunks),
+					code,
+					timedOut,
+				}),
+			);
+		});
+	});
+}
+
+/** Read `ccline --version`. Returns null when the binary cannot be probed. */
+export async function probeVersion(binary: string, timeoutMs = 2000, signal?: AbortSignal): Promise<string | null> {
+	const result = await spawnCcline({ binary, args: ["--version"], timeoutMs, signal });
+	if (!result.ok) return null;
+	const line = result.stdout.split("\n")[0]?.trim();
+	return line ? line : null;
+}

package/extensions/pi-ccline/config.test.ts

@@ -0,0 +1,78 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+
+import { DEFAULT_CONFIG, MIN_LIVE_REFRESH_MS, MIN_THROTTLE_MS, configPath, loadConfig, normalizeConfig, saveConfig } from "./config.ts";
+
+function tempDir(): string {
+	return mkdtempSync(join(tmpdir(), "pi-ccline-config-"));
+}
+
+test("uses defaults when the config file is missing", () => {
+	assert.deepEqual(loadConfig(join(tempDir(), "config.json")), DEFAULT_CONFIG);
+});
+
+test("falls back to defaults on broken JSON instead of throwing", () => {
+	const path = join(tempDir(), "config.json");
+	writeFileSync(path, "{ not json", "utf8");
+	assert.deepEqual(loadConfig(path), DEFAULT_CONFIG);
+});
+
+test("normalizes wrong types and clamps the throttle to one second", () => {
+	const config = normalizeConfig({
+		enabled: "yes",
+		binary: "  ",
+		timeoutMs: 10,
+		refreshThrottleMs: 5,
+		liveRefreshMs: 10,
+		env: { A: "1", B: 2 },
+	});
+	assert.equal(config.enabled, true);
+	assert.equal(config.binary, null);
+	assert.equal(config.timeoutMs, 200);
+	assert.equal(config.refreshThrottleMs, MIN_THROTTLE_MS);
+	assert.equal(config.liveRefreshMs, MIN_LIVE_REFRESH_MS);
+	assert.deepEqual(config.env, { A: "1" });
+});
+
+test("liveRefreshMs 0 disables ticker and bad values fall back to the default", () => {
+	assert.equal(normalizeConfig({ liveRefreshMs: 0 }).liveRefreshMs, 0);
+	assert.equal(normalizeConfig({ liveRefreshMs: "fast" }).liveRefreshMs, DEFAULT_CONFIG.liveRefreshMs);
+	assert.equal(normalizeConfig({ liveRefreshMs: 2500 }).liveRefreshMs, 2500);
+});
+
+test("keeps valid overrides", () => {
+	const config = normalizeConfig({ enabled: false, binary: "/tmp/ccline", timeoutMs: 9000, refreshThrottleMs: 2500 });
+	assert.deepEqual(config, {
+		enabled: false,
+		binary: "/tmp/ccline",
+		timeoutMs: 9000,
+		refreshThrottleMs: 2500,
+		liveRefreshMs: DEFAULT_CONFIG.liveRefreshMs,
+		showProvider: DEFAULT_CONFIG.showProvider,
+		env: {},
+	});
+});
+
+test("showProvider defaults on and ignores non-boolean values", () => {
+	assert.equal(DEFAULT_CONFIG.showProvider, true);
+	assert.equal(normalizeConfig({}).showProvider, true);
+	assert.equal(normalizeConfig({ showProvider: false }).showProvider, false);
+	assert.equal(normalizeConfig({ showProvider: "no" }).showProvider, true);
+});
+
+test("round-trips through saveConfig and loadConfig", () => {
+	const home = tempDir();
+	const config = { ...DEFAULT_CONFIG, enabled: false, binary: "/opt/ccline", env: { FOO: "bar" } };
+	assert.equal(saveConfig(config, configPath(home)), true);
+	assert.deepEqual(loadConfig(configPath(home)), config);
+});
+
+test("saveConfig reports failure instead of throwing", () => {
+	const home = tempDir();
+	const path = join(home, "file-as-dir", "config.json");
+	writeFileSync(join(home, "file-as-dir"), "blocked", "utf8");
+	assert.equal(saveConfig(DEFAULT_CONFIG, path), false);
+});

package/extensions/pi-ccline/config.ts

@@ -0,0 +1,104 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export interface PiCclineConfig {
+	/** Whether the footer is installed at session start. */
+	enabled: boolean;
+	/** Explicit ccline binary path; null means use the default resolution order. */
+	binary: string | null;
+	/** Hard timeout for one ccline invocation. */
+	timeoutMs: number;
+	/** Minimum spacing between two refreshes. Never below MIN_THROTTLE_MS. */
+	refreshThrottleMs: number;
+	/**
+	 * Interval of the live ticker that keeps time-based segments (elapsed
+	 * duration) moving while the agent runs. 0 disables the ticker.
+	 */
+	liveRefreshMs: number;
+	/** Append the model's provider to the model segment of the footer. */
+	showProvider: boolean;
+	/** Extra environment variables passed to the binary. */
+	env: Record<string, string>;
+}
+
+export const DEFAULT_CONFIG: PiCclineConfig = {
+	enabled: true,
+	binary: null,
+	timeoutMs: 5000,
+	refreshThrottleMs: 1000,
+	liveRefreshMs: 1000,
+	showProvider: true,
+	env: {},
+};
+
+export const MIN_TIMEOUT_MS = 200;
+export const MAX_TIMEOUT_MS = 60_000;
+/** The footer re-renders often; a faster refresh rate would spawn too many processes. */
+export const MIN_THROTTLE_MS = 1000;
+/** Below this a live ticker would spawn processes faster than a statusline is read. */
+export const MIN_LIVE_REFRESH_MS = 250;
+
+/** Path of the extension's own config file (not pi's settings.json). */
+export function configPath(home: string = homedir()): string {
+	return join(home, ".pi", "agent", "pi-ccline", "config.json");
+}
+
+function clampInt(value: unknown, fallback: number, min: number, max: number): number {
+	if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+	return Math.min(max, Math.max(min, Math.round(value)));
+}
+
+/** Coerce arbitrary parsed JSON into a valid config. Never throws. */
+export function normalizeConfig(raw: unknown): PiCclineConfig {
+	const source: Record<string, unknown> = raw && typeof raw === "object" && !Array.isArray(raw) ? (raw as Record<string, unknown>) : {};
+
+	const env: Record<string, string> = {};
+	const rawEnv = source.env;
+	if (rawEnv && typeof rawEnv === "object" && !Array.isArray(rawEnv)) {
+		for (const [key, value] of Object.entries(rawEnv as Record<string, unknown>)) {
+			if (typeof value === "string") env[key] = value;
+		}
+	}
+
+	/** 0 is an explicit opt-out; anything else is clamped to a sane tick range. */
+function clampLiveRefresh(value: unknown, fallback: number): number {
+	if (value === 0) return 0;
+	if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+	return Math.min(MAX_TIMEOUT_MS, Math.max(MIN_LIVE_REFRESH_MS, Math.round(value)));
+}
+
+const binary = typeof source.binary === "string" && source.binary.trim() ? source.binary.trim() : null;
+
+	return {
+		enabled: typeof source.enabled === "boolean" ? source.enabled : DEFAULT_CONFIG.enabled,
+		binary,
+		timeoutMs: clampInt(source.timeoutMs, DEFAULT_CONFIG.timeoutMs, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS),
+		refreshThrottleMs: clampInt(source.refreshThrottleMs, DEFAULT_CONFIG.refreshThrottleMs, MIN_THROTTLE_MS, MAX_TIMEOUT_MS),
+		liveRefreshMs: clampLiveRefresh(source.liveRefreshMs, DEFAULT_CONFIG.liveRefreshMs),
+		showProvider: typeof source.showProvider === "boolean" ? source.showProvider : DEFAULT_CONFIG.showProvider,
+		env,
+	};
+}
+
+/** Read the config file. A missing or broken file falls back to defaults. */
+export function loadConfig(path: string = configPath()): PiCclineConfig {
+	try {
+		return normalizeConfig(JSON.parse(readFileSync(path, "utf8")));
+	} catch {
+		return normalizeConfig(DEFAULT_CONFIG);
+	}
+}
+
+/** Persist the config. Returns false instead of throwing on any I/O error. */
+export function saveConfig(config: PiCclineConfig, path: string = configPath()): boolean {
+	try {
+		mkdirSync(dirname(path), { recursive: true });
+		const temp = `${path}.${process.pid}.tmp`;
+		writeFileSync(temp, `${JSON.stringify(normalizeConfig(config), null, 2)}\n`, "utf8");
+		renameSync(temp, path);
+		return true;
+	} catch {
+		return false;
+	}
+}