@ryan_nookpi/pi-extension-setup-sh 0.1.0

package/README.md

@@ -0,0 +1,63 @@
+# @ryan_nookpi/pi-extension-setup-sh
+
+Automatically runs the nearest `setup.sh` when a pi session starts.
+
+This is useful for repositories that need a predictable bootstrap step before the agent starts editing, testing, or running commands.
+
+## Install
+
+```bash
+pi install npm:@ryan_nookpi/pi-extension-setup-sh
+```
+
+## What it does
+
+- searches the current directory and parent directories for `setup.sh`
+- runs `setup.sh` automatically on session startup
+- skips automatic reruns when the same `setup.sh` already completed successfully
+- shows running, pending, failed, cancelled, and stale states in the pi UI
+- keeps per-project logs and state under pi's setup-sh state directory
+- prevents duplicate setup runs with a lock file
+
+## Commands
+
+```text
+/setup-sh
+/setup-sh status
+/setup-sh rerun
+/setup-sh cancel
+/setup-sh clear
+/setup-sh help
+```
+
+### `/setup-sh`
+
+Runs the nearest `setup.sh` manually, or attaches to the current run if one is already active.
+
+### `/setup-sh status`
+
+Shows the current setup state and recent log lines.
+
+### `/setup-sh rerun`
+
+Runs `setup.sh` again even if the previous run succeeded.
+
+### `/setup-sh cancel`
+
+Sends a termination signal to the active setup process.
+
+### `/setup-sh clear`
+
+Hides the setup widget for the current session.
+
+## Behavior
+
+- `setup.sh` is executed with `/bin/zsh` from the directory containing the script.
+- A successful automatic run is remembered by the script hash, so changing `setup.sh` allows it to run again.
+- Long-running setup output becomes `pending` in the UI when logs have been idle for a while.
+- Failed and stale states stay visible so you can inspect them with `/setup-sh status` or rerun with `/setup-sh rerun`.
+
+## Requirements
+
+- pi
+- a readable `setup.sh` file in the project directory or one of its parents

package/constants.ts

@@ -0,0 +1,10 @@
+import * as os from "node:os";
+import * as path from "node:path";
+
+export const WIDGET_KEY = "setup-sh";
+export const STATUS_KEY = "setup-sh";
+export const STATE_ROOT = path.join(os.homedir(), ".pi", "agent", "state", "setup-sh");
+export const LOCK_STALE_MS = 12 * 60 * 60 * 1000;
+export const PENDING_AFTER_MS = 60 * 1000;
+export const WIDGET_REFRESH_MS = 1000;
+export const LOG_TAIL_LINES = 8;

package/context.ts

@@ -0,0 +1,81 @@
+import { createHash } from "node:crypto";
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { STATE_ROOT } from "./constants.js";
+import type { SetupContext, StatePaths } from "./types.js";
+
+export function statePaths(repoKey: string): StatePaths {
+	const rootDir = STATE_ROOT;
+	const locksDir = path.join(rootDir, "locks");
+	const logsDir = path.join(rootDir, "logs");
+	const statesDir = path.join(rootDir, "states");
+	const exitsDir = path.join(rootDir, "exits");
+	const wrappersDir = path.join(rootDir, "wrappers");
+	return {
+		rootDir,
+		locksDir,
+		logsDir,
+		statesDir,
+		exitsDir,
+		wrappersDir,
+		lockPath: path.join(locksDir, `${repoKey}.lock.json`),
+		statePath: path.join(statesDir, `${repoKey}.json`),
+	};
+}
+
+export function repoKeyFor(realRepoRoot: string): string {
+	return createHash("sha256").update(realRepoRoot).digest("hex").slice(0, 16);
+}
+
+function fileHash(filePath: string): string {
+	return createHash("sha256").update(readFileSync(filePath)).digest("hex");
+}
+
+function isExecutableOrReadable(filePath: string): boolean {
+	try {
+		statSync(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export function findSetupPath(cwd: string): string | null {
+	let current = path.resolve(cwd);
+	try {
+		current = realpathSync(current);
+	} catch {
+		// Keep resolved cwd when the directory cannot be canonicalized yet.
+	}
+
+	while (true) {
+		const candidate = path.join(current, "setup.sh");
+		if (isExecutableOrReadable(candidate)) return candidate;
+		const parent = path.dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+}
+
+export function resolveSetupContext(cwd: string): SetupContext | null {
+	const setupPath = findSetupPath(cwd);
+	if (!setupPath) return null;
+	const realSetupPath = realpathSync(setupPath);
+	const repoRoot = realpathSync(path.dirname(realSetupPath));
+	const repoKey = repoKeyFor(repoRoot);
+	return {
+		repoRoot,
+		setupPath: realSetupPath,
+		repoKey,
+		setupHash: fileHash(realSetupPath),
+		paths: statePaths(repoKey),
+	};
+}
+
+export function displayPath(targetPath: string): string {
+	const home = os.homedir();
+	if (targetPath === home) return "~";
+	if (targetPath.startsWith(`${home}${path.sep}`)) return `~${targetPath.slice(home.length)}`;
+	return targetPath;
+}

package/index.ts

@@ -0,0 +1,172 @@
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { PENDING_AFTER_MS, STATE_ROOT, STATUS_KEY, WIDGET_KEY, WIDGET_REFRESH_MS } from "./constants.js";
+import { displayPath, findSetupPath, repoKeyFor, resolveSetupContext } from "./context.js";
+import { cancelSetup, createWrapperScript, startSetup } from "./runner.js";
+import { finalizeRunIfNeeded } from "./state.js";
+import type { SetupContext, StartMode, StartResult } from "./types.js";
+import { formatDuration, shellQuote, stripAnsi } from "./utils.js";
+import {
+	formatSnapshotLine,
+	installWidget,
+	refreshWatcher,
+	renderWidgetLine,
+	showStatus,
+	stopWatcher,
+	type Watcher,
+} from "./widget.js";
+
+function commandHelp(): string {
+	return [
+		"/setup-sh [status|rerun|cancel|clear]",
+		"- 인자 없음: 현재 폴더의 setup.sh 실행 또는 실행 상태 표시",
+		"- status: 상세 상태와 로그 tail 표시",
+		"- rerun: 성공/실패 상태와 무관하게 재실행",
+		"- cancel: 실행 중인 setup.sh 종료",
+		"- clear: 현재 세션의 setup widget 숨김",
+	].join("\n");
+}
+
+async function notifyStartResult(ctx: ExtensionContext, result: StartResult): Promise<void> {
+	if (result.kind === "started") {
+		ctx.ui.notify(`setup.sh 실행 시작: ${displayPath(result.context.repoRoot)}`, "info");
+		return;
+	}
+	if (result.kind === "running") {
+		ctx.ui.notify(`setup.sh가 이미 실행 중입니다: ${displayPath(result.context.repoRoot)}`, "info");
+		return;
+	}
+	if (result.kind === "skipped") {
+		ctx.ui.notify(result.reason, "info");
+		return;
+	}
+	if (result.kind === "failed") {
+		ctx.ui.notify(result.reason, "error");
+	}
+}
+
+export const __test__ = {
+	STATE_ROOT,
+	PENDING_AFTER_MS,
+	displayPath,
+	findSetupPath,
+	formatDuration,
+	formatSnapshotLine,
+	repoKeyFor,
+	renderWidgetLine,
+	resolveSetupContext,
+	createWrapperScript,
+	shellQuote,
+	stripAnsi,
+};
+
+export default function setupShExtension(pi: ExtensionAPI): void {
+	let watcher: Watcher | null = null;
+	const hiddenRepoKeys = new Set<string>();
+
+	async function watch(ctx: ExtensionContext, context: SetupContext): Promise<void> {
+		if (!ctx.hasUI || hiddenRepoKeys.has(context.repoKey)) return;
+		stopWatcher(ctx, watcher);
+		watcher = {
+			context,
+			interval: setInterval(() => {
+				if (watcher) void refreshWatcher(ctx, watcher);
+			}, WIDGET_REFRESH_MS),
+			snapshot: null,
+			tui: null,
+			disposed: false,
+		};
+		installWidget(ctx, watcher);
+		await refreshWatcher(ctx, watcher);
+	}
+
+	async function runOrAttach(ctx: ExtensionContext, mode: StartMode): Promise<StartResult> {
+		const result = await startSetup(ctx.cwd, mode);
+		if (result.kind !== "no-setup" && result.kind !== "failed") {
+			hiddenRepoKeys.delete(result.context.repoKey);
+			await watch(ctx, result.context);
+		}
+		return result;
+	}
+
+	pi.on("session_start", async (event, ctx) => {
+		const context = resolveSetupContext(ctx.cwd);
+		if (!context) {
+			if (ctx.hasUI) {
+				ctx.ui.setWidget(WIDGET_KEY, undefined);
+				ctx.ui.setStatus(STATUS_KEY, undefined);
+			}
+			return;
+		}
+
+		if (event.reason === "reload") {
+			await finalizeRunIfNeeded(context);
+			await watch(ctx, context);
+			return;
+		}
+
+		const result = await runOrAttach(ctx, "auto");
+		if (!ctx.hasUI) return;
+		if (result.kind === "started") {
+			ctx.ui.notify(`setup.sh 자동 실행 시작: ${displayPath(result.context.repoRoot)}`, "info");
+		}
+		if (result.kind === "running") ctx.ui.notify(`setup.sh 실행 중: ${displayPath(result.context.repoRoot)}`, "info");
+	});
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		stopWatcher(ctx, watcher);
+		watcher = null;
+	});
+
+	pi.registerCommand("setup-sh", {
+		description: "Run or inspect ./setup.sh for the current folder",
+		getArgumentCompletions: (prefix: string) => {
+			const values = ["status", "rerun", "cancel", "clear", "help"];
+			return values
+				.filter((value) => value.startsWith(prefix.trim()))
+				.map((value) => ({ value, label: value, description: `/setup-sh ${value}` }));
+		},
+		handler: async (args, ctx) => {
+			const action = args.trim() || "run";
+			const context = resolveSetupContext(ctx.cwd);
+			if (action === "help") {
+				ctx.ui.notify(commandHelp(), "info");
+				return;
+			}
+			if (!context) {
+				ctx.ui.notify("현재 폴더 또는 상위 폴더에서 setup.sh를 찾지 못했습니다.", "warning");
+				return;
+			}
+
+			if (action === "clear") {
+				hiddenRepoKeys.add(context.repoKey);
+				stopWatcher(ctx, watcher);
+				watcher = null;
+				ctx.ui.notify("setup.sh widget을 숨겼습니다.", "info");
+				return;
+			}
+
+			if (action === "status") {
+				hiddenRepoKeys.delete(context.repoKey);
+				await watch(ctx, context);
+				await showStatus(ctx, context);
+				return;
+			}
+
+			if (action === "cancel") {
+				const message = await cancelSetup(context);
+				hiddenRepoKeys.delete(context.repoKey);
+				await watch(ctx, context);
+				ctx.ui.notify(message, "warning");
+				return;
+			}
+
+			if (action !== "run" && action !== "rerun") {
+				ctx.ui.notify(commandHelp(), "warning");
+				return;
+			}
+
+			const mode: StartMode = action === "rerun" ? "rerun" : "manual";
+			await notifyStartResult(ctx, await runOrAttach(ctx, mode));
+		},
+	});
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@ryan_nookpi/pi-extension-setup-sh",
+  "version": "0.1.0",
+  "description": "Auto-run setup.sh extension for pi.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Jonghakseo/pi-extension.git",
+    "directory": "packages/setup-sh"
+  },
+  "bugs": {
+    "url": "https://github.com/Jonghakseo/pi-extension/issues"
+  },
+  "homepage": "https://github.com/Jonghakseo/pi-extension/tree/main/packages/setup-sh#readme",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "files": [
+    "constants.ts",
+    "context.ts",
+    "index.ts",
+    "runner.ts",
+    "state.ts",
+    "types.ts",
+    "utils.ts",
+    "widget.ts",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/runner.ts

@@ -0,0 +1,156 @@
+import { spawn } from "node:child_process";
+import { closeSync, openSync, writeFileSync } from "node:fs";
+import { chmod } from "node:fs/promises";
+import * as path from "node:path";
+import { resolveSetupContext } from "./context.js";
+import { createLock, ensureStateDirs, finalizeRunIfNeeded } from "./state.js";
+import type { LockRecord, RunRecord, SetupContext, StartMode, StartResult } from "./types.js";
+import { isoNow, isPidAlive, maybeUnlink, shellQuote, writeJsonAtomic } from "./utils.js";
+
+export function createWrapperScript(record: LockRecord, wrapperPath: string): string {
+	const setupPath = shellQuote(record.setupPath);
+	const repoRoot = shellQuote(record.repoRoot);
+	const lockPath = shellQuote(record.lockPath);
+	const exitPath = shellQuote(record.exitPath);
+	return `#!/bin/zsh
+set +e
+write_exit() {
+  local code="$1"
+  local setup_status="failed"
+  if [ "$code" = "0" ]; then
+    setup_status="success"
+  elif [ "$code" = "130" ] || [ "$code" = "143" ]; then
+    setup_status="cancelled"
+  fi
+  local finished_at="$(date -u '+%Y-%m-%dT%H:%M:%SZ')"
+  printf '{"status":"%s","exitCode":%s,"finishedAt":"%s"}\n' "$setup_status" "$code" "$finished_at" > ${exitPath}.tmp
+  mv ${exitPath}.tmp ${exitPath}
+  rm -f ${lockPath}
+}
+trap 'write_exit 130; exit 130' INT TERM HUP
+printf '▶ setup.sh start %s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')"
+cd ${repoRoot}
+/bin/zsh ${setupPath}
+code=$?
+write_exit "$code"
+printf '■ setup.sh exit %s\n' "$code"
+rm -f ${shellQuote(wrapperPath)}
+exit "$code"
+`;
+}
+
+function initialLockRecord(context: SetupContext, runId: string, startedAt: string): LockRecord {
+	const logPath = path.join(context.paths.logsDir, `${context.repoKey}-${runId}.log`);
+	const exitPath = path.join(context.paths.exitsDir, `${context.repoKey}-${runId}.exit.json`);
+	return {
+		repoKey: context.repoKey,
+		repoRoot: context.repoRoot,
+		setupPath: context.setupPath,
+		setupHash: context.setupHash,
+		runId,
+		pid: process.pid,
+		coordinatorPid: process.pid,
+		startedAt,
+		logPath,
+		exitPath,
+		lockPath: context.paths.lockPath,
+	};
+}
+
+async function handleLockedSetup(context: SetupContext): Promise<StartResult> {
+	const running = await finalizeRunIfNeeded(context);
+	return running?.status === "running"
+		? { kind: "running", context, record: running, owner: running.coordinatorPid === process.pid ? "self" : "other" }
+		: { kind: "skipped", context, record: running ?? undefined, reason: "setup.sh is locked by another session" };
+}
+
+async function spawnSetup(context: SetupContext, record: LockRecord, mode: StartMode): Promise<StartResult> {
+	const wrapperPath = path.join(context.paths.wrappersDir, `${context.repoKey}-${record.runId}.zsh`);
+	try {
+		const logFd = openSync(record.logPath, "a");
+		try {
+			writeFileSync(wrapperPath, createWrapperScript(record, wrapperPath), "utf-8");
+			await chmod(wrapperPath, 0o700);
+			const child = spawn("/bin/zsh", [wrapperPath], {
+				cwd: context.repoRoot,
+				detached: true,
+				stdio: ["ignore", logFd, logFd],
+				env: process.env,
+			});
+			child.unref();
+
+			if (!child.pid) throw new Error("Failed to start setup.sh");
+
+			const run: RunRecord = { ...record, pid: child.pid, status: "running", mode };
+			await writeJsonAtomic(context.paths.lockPath, run);
+			await writeJsonAtomic(context.paths.statePath, run);
+			child.on("exit", () => {
+				void finalizeRunIfNeeded(context);
+			});
+			return { kind: "started", context, record: run };
+		} finally {
+			closeSync(logFd);
+		}
+	} catch (error) {
+		await maybeUnlink(context.paths.lockPath);
+		const failed: RunRecord = {
+			...record,
+			status: "failed",
+			mode,
+			finishedAt: isoNow(),
+			message: error instanceof Error ? error.message : String(error),
+		};
+		await writeJsonAtomic(context.paths.statePath, failed);
+		return { kind: "failed", context, reason: failed.message ?? "Failed to start setup.sh" };
+	}
+}
+
+export async function startSetup(cwd: string, mode: StartMode): Promise<StartResult> {
+	let context: SetupContext | null = null;
+	try {
+		context = resolveSetupContext(cwd);
+	} catch (error) {
+		return { kind: "failed", reason: error instanceof Error ? error.message : String(error) };
+	}
+
+	if (!context) return { kind: "no-setup", reason: "setup.sh not found" };
+	await ensureStateDirs(context.paths);
+	const current = await finalizeRunIfNeeded(context);
+	if (current?.status === "running") {
+		return {
+			kind: "running",
+			context,
+			record: current,
+			owner: current.coordinatorPid === process.pid ? "self" : "other",
+		};
+	}
+
+	if (mode === "auto" && current?.status === "success" && current.setupHash === context.setupHash) {
+		return { kind: "skipped", context, record: current, reason: "setup.sh already completed for this folder" };
+	}
+
+	const runId = `${Date.now()}-${process.pid}`;
+	const record = initialLockRecord(context, runId, isoNow());
+	const lockResult = await createLock(context, record);
+	if (lockResult === "locked") return handleLockedSetup(context);
+	return spawnSetup(context, record, mode);
+}
+
+export async function cancelSetup(context: SetupContext): Promise<string> {
+	const record = await finalizeRunIfNeeded(context);
+	if (!record || record.status !== "running") return "실행 중인 setup.sh가 없습니다.";
+	if (!isPidAlive(record.pid)) {
+		await finalizeRunIfNeeded(context);
+		return "setup.sh 프로세스가 이미 종료되었습니다.";
+	}
+	try {
+		process.kill(-record.pid, "SIGTERM");
+	} catch {
+		try {
+			process.kill(record.pid, "SIGTERM");
+		} catch (error) {
+			return `setup.sh 종료 신호 전송 실패: ${error instanceof Error ? error.message : String(error)}`;
+		}
+	}
+	return `setup.sh 종료 신호를 보냈습니다. pid=${record.pid}`;
+}

package/state.ts

@@ -0,0 +1,88 @@
+import { mkdir, open } from "node:fs/promises";
+import { LOCK_STALE_MS } from "./constants.js";
+import type { ExitRecord, LockRecord, RunRecord, SetupContext, StatePaths } from "./types.js";
+import { elapsedMs, isoNow, isPidAlive, maybeUnlink, readJson, writeJsonAtomic } from "./utils.js";
+
+export async function ensureStateDirs(
+	paths: Pick<StatePaths, "rootDir" | "locksDir" | "logsDir" | "statesDir" | "exitsDir" | "wrappersDir">,
+): Promise<void> {
+	await Promise.all([
+		mkdir(paths.rootDir, { recursive: true }),
+		mkdir(paths.locksDir, { recursive: true }),
+		mkdir(paths.logsDir, { recursive: true }),
+		mkdir(paths.statesDir, { recursive: true }),
+		mkdir(paths.exitsDir, { recursive: true }),
+		mkdir(paths.wrappersDir, { recursive: true }),
+	]);
+}
+
+export async function finalizeRunIfNeeded(context: SetupContext): Promise<RunRecord | null> {
+	const record = await readJson<RunRecord>(context.paths.statePath);
+	if (!record) {
+		const lock = await readJson<LockRecord>(context.paths.lockPath);
+		if (lock && isPidAlive(lock.pid)) return { ...lock, status: "running", mode: "auto" };
+		if (lock) await maybeUnlink(context.paths.lockPath);
+		return null;
+	}
+	if (record.status !== "running") return record;
+
+	const exitRecord = await readJson<ExitRecord>(record.exitPath);
+	if (exitRecord) {
+		const next: RunRecord = {
+			...record,
+			status: exitRecord.status,
+			exitCode: exitRecord.exitCode,
+			finishedAt: exitRecord.finishedAt,
+			message:
+				exitRecord.status === "success"
+					? "setup.sh completed"
+					: exitRecord.status === "cancelled"
+						? "setup.sh cancelled"
+						: `setup.sh exited with code ${exitRecord.exitCode}`,
+		};
+		await writeJsonAtomic(context.paths.statePath, next);
+		await maybeUnlink(context.paths.lockPath);
+		return next;
+	}
+
+	const lock = await readJson<LockRecord>(context.paths.lockPath);
+	if (lock && isPidAlive(lock.pid)) return record;
+
+	const lockAge = lock ? elapsedMs(lock.startedAt) : elapsedMs(record.startedAt);
+	if (!lock || lockAge > LOCK_STALE_MS || !isPidAlive(record.pid)) {
+		const next: RunRecord = {
+			...record,
+			status: "stale",
+			finishedAt: isoNow(),
+			message: "setup.sh stopped without writing an exit status",
+		};
+		await writeJsonAtomic(context.paths.statePath, next);
+		await maybeUnlink(context.paths.lockPath);
+		return next;
+	}
+
+	return record;
+}
+
+export async function createLock(context: SetupContext, record: LockRecord): Promise<"acquired" | "locked"> {
+	await ensureStateDirs(context.paths);
+	for (let attempt = 0; attempt < 2; attempt++) {
+		try {
+			const handle = await open(context.paths.lockPath, "wx");
+			try {
+				await handle.writeFile(`${JSON.stringify(record, null, 2)}\n`, "utf-8");
+			} finally {
+				await handle.close();
+			}
+			return "acquired";
+		} catch (error) {
+			const code = typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+			if (code !== "EEXIST") throw error;
+
+			const existing = await readJson<LockRecord>(context.paths.lockPath);
+			if (existing && isPidAlive(existing.pid)) return "locked";
+			await maybeUnlink(context.paths.lockPath);
+		}
+	}
+	return "locked";
+}

package/types.ts

@@ -0,0 +1,69 @@
+export type SetupStatus = "running" | "success" | "failed" | "cancelled" | "stale";
+export type DisplayStatus = SetupStatus | "pending" | "skipped";
+export type StartMode = "auto" | "manual" | "rerun";
+
+export type SetupContext = {
+	repoRoot: string;
+	setupPath: string;
+	repoKey: string;
+	setupHash: string;
+	paths: StatePaths;
+};
+
+export type StatePaths = {
+	rootDir: string;
+	locksDir: string;
+	logsDir: string;
+	statesDir: string;
+	exitsDir: string;
+	wrappersDir: string;
+	lockPath: string;
+	statePath: string;
+};
+
+export type LockRecord = {
+	repoKey: string;
+	repoRoot: string;
+	setupPath: string;
+	setupHash: string;
+	runId: string;
+	pid: number;
+	coordinatorPid: number;
+	startedAt: string;
+	logPath: string;
+	exitPath: string;
+	lockPath: string;
+};
+
+export type RunRecord = LockRecord & {
+	status: SetupStatus;
+	mode: StartMode;
+	finishedAt?: string;
+	exitCode?: number;
+	message?: string;
+};
+
+export type ExitRecord = {
+	status: SetupStatus;
+	exitCode: number;
+	finishedAt: string;
+};
+
+export type StartResult =
+	| { kind: "started"; context: SetupContext; record: RunRecord }
+	| { kind: "running"; context: SetupContext; record: RunRecord; owner: "self" | "other" }
+	| { kind: "skipped"; context: SetupContext; record?: RunRecord; reason: string }
+	| { kind: "no-setup"; reason: string }
+	| { kind: "failed"; context?: SetupContext; reason: string };
+
+export type Snapshot = {
+	visible: boolean;
+	status: DisplayStatus;
+	repoRoot: string;
+	owner: "self" | "other" | "none";
+	startedAt?: string;
+	finishedAt?: string;
+	exitCode?: number;
+	message?: string;
+	logPath?: string;
+};

package/utils.ts

@@ -0,0 +1,140 @@
+import { readFileSync, statSync } from "node:fs";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import * as path from "node:path";
+import { LOG_TAIL_LINES } from "./constants.js";
+
+export async function readJson<T>(filePath: string): Promise<T | null> {
+	try {
+		return JSON.parse(await readFile(filePath, "utf-8")) as T;
+	} catch {
+		return null;
+	}
+}
+
+export async function writeJsonAtomic(filePath: string, value: unknown): Promise<void> {
+	await mkdir(path.dirname(filePath), { recursive: true });
+	const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+	await writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`, "utf-8");
+	await rename(tmp, filePath);
+}
+
+export function isPidAlive(pid: number | undefined): boolean {
+	if (!pid || !Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		const code = typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+		return code === "EPERM";
+	}
+}
+
+export function isoNow(): string {
+	return new Date().toISOString();
+}
+
+export function elapsedMs(startedAt?: string, finishedAt?: string): number {
+	if (!startedAt) return 0;
+	const start = Date.parse(startedAt);
+	if (!Number.isFinite(start)) return 0;
+	const end = finishedAt ? Date.parse(finishedAt) : Date.now();
+	return Math.max(0, end - start);
+}
+
+export function formatDuration(ms: number): string {
+	const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+	const minutes = Math.floor(totalSeconds / 60);
+	const seconds = totalSeconds % 60;
+	return `${minutes}:${seconds.toString().padStart(2, "0")}`;
+}
+
+function skipCsi(value: string, index: number): number {
+	let next = index + 1;
+	while (next < value.length) {
+		const code = value.charCodeAt(next);
+		next++;
+		if (code >= 0x40 && code <= 0x7e) break;
+	}
+	return next;
+}
+
+function skipOsc(value: string, index: number): number {
+	let next = index + 1;
+	while (next < value.length) {
+		if (value.charCodeAt(next) === 0x07) return next + 1;
+		if (value.charCodeAt(next) === 0x1b && value[next + 1] === "\\") return next + 2;
+		next++;
+	}
+	return next;
+}
+
+export function stripAnsi(value: string): string {
+	let output = "";
+	let index = 0;
+	while (index < value.length) {
+		if (value.charCodeAt(index) !== 0x1b) {
+			output += value[index];
+			index++;
+			continue;
+		}
+
+		const marker = value[index + 1];
+		if (marker === "[") {
+			index = skipCsi(value, index + 1);
+		} else if (marker === "]") {
+			index = skipOsc(value, index + 1);
+		} else {
+			index++;
+		}
+	}
+	return output;
+}
+
+export function readLastLogLine(logPath: string | undefined): string | undefined {
+	if (!logPath) return undefined;
+	let text = "";
+	try {
+		text = readFileSync(logPath, "utf-8");
+	} catch {
+		return undefined;
+	}
+	const lines = text
+		.split(/\r?\n/)
+		.map((line) => stripAnsi(line).trim())
+		.filter((line) => line.length > 0);
+	return lines.at(-1);
+}
+
+export function readLogTail(logPath: string | undefined, maxLines = LOG_TAIL_LINES): string[] {
+	if (!logPath) return [];
+	try {
+		return readFileSync(logPath, "utf-8")
+			.split(/\r?\n/)
+			.map((line) => stripAnsi(line).trimEnd())
+			.filter((line) => line.trim().length > 0)
+			.slice(-maxLines);
+	} catch {
+		return [];
+	}
+}
+
+export function getLogIdleMs(logPath: string | undefined, startedAt?: string): number {
+	try {
+		if (logPath) return Date.now() - statSync(logPath).mtimeMs;
+	} catch {
+		// Fall through to startedAt based idle duration.
+	}
+	return elapsedMs(startedAt);
+}
+
+export async function maybeUnlink(filePath: string): Promise<void> {
+	try {
+		await unlink(filePath);
+	} catch {
+		// Ignore missing files and concurrent cleanup.
+	}
+}
+
+export function shellQuote(value: string): string {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}

package/widget.ts

@@ -0,0 +1,135 @@
+import type { ExtensionContext, Theme } from "@mariozechner/pi-coding-agent";
+import type { TUI } from "@mariozechner/pi-tui";
+import { truncateToWidth } from "@mariozechner/pi-tui";
+import { PENDING_AFTER_MS, STATUS_KEY, WIDGET_KEY } from "./constants.js";
+import { displayPath } from "./context.js";
+import { finalizeRunIfNeeded } from "./state.js";
+import type { DisplayStatus, RunRecord, SetupContext, Snapshot } from "./types.js";
+import { elapsedMs, formatDuration, getLogIdleMs, readLastLogLine, readLogTail } from "./utils.js";
+
+export type Watcher = {
+	context: SetupContext;
+	interval: ReturnType<typeof setInterval>;
+	snapshot: Snapshot | null;
+	tui: TUI | null;
+	disposed: boolean;
+};
+
+export function snapshotFromRecord(record: RunRecord, localPid = process.pid): Snapshot {
+	const logIdleMs = getLogIdleMs(record.logPath, record.startedAt);
+	const status: DisplayStatus = record.status === "running" && logIdleMs > PENDING_AFTER_MS ? "pending" : record.status;
+	const message =
+		record.status === "running" ? readLastLogLine(record.logPath) : (record.message ?? readLastLogLine(record.logPath));
+	return {
+		visible: true,
+		status,
+		repoRoot: record.repoRoot,
+		owner: record.coordinatorPid === localPid ? "self" : "other",
+		startedAt: record.startedAt,
+		finishedAt: record.finishedAt,
+		exitCode: record.exitCode,
+		message,
+		logPath: record.logPath,
+	};
+}
+
+export async function getSnapshot(context: SetupContext): Promise<Snapshot | null> {
+	const record = await finalizeRunIfNeeded(context);
+	if (!record || record.status === "success") return null;
+	return snapshotFromRecord(record);
+}
+
+export function formatSnapshotLine(snapshot: Snapshot, theme: Pick<Theme, "fg">): string {
+	const duration = formatDuration(elapsedMs(snapshot.startedAt, snapshot.finishedAt));
+	const repo = displayPath(snapshot.repoRoot);
+	const owner =
+		snapshot.owner === "other" && (snapshot.status === "running" || snapshot.status === "pending") ? " elsewhere" : "";
+	const exit = snapshot.exitCode !== undefined && snapshot.status !== "success" ? ` exit ${snapshot.exitCode}` : "";
+	const suffix = snapshot.message ? ` · ${snapshot.message}` : "";
+
+	if (snapshot.status === "success") return `${theme.fg("success", "✅")} setup.sh done ${duration} · ${repo}`;
+	if (snapshot.status === "failed") {
+		return `${theme.fg("error", "❌")} setup.sh failed${exit} · ${repo}${suffix} · /setup-sh status`;
+	}
+	if (snapshot.status === "cancelled") return `${theme.fg("warning", "⚠️")} setup.sh cancelled · ${repo}${suffix}`;
+	if (snapshot.status === "stale") {
+		return `${theme.fg("warning", "⚠️")} setup.sh stale · ${repo}${suffix} · /setup-sh rerun`;
+	}
+	if (snapshot.status === "pending") {
+		return `${theme.fg("warning", "⏳")} setup.sh pending${owner} ${duration} · ${repo}${suffix}`;
+	}
+	return `${theme.fg("accent", "🔧")} setup.sh running${owner} ${duration} · ${repo}${suffix}`;
+}
+
+export function plainSnapshotLine(snapshot: Snapshot): string {
+	return formatSnapshotLine(snapshot, { fg: (_color, text) => text });
+}
+
+export function renderWidgetLine(snapshot: Snapshot | null, width: number, theme: Pick<Theme, "fg">): string[] {
+	if (!snapshot?.visible) return [];
+	return [truncateToWidth(formatSnapshotLine(snapshot, theme), width, "…")];
+}
+
+export function updateStatus(ctx: ExtensionContext, snapshot: Snapshot | null): void {
+	if (!snapshot?.visible) {
+		ctx.ui.setStatus(STATUS_KEY, undefined);
+		return;
+	}
+	if (snapshot.status === "failed" || snapshot.status === "stale") {
+		ctx.ui.setStatus(STATUS_KEY, ctx.ui.theme.fg("error", "❌ setup"));
+		return;
+	}
+	if (snapshot.status === "pending") {
+		ctx.ui.setStatus(STATUS_KEY, ctx.ui.theme.fg("warning", "⏳ setup"));
+		return;
+	}
+	if (snapshot.status === "running") {
+		ctx.ui.setStatus(STATUS_KEY, ctx.ui.theme.fg("accent", "🔧 setup"));
+		return;
+	}
+	ctx.ui.setStatus(STATUS_KEY, undefined);
+}
+
+export function installWidget(ctx: ExtensionContext, watcher: Watcher): void {
+	if (!ctx.hasUI) return;
+	ctx.ui.setWidget(WIDGET_KEY, (tui: TUI, theme: Theme) => {
+		watcher.tui = tui;
+		return {
+			render: (width: number) => renderWidgetLine(watcher.snapshot, width || tui.terminal?.columns || 120, theme),
+			invalidate: () => {},
+		};
+	});
+}
+
+export async function refreshWatcher(ctx: ExtensionContext, watcher: Watcher): Promise<void> {
+	if (watcher.disposed) return;
+	watcher.snapshot = await getSnapshot(watcher.context);
+	updateStatus(ctx, watcher.snapshot);
+	if (!watcher.snapshot) {
+		ctx.ui.setWidget(WIDGET_KEY, undefined);
+		return;
+	}
+	watcher.tui?.requestRender();
+}
+
+export function stopWatcher(ctx: ExtensionContext, watcher: Watcher | null): void {
+	if (!watcher) return;
+	watcher.disposed = true;
+	clearInterval(watcher.interval);
+	ctx.ui.setWidget(WIDGET_KEY, undefined);
+	ctx.ui.setStatus(STATUS_KEY, undefined);
+}
+
+export async function showStatus(ctx: ExtensionContext, context: SetupContext): Promise<void> {
+	const record = await finalizeRunIfNeeded(context);
+	if (!record) {
+		ctx.ui.notify(`setup.sh 상태 없음: ${displayPath(context.repoRoot)}`, "info");
+		return;
+	}
+	const snapshot = snapshotFromRecord(record);
+	const tail = readLogTail(record.logPath);
+	const body = [plainSnapshotLine(snapshot), `Log: ${record.logPath}`, tail.length > 0 ? "" : undefined, ...tail]
+		.filter((line): line is string => line !== undefined)
+		.join("\n");
+	ctx.ui.notify(body, record.status === "failed" || record.status === "stale" ? "error" : "info");
+}