@ag-eco/agentplate-cli 0.13.0

package/src/utils/bin.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, test } from "bun:test";
+import { resolveAgentplateBin } from "./bin.ts";
+
+describe("resolveAgentplateBin", () => {
+	test("returns a non-empty string", async () => {
+		const bin = await resolveAgentplateBin();
+		expect(typeof bin).toBe("string");
+		expect(bin.length).toBeGreaterThan(0);
+	});
+});

package/src/utils/bin.ts

@@ -0,0 +1,37 @@
+/**
+ * Binary resolution utilities.
+ */
+import { AgentplateError } from "../errors.ts";
+
+/**
+ * Resolve the path to the agentplate binary for re-launching.
+ * Uses `which ap` first, then falls back to process.argv.
+ */
+export async function resolveAgentplateBin(): Promise<string> {
+	try {
+		const proc = Bun.spawn(["which", "ap"], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		const exitCode = await proc.exited;
+		if (exitCode === 0) {
+			const binPath = (await new Response(proc.stdout).text()).trim();
+			if (binPath.length > 0) {
+				return binPath;
+			}
+		}
+	} catch {
+		// which not available or agentplate not on PATH
+	}
+
+	// Fallback: use the script that's currently running (process.argv[1])
+	const scriptPath = process.argv[1];
+	if (scriptPath) {
+		return scriptPath;
+	}
+
+	throw new AgentplateError(
+		"Cannot resolve agentplate binary path for background launch",
+		"WATCH_ERROR",
+	);
+}

package/src/utils/browser.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from "bun:test";
+import { browserOpenCommand, openBrowser } from "./browser.ts";
+
+describe("browserOpenCommand", () => {
+	test("uses `open` on darwin", () => {
+		expect(browserOpenCommand("http://localhost:7321", "darwin")).toEqual([
+			"open",
+			"http://localhost:7321",
+		]);
+	});
+
+	test("uses `cmd /c start` with empty title on win32", () => {
+		expect(browserOpenCommand("http://localhost:7321", "win32")).toEqual([
+			"cmd",
+			"/c",
+			"start",
+			"",
+			"http://localhost:7321",
+		]);
+	});
+
+	test("uses `xdg-open` on linux/other", () => {
+		expect(browserOpenCommand("http://localhost:7321", "linux")).toEqual([
+			"xdg-open",
+			"http://localhost:7321",
+		]);
+	});
+});
+
+describe("openBrowser", () => {
+	test("spawns the resolved command and returns true", () => {
+		let received: string[] | null = null;
+		const fakeSpawn = ((cmd: string[]) => {
+			received = cmd;
+			return { unref() {} } as unknown as ReturnType<typeof Bun.spawn>;
+		}) as typeof Bun.spawn;
+
+		const ok = openBrowser("http://localhost:7321", fakeSpawn, "darwin");
+		expect(ok).toBe(true);
+		expect(received as string[] | null).toEqual(["open", "http://localhost:7321"]);
+	});
+
+	test("returns false (never throws) when spawn fails", () => {
+		const throwingSpawn = (() => {
+			throw new Error("no GUI");
+		}) as typeof Bun.spawn;
+		expect(openBrowser("http://localhost:7321", throwingSpawn, "linux")).toBe(false);
+	});
+});

package/src/utils/browser.ts

@@ -0,0 +1,48 @@
+/**
+ * Best-effort cross-platform browser launcher for `ap dashboard ui`.
+ *
+ * Resolves the platform's "open a URL in the default browser" command and
+ * spawns it detached. Never throws — a failed launch (headless CI, no GUI,
+ * missing `xdg-open`) just means the operator opens the printed URL manually.
+ */
+
+type SpawnFn = typeof Bun.spawn;
+
+/**
+ * Resolve the argv used to open `url` in the default browser on `platform`.
+ *  - darwin: `open <url>`
+ *  - win32:  `cmd /c start "" <url>` (empty title arg so a quoted URL isn't
+ *            mistaken for the window title)
+ *  - else:   `xdg-open <url>` (Linux/BSD desktops)
+ */
+export function browserOpenCommand(
+	url: string,
+	platform: NodeJS.Platform = process.platform,
+): string[] {
+	if (platform === "darwin") return ["open", url];
+	if (platform === "win32") return ["cmd", "/c", "start", "", url];
+	return ["xdg-open", url];
+}
+
+/**
+ * Open `url` in the default browser. Best-effort: returns `true` when the
+ * launcher was spawned, `false` on any failure. `spawn`/`platform` are
+ * injectable for tests.
+ */
+export function openBrowser(
+	url: string,
+	spawn: SpawnFn = Bun.spawn,
+	platform: NodeJS.Platform = process.platform,
+): boolean {
+	try {
+		const proc = spawn(browserOpenCommand(url, platform), {
+			stdout: "ignore",
+			stderr: "ignore",
+			stdin: "ignore",
+		});
+		proc.unref();
+		return true;
+	} catch {
+		return false;
+	}
+}

package/src/utils/fs.test.ts

@@ -0,0 +1,119 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, readdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { cleanupTempDir } from "../test-helpers.ts";
+import { clearDirectory, deleteFile, resetJsonFile, wipeSqliteDb } from "./fs.ts";
+
+let tempDir: string;
+
+beforeEach(async () => {
+	tempDir = await mkdtemp(join(tmpdir(), "ap-fs-test-"));
+});
+
+afterEach(async () => {
+	await cleanupTempDir(tempDir);
+});
+
+describe("wipeSqliteDb", () => {
+	test("deletes main db and WAL/SHM companion files", async () => {
+		const dbPath = join(tempDir, "test-wipe.db");
+		const { Database } = await import("bun:sqlite");
+		const db = new Database(dbPath);
+		db.exec("PRAGMA journal_mode=WAL");
+		db.exec("CREATE TABLE t (id INTEGER PRIMARY KEY)");
+		db.exec("INSERT INTO t VALUES (1)");
+		db.close();
+
+		expect(existsSync(dbPath)).toBe(true);
+
+		const result = await wipeSqliteDb(dbPath);
+		expect(result).toBe(true);
+
+		expect(existsSync(dbPath)).toBe(false);
+		expect(existsSync(`${dbPath}-wal`)).toBe(false);
+		expect(existsSync(`${dbPath}-shm`)).toBe(false);
+	});
+
+	test("returns false when db file does not exist", async () => {
+		const dbPath = join(tempDir, "nonexistent.db");
+		const result = await wipeSqliteDb(dbPath);
+		expect(result).toBe(false);
+	});
+});
+
+describe("resetJsonFile", () => {
+	test("resets existing JSON file to empty array", async () => {
+		const filePath = join(tempDir, "test-reset.json");
+		await Bun.write(filePath, '[{"id":"1"},{"id":"2"}]');
+
+		const result = await resetJsonFile(filePath);
+		expect(result).toBe(true);
+
+		const content = await Bun.file(filePath).text();
+		expect(content).toBe("[]\n");
+	});
+
+	test("returns false for nonexistent file", async () => {
+		const filePath = join(tempDir, "nonexistent.json");
+		const result = await resetJsonFile(filePath);
+		expect(result).toBe(false);
+	});
+});
+
+describe("clearDirectory", () => {
+	test("clears files from a directory", async () => {
+		const dirPath = join(tempDir, "clear-test");
+		await mkdir(dirPath, { recursive: true });
+		await writeFile(join(dirPath, "file1.txt"), "hello");
+		await writeFile(join(dirPath, "file2.txt"), "world");
+
+		const result = await clearDirectory(dirPath);
+		expect(result).toBe(true);
+
+		const entries = await readdir(dirPath);
+		expect(entries).toHaveLength(0);
+	});
+
+	test("returns false for empty directory", async () => {
+		const dirPath = join(tempDir, "empty-dir");
+		await mkdir(dirPath, { recursive: true });
+
+		const result = await clearDirectory(dirPath);
+		expect(result).toBe(false);
+	});
+
+	test("returns false for nonexistent directory", async () => {
+		const result = await clearDirectory(join(tempDir, "no-such-dir"));
+		expect(result).toBe(false);
+	});
+
+	test("recursively removes subdirectories", async () => {
+		const dirPath = join(tempDir, "nested-clear");
+		await mkdir(join(dirPath, "sub", "deep"), { recursive: true });
+		await writeFile(join(dirPath, "sub", "deep", "file.txt"), "data");
+
+		const result = await clearDirectory(dirPath);
+		expect(result).toBe(true);
+
+		const entries = await readdir(dirPath);
+		expect(entries).toHaveLength(0);
+	});
+});
+
+describe("deleteFile", () => {
+	test("deletes an existing file", async () => {
+		const filePath = join(tempDir, "to-delete.txt");
+		await writeFile(filePath, "delete me");
+
+		const result = await deleteFile(filePath);
+		expect(result).toBe(true);
+		expect(existsSync(filePath)).toBe(false);
+	});
+
+	test("returns false for nonexistent file", async () => {
+		const result = await deleteFile(join(tempDir, "no-such-file.txt"));
+		expect(result).toBe(false);
+	});
+});

package/src/utils/fs.ts

@@ -0,0 +1,62 @@
+/**
+ * Filesystem utility functions for cleanup and state management.
+ */
+import { readdir, rm, unlink } from "node:fs/promises";
+import { join } from "node:path";
+
+/**
+ * Delete a SQLite database file and its WAL/SHM companions.
+ */
+export async function wipeSqliteDb(dbPath: string): Promise<boolean> {
+	const extensions = ["", "-wal", "-shm"];
+	let wiped = false;
+	for (const ext of extensions) {
+		try {
+			await unlink(`${dbPath}${ext}`);
+			if (ext === "") wiped = true;
+		} catch {
+			// File may not exist
+		}
+	}
+	return wiped;
+}
+
+/**
+ * Reset a JSON file to an empty array.
+ */
+export async function resetJsonFile(path: string): Promise<boolean> {
+	const file = Bun.file(path);
+	if (await file.exists()) {
+		await Bun.write(path, "[]\n");
+		return true;
+	}
+	return false;
+}
+
+/**
+ * Clear all entries inside a directory but keep the directory itself.
+ */
+export async function clearDirectory(dirPath: string): Promise<boolean> {
+	try {
+		const entries = await readdir(dirPath);
+		for (const entry of entries) {
+			await rm(join(dirPath, entry), { recursive: true, force: true });
+		}
+		return entries.length > 0;
+	} catch {
+		// Directory may not exist
+		return false;
+	}
+}
+
+/**
+ * Delete a single file if it exists.
+ */
+export async function deleteFile(path: string): Promise<boolean> {
+	try {
+		await unlink(path);
+		return true;
+	} catch {
+		return false;
+	}
+}

package/src/utils/pid.test.ts

@@ -0,0 +1,152 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { cleanupTempDir } from "../test-helpers.ts";
+import { acquirePidLock, readPidFile, removePidFile, writePidFile } from "./pid.ts";
+
+let tempDir: string;
+
+beforeEach(async () => {
+	tempDir = await mkdtemp(join(tmpdir(), "ap-pid-test-"));
+});
+
+afterEach(async () => {
+	await cleanupTempDir(tempDir);
+});
+
+describe("readPidFile", () => {
+	test("returns pid from valid file", async () => {
+		const pidPath = join(tempDir, "test.pid");
+		await Bun.write(pidPath, "12345\n");
+		const pid = await readPidFile(pidPath);
+		expect(pid).toBe(12345);
+	});
+
+	test("returns null for nonexistent file", async () => {
+		const pid = await readPidFile(join(tempDir, "missing.pid"));
+		expect(pid).toBeNull();
+	});
+
+	test("returns null for non-numeric content", async () => {
+		const pidPath = join(tempDir, "bad.pid");
+		await Bun.write(pidPath, "not-a-number\n");
+		const pid = await readPidFile(pidPath);
+		expect(pid).toBeNull();
+	});
+
+	test("returns null for negative pid", async () => {
+		const pidPath = join(tempDir, "neg.pid");
+		await Bun.write(pidPath, "-1\n");
+		const pid = await readPidFile(pidPath);
+		expect(pid).toBeNull();
+	});
+});
+
+describe("writePidFile", () => {
+	test("roundtrip write then read", async () => {
+		const pidPath = join(tempDir, "roundtrip.pid");
+		await writePidFile(pidPath, 42);
+		const pid = await readPidFile(pidPath);
+		expect(pid).toBe(42);
+	});
+});
+
+describe("removePidFile", () => {
+	test("removes existing file", async () => {
+		const pidPath = join(tempDir, "remove.pid");
+		await Bun.write(pidPath, "99\n");
+		expect(await Bun.file(pidPath).exists()).toBe(true);
+		await removePidFile(pidPath);
+		expect(await Bun.file(pidPath).exists()).toBe(false);
+	});
+
+	test("does not throw for nonexistent file", async () => {
+		await removePidFile(join(tempDir, "nope.pid"));
+		// No throw = pass
+	});
+});
+
+describe("acquirePidLock", () => {
+	const alwaysAlive = (_pid: number) => true;
+	const alwaysDead = (_pid: number) => false;
+
+	test("acquires when no lock file exists", async () => {
+		const pidPath = join(tempDir, "lock.pid");
+		const result = await acquirePidLock(pidPath, 1234, alwaysAlive);
+		expect(result.acquired).toBe(true);
+		expect(await readPidFile(pidPath)).toBe(1234);
+	});
+
+	test("creates parent directory if missing", async () => {
+		const pidPath = join(tempDir, "nested", "deeper", "lock.pid");
+		const result = await acquirePidLock(pidPath, 555, alwaysAlive);
+		expect(result.acquired).toBe(true);
+		expect(await readPidFile(pidPath)).toBe(555);
+	});
+
+	test("refuses when a live foreign PID owns the lock", async () => {
+		const pidPath = join(tempDir, "lock.pid");
+		await Bun.write(pidPath, "9999\n");
+		const result = await acquirePidLock(pidPath, 1234, alwaysAlive);
+		expect(result.acquired).toBe(false);
+		if (!result.acquired) {
+			expect(result.existingPid).toBe(9999);
+		}
+		// File untouched.
+		expect(await readPidFile(pidPath)).toBe(9999);
+	});
+
+	test("idempotent when file already contains caller's own PID", async () => {
+		const pidPath = join(tempDir, "lock.pid");
+		await Bun.write(pidPath, "1234\n");
+		// alwaysAlive would say 1234 is alive, but acquirePidLock should detect
+		// own-PID first and accept.
+		const result = await acquirePidLock(pidPath, 1234, alwaysAlive);
+		expect(result.acquired).toBe(true);
+		expect(await readPidFile(pidPath)).toBe(1234);
+	});
+
+	test("reclaims stale lock with dead PID", async () => {
+		const pidPath = join(tempDir, "lock.pid");
+		await Bun.write(pidPath, "9999\n");
+		const result = await acquirePidLock(pidPath, 1234, alwaysDead);
+		expect(result.acquired).toBe(true);
+		expect(await readPidFile(pidPath)).toBe(1234);
+	});
+
+	test("reclaims unreadable/corrupted lock file", async () => {
+		const pidPath = join(tempDir, "lock.pid");
+		await Bun.write(pidPath, "garbage-not-a-pid\n");
+		const result = await acquirePidLock(pidPath, 1234, alwaysAlive);
+		expect(result.acquired).toBe(true);
+		expect(await readPidFile(pidPath)).toBe(1234);
+	});
+
+	test("two simultaneous acquirers — only one wins", async () => {
+		const pidPath = join(tempDir, "lock.pid");
+		const [a, b] = await Promise.all([
+			acquirePidLock(pidPath, 1111, alwaysAlive),
+			acquirePidLock(pidPath, 2222, alwaysAlive),
+		]);
+		const winners = [a, b].filter((r) => r.acquired);
+		const losers = [a, b].filter((r) => !r.acquired);
+		expect(winners.length).toBe(1);
+		expect(losers.length).toBe(1);
+		const loser = losers[0];
+		if (loser && !loser.acquired) {
+			expect([1111, 2222]).toContain(loser.existingPid);
+		}
+	});
+
+	test("two simultaneous acquirers — file content matches the winner", async () => {
+		const pidPath = join(tempDir, "lock.pid");
+		const [a, b] = await Promise.all([
+			acquirePidLock(pidPath, 1111, alwaysAlive),
+			acquirePidLock(pidPath, 2222, alwaysAlive),
+		]);
+		const fileContent = await readPidFile(pidPath);
+		const winnerPid = a.acquired ? 1111 : b.acquired ? 2222 : -1;
+		expect(fileContent).toBe(winnerPid);
+	});
+});

package/src/utils/pid.ts

@@ -0,0 +1,130 @@
+/**
+ * PID file management for daemon processes.
+ */
+import { randomUUID } from "node:crypto";
+import { link, mkdir, unlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+/**
+ * Read the PID from a PID file.
+ * Returns null if the file doesn't exist or can't be parsed.
+ */
+export async function readPidFile(pidFilePath: string): Promise<number | null> {
+	const file = Bun.file(pidFilePath);
+	const exists = await file.exists();
+	if (!exists) {
+		return null;
+	}
+
+	try {
+		const text = await file.text();
+		const pid = Number.parseInt(text.trim(), 10);
+		if (Number.isNaN(pid) || pid <= 0) {
+			return null;
+		}
+		return pid;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Write a PID to a PID file.
+ */
+export async function writePidFile(pidFilePath: string, pid: number): Promise<void> {
+	await Bun.write(pidFilePath, `${pid}\n`);
+}
+
+/**
+ * Remove a PID file.
+ */
+export async function removePidFile(pidFilePath: string): Promise<void> {
+	try {
+		await unlink(pidFilePath);
+	} catch {
+		// File may already be gone — not an error
+	}
+}
+
+/**
+ * Result of acquirePidLock.
+ *
+ * `acquired: true` — caller owns the lock and is responsible for removing the
+ * PID file on shutdown.
+ *
+ * `acquired: false` — a live foreign process already owns the lock; caller
+ * must not start. `existingPid` is the live owner. `existingPid === -1` means
+ * the lock file existed but was unreadable and could not be reclaimed.
+ */
+export type AcquirePidLockResult = { acquired: true } | { acquired: false; existingPid: number };
+
+/**
+ * Atomically acquire a PID-file lock.
+ *
+ * Uses the write-temp-then-link pattern so the lock file appears at its final
+ * path with PID contents already present (no empty-file window): a competing
+ * reader can never observe an in-flight write. Behavior:
+ *
+ * - Lock file does not exist → atomic create via link(). Caller owns the lock.
+ * - Lock file exists, contains the caller's own PID → idempotent acquire
+ *   (caller already owns it; e.g. background-mode parent wrote child.pid
+ *   before spawn).
+ * - Lock file exists with a live foreign PID → refuse; return existingPid.
+ * - Lock file exists with a dead PID (or unreadable) → reclaim by unlinking
+ *   and retrying once. If the retry races and loses to a live foreign
+ *   watchdog, the call returns acquired=false with that foreign PID.
+ *
+ * Parent directory is created if missing (matches the implicit Bun.write
+ * behavior the legacy writePidFile relied on).
+ */
+export async function acquirePidLock(
+	pidFilePath: string,
+	pid: number,
+	isAlive: (pid: number) => boolean,
+): Promise<AcquirePidLockResult> {
+	await mkdir(dirname(pidFilePath), { recursive: true });
+
+	// Stage the PID content at a unique temp path. After link() succeeds, the
+	// lock path appears with full content already present.
+	const tempPath = `${pidFilePath}.tmp.${pid}.${randomUUID()}`;
+	await writeFile(tempPath, `${pid}\n`);
+
+	try {
+		// Two attempts: first try, then one stale-lock reclaim retry. A second
+		// EEXIST after reclaim means a live foreign process raced in.
+		for (let attempt = 0; attempt < 2; attempt++) {
+			try {
+				await link(tempPath, pidFilePath);
+				return { acquired: true };
+			} catch (err: unknown) {
+				const code = (err as NodeJS.ErrnoException | undefined)?.code;
+				if (code !== "EEXIST") {
+					throw err;
+				}
+				const existing = await readPidFile(pidFilePath);
+				if (existing === null) {
+					// Unreadable/corrupted lock file — treat as stale.
+					await removePidFile(pidFilePath);
+					continue;
+				}
+				if (existing === pid) {
+					// Idempotent: caller already owns it (parent pre-wrote child PID).
+					return { acquired: true };
+				}
+				if (isAlive(existing)) {
+					return { acquired: false, existingPid: existing };
+				}
+				// Stale: reclaim and retry once.
+				await removePidFile(pidFilePath);
+			}
+		}
+
+		// Two stale-then-retry attempts both failed. Another writer raced in
+		// between our reclaim and our retry — they own the lock now.
+		const existing = await readPidFile(pidFilePath);
+		return { acquired: false, existingPid: existing ?? -1 };
+	} finally {
+		// Drop the temp inode link (lock path retains the data via the second link).
+		await unlink(tempPath).catch(() => {});
+	}
+}

package/src/utils/process-scan.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+import { findRunningWatchdogProcesses } from "./process-scan.ts";
+
+describe("findRunningWatchdogProcesses", () => {
+	test("returns an array (does not throw)", async () => {
+		const results = await findRunningWatchdogProcesses();
+		expect(Array.isArray(results)).toBe(true);
+		// We can't assert specifics — depends on what's running on the host —
+		// but each entry should have a numeric pid and string command.
+		for (const proc of results) {
+			expect(typeof proc.pid).toBe("number");
+			expect(proc.pid).toBeGreaterThan(0);
+			expect(typeof proc.command).toBe("string");
+		}
+	});
+
+	test("excludes own process even if command matches", async () => {
+		// The test process itself runs `bun test ...` not `ap watch`, so it
+		// would not match anyway. But we still verify own-pid is filtered out
+		// by checking no result has our PID.
+		const results = await findRunningWatchdogProcesses();
+		const ownPid = process.pid;
+		for (const proc of results) {
+			expect(proc.pid).not.toBe(ownPid);
+		}
+	});
+
+	test("matches `ap watch` and `bun run ap watch` invocations", async () => {
+		// Spawn a sleeper whose command line contains the `ap watch` substring,
+		// then verify the scanner finds it. We use `sh -c` so the argv string
+		// passed to ps contains our marker tokens.
+		const sleeper = Bun.spawn(["sh", "-c", "exec -a 'bun run ap watch' sleep 30"], {
+			stdout: "ignore",
+			stderr: "ignore",
+		});
+		try {
+			// Give ps a moment to see the new process.
+			await Bun.sleep(150);
+			const results = await findRunningWatchdogProcesses();
+			const found = results.find((p) => p.pid === sleeper.pid);
+			// On macOS BSD ps, `exec -a` may or may not change the displayed
+			// argv depending on shell version. We accept either: if the
+			// command is detected, it must look right; if not, we don't fail
+			// the test (env-dependent).
+			if (found) {
+				expect(found.command).toMatch(/\b(ap|agentplate)\b.*\bwatch\b/);
+			}
+		} finally {
+			sleeper.kill("SIGTERM");
+			await sleeper.exited.catch(() => {});
+		}
+	});
+});