@ag-eco/agentplate-cli 0.13.0

package/src/commands/serve/agent-actions.ts

@@ -0,0 +1,192 @@
+/**
+ * Action wrappers for the fleet-control REST endpoints (spawn / stop / merge).
+ *
+ * Thin functions consumed by `src/commands/serve/rest.ts` to drive `ap sling`,
+ * `ap stop`, and `ap merge` from the web UI. Each wraps the existing command
+ * core (`slingCommand` / `stopCommand` / `mergeCommand` / `predictConflicts`)
+ * rather than re-implementing the logic, and exposes DI overrides so tests can
+ * inject fakes without spawning real agents or touching git.
+ *
+ * Mirrors the pattern in ./coordinator-actions.ts: short-lived SQLite handles,
+ * typed errors that the REST layer maps to HTTP status, no long-lived state.
+ */
+
+import { join } from "node:path";
+import { loadConfig } from "../../config.ts";
+import { ValidationError } from "../../errors.ts";
+import { predictConflicts } from "../../merge/predict.ts";
+import type { SessionStore } from "../../sessions/store.ts";
+import { createSessionStore } from "../../sessions/store.ts";
+import type { ConflictPrediction, MergeEntry } from "../../types.ts";
+import { type MergeOptions, mergeCommand } from "../merge.ts";
+import { type SlingOptions, slingCommand } from "../sling.ts";
+import { type StopOptions, stopCommand } from "../stop.ts";
+
+export interface AgentActionDeps {
+	projectRoot: string;
+	/** Inject a SessionStore (closing is the caller's responsibility). */
+	_sessionStore?: SessionStore;
+	_slingCommand?: (taskId: string, opts: SlingOptions) => Promise<void>;
+	_stopCommand?: (agentName: string, opts: StopOptions) => Promise<void>;
+	_mergeCommand?: (opts: MergeOptions) => Promise<void>;
+	_predictConflicts?: typeof predictConflicts;
+	_loadConfig?: typeof loadConfig;
+}
+
+// ─── Sling (spawn) ──────────────────────────────────────────────────────────
+
+export interface SlingInput {
+	taskId: string;
+	capability?: string;
+	name?: string;
+	files?: string;
+	spec?: string;
+	runtime?: string;
+	skipTaskCheck?: boolean;
+}
+
+export interface SlingResult {
+	agentName: string;
+	state: string | null;
+	spawned: boolean;
+}
+
+/**
+ * Spawn a worker agent. Forces headless mode (no tmux) — the web UI is the
+ * operator surface. After spawning, reads the freshly-created session row so
+ * the caller can correlate. The agent name mirrors slingCommand's derivation
+ * (`${capability}-${taskId}` when no explicit name is given).
+ */
+export async function slingAgent(deps: AgentActionDeps, input: SlingInput): Promise<SlingResult> {
+	const taskId = input.taskId?.trim() ?? "";
+	if (taskId.length === 0) {
+		throw new ValidationError("Missing or invalid 'taskId' (string)", { field: "taskId" });
+	}
+	const capability = input.capability ?? "builder";
+	const explicitName = input.name?.trim() ?? "";
+
+	const sling = deps._slingCommand ?? slingCommand;
+	const opts: SlingOptions = {
+		json: true,
+		headless: true,
+		capability,
+		...(explicitName.length > 0 ? { name: explicitName } : {}),
+		...(input.files ? { files: input.files } : {}),
+		...(input.spec ? { spec: input.spec } : {}),
+		...(input.runtime ? { runtime: input.runtime } : {}),
+		...(input.skipTaskCheck ? { skipTaskCheck: true } : {}),
+	};
+	await sling(taskId, opts);
+
+	const expectedName = explicitName.length > 0 ? explicitName : `${capability}-${taskId}`;
+	const store =
+		deps._sessionStore ?? createSessionStore(join(deps.projectRoot, ".agentplate", "sessions.db"));
+	try {
+		const session = store.getByName(expectedName);
+		return {
+			agentName: expectedName,
+			state: session?.state ?? null,
+			spawned: session !== null,
+		};
+	} finally {
+		if (deps._sessionStore === undefined) store.close();
+	}
+}
+
+// ─── Stop ───────────────────────────────────────────────────────────────────
+
+export interface StopAgentResult {
+	stopped: boolean;
+	agentName: string;
+}
+
+/**
+ * Terminate a running agent. Throws AgentError (→ HTTP 500/409) when the agent
+ * is unknown or already completed without `cleanWorktree`.
+ */
+export async function stopAgent(
+	deps: AgentActionDeps,
+	name: string,
+	opts?: { cleanWorktree?: boolean },
+): Promise<StopAgentResult> {
+	const agentName = name?.trim() ?? "";
+	if (agentName.length === 0) {
+		throw new ValidationError("Missing agent name", { field: "name" });
+	}
+	const stop = deps._stopCommand ?? stopCommand;
+	await stop(agentName, { json: true, cleanWorktree: opts?.cleanWorktree ?? false });
+	return { stopped: true, agentName };
+}
+
+// ─── Merge ──────────────────────────────────────────────────────────────────
+
+/**
+ * Resolve the merge target the same way `ap merge` does:
+ * `into` flag > session-start branch (.agentplate/session-branch.txt) >
+ * config canonicalBranch.
+ */
+async function resolveTargetBranch(deps: AgentActionDeps, into?: string): Promise<string> {
+	if (into !== undefined && into.trim().length > 0) return into.trim();
+	const sessionBranchPath = join(deps.projectRoot, ".agentplate", "session-branch.txt");
+	const file = Bun.file(sessionBranchPath);
+	if (await file.exists()) {
+		const content = (await file.text()).trim();
+		if (content.length > 0) return content;
+	}
+	const loadCfg = deps._loadConfig ?? loadConfig;
+	const config = await loadCfg(deps.projectRoot);
+	return config.project.canonicalBranch;
+}
+
+export type MergePreviewResult = ConflictPrediction & { branch: string; target: string };
+
+/**
+ * Predict how `ap merge` would resolve `branch` into the target branch.
+ * Side-effect-free (runs `git merge-tree --write-tree`).
+ */
+export async function mergePreview(
+	deps: AgentActionDeps,
+	input: { branch: string; into?: string },
+): Promise<MergePreviewResult> {
+	const branch = input.branch?.trim() ?? "";
+	if (branch.length === 0) {
+		throw new ValidationError("Missing or invalid 'branch' (string)", { field: "branch" });
+	}
+	const target = await resolveTargetBranch(deps, input.into);
+	const predict = deps._predictConflicts ?? predictConflicts;
+	const entry: MergeEntry = {
+		branchName: branch,
+		taskId: "unknown",
+		agentName: "unknown",
+		filesModified: [],
+		enqueuedAt: "",
+		status: "pending",
+		resolvedTier: null,
+	};
+	const prediction = await predict(entry, target, deps.projectRoot);
+	return { ...prediction, branch, target };
+}
+
+/**
+ * Trigger an actual merge. Returns an acknowledgement — detailed per-branch
+ * results surface through events/mail and the UI refreshes. Throws (→ HTTP
+ * error) when the merge fails outright.
+ */
+export async function mergeRun(
+	deps: AgentActionDeps,
+	input: { branch?: string; all?: boolean; into?: string },
+): Promise<{ triggered: true }> {
+	const branch = input.branch?.trim();
+	if (input.all !== true && (branch === undefined || branch.length === 0)) {
+		throw new ValidationError("Provide 'branch' or set 'all: true'", { field: "branch" });
+	}
+	const merge = deps._mergeCommand ?? mergeCommand;
+	const opts: MergeOptions = {
+		json: true,
+		...(input.all === true ? { all: true } : {}),
+		...(branch ? { branch } : {}),
+		...(input.into ? { into: input.into } : {}),
+	};
+	await merge(opts);
+	return { triggered: true };
+}

package/src/commands/serve/build.test.ts

@@ -0,0 +1,202 @@
+/**
+ * Tests for ensureUiBuild auto-build helper.
+ *
+ * Real filesystem (temp dirs + utimesSync) drives the freshness comparison;
+ * the runner is always stubbed so we never invoke a real bun install/build.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ensureUiBuild, type RunnerResult } from "./build.ts";
+
+interface RunnerCall {
+	cmd: string[];
+	cwd: string;
+}
+
+function makeRunner(results: RunnerResult[]): {
+	runner: (cmd: string[], cwd: string) => Promise<RunnerResult>;
+	calls: RunnerCall[];
+} {
+	const calls: RunnerCall[] = [];
+	let i = 0;
+	return {
+		calls,
+		runner: async (cmd, cwd) => {
+			calls.push({ cmd, cwd });
+			const r = results[i] ?? { exitCode: 0, stderr: "" };
+			i += 1;
+			return r;
+		},
+	};
+}
+
+function setupUiDir(root: string): { uiDir: string } {
+	const uiDir = join(root, "ui");
+	mkdirSync(join(uiDir, "src"), { recursive: true });
+	writeFileSync(join(uiDir, "src", "main.ts"), 'console.log("hi")');
+	writeFileSync(join(uiDir, "index.html"), "<html></html>");
+	writeFileSync(join(uiDir, "package.json"), '{"name":"ui"}');
+	return { uiDir };
+}
+
+describe("ensureUiBuild", () => {
+	let tempDir: string;
+
+	beforeEach(() => {
+		tempDir = mkdtempSync(join(tmpdir(), "agentplate-ui-build-"));
+	});
+
+	afterEach(() => {
+		rmSync(tempDir, { recursive: true, force: true });
+	});
+
+	test("triggers build when dist/index.html is missing", async () => {
+		const { uiDir } = setupUiDir(tempDir);
+		// Pretend node_modules already exists so we skip install.
+		mkdirSync(join(uiDir, "node_modules"));
+
+		const { runner, calls } = makeRunner([{ exitCode: 0, stderr: "" }]);
+		await ensureUiBuild({ uiDir, _runner: runner, log: () => {} });
+
+		expect(calls.length).toBe(1);
+		expect(calls[0]?.cmd).toEqual(["bun", "run", "build"]);
+		expect(calls[0]?.cwd).toBe(uiDir);
+	});
+
+	test("triggers build when source mtime is newer than dist mtime", async () => {
+		const { uiDir } = setupUiDir(tempDir);
+		mkdirSync(join(uiDir, "node_modules"));
+		mkdirSync(join(uiDir, "dist"));
+		writeFileSync(join(uiDir, "dist", "index.html"), "<html>old</html>");
+
+		// Make dist older, src newer (definite mtime separation).
+		const past = new Date(Date.now() - 60_000);
+		const future = new Date(Date.now() + 60_000);
+		utimesSync(join(uiDir, "dist", "index.html"), past, past);
+		utimesSync(join(uiDir, "src", "main.ts"), future, future);
+
+		const { runner, calls } = makeRunner([{ exitCode: 0, stderr: "" }]);
+		await ensureUiBuild({ uiDir, _runner: runner, log: () => {} });
+
+		expect(calls.length).toBe(1);
+		expect(calls[0]?.cmd).toEqual(["bun", "run", "build"]);
+	});
+
+	test("skips build when dist is newer than every source file", async () => {
+		const { uiDir } = setupUiDir(tempDir);
+		mkdirSync(join(uiDir, "node_modules"));
+		mkdirSync(join(uiDir, "dist"));
+		writeFileSync(join(uiDir, "dist", "index.html"), "<html>fresh</html>");
+
+		// All sources older than dist.
+		const past = new Date(Date.now() - 60_000);
+		utimesSync(join(uiDir, "src", "main.ts"), past, past);
+		utimesSync(join(uiDir, "index.html"), past, past);
+		utimesSync(join(uiDir, "package.json"), past, past);
+		// Dist is "now" — already the newest.
+
+		const { runner, calls } = makeRunner([]);
+		await ensureUiBuild({ uiDir, _runner: runner, log: () => {} });
+
+		expect(calls.length).toBe(0);
+	});
+
+	test("runs install only when node_modules is missing", async () => {
+		const { uiDir } = setupUiDir(tempDir);
+		// node_modules deliberately missing.
+
+		const { runner, calls } = makeRunner([
+			{ exitCode: 0, stderr: "" }, // install
+			{ exitCode: 0, stderr: "" }, // build
+		]);
+		await ensureUiBuild({ uiDir, _runner: runner, log: () => {} });
+
+		expect(calls.length).toBe(2);
+		expect(calls[0]?.cmd).toEqual(["bun", "install"]);
+		expect(calls[0]?.cwd).toBe(uiDir);
+		expect(calls[1]?.cmd).toEqual(["bun", "run", "build"]);
+	});
+
+	test("does NOT run install when node_modules exists", async () => {
+		const { uiDir } = setupUiDir(tempDir);
+		mkdirSync(join(uiDir, "node_modules"));
+
+		const { runner, calls } = makeRunner([{ exitCode: 0, stderr: "" }]);
+		await ensureUiBuild({ uiDir, _runner: runner, log: () => {} });
+
+		expect(calls.length).toBe(1);
+		expect(calls[0]?.cmd).toEqual(["bun", "run", "build"]);
+	});
+
+	test("throws on non-zero install exit; error includes stderr", async () => {
+		const { uiDir } = setupUiDir(tempDir);
+
+		const { runner } = makeRunner([{ exitCode: 1, stderr: "lockfile out of date" }]);
+
+		await expect(ensureUiBuild({ uiDir, _runner: runner, log: () => {} })).rejects.toThrow(
+			/lockfile out of date/,
+		);
+	});
+
+	test("throws on non-zero build exit; error includes stderr", async () => {
+		const { uiDir } = setupUiDir(tempDir);
+		mkdirSync(join(uiDir, "node_modules"));
+
+		const { runner } = makeRunner([{ exitCode: 2, stderr: "type error in main.ts" }]);
+
+		await expect(ensureUiBuild({ uiDir, _runner: runner, log: () => {} })).rejects.toThrow(
+			/type error in main\.ts/,
+		);
+	});
+
+	test("logs progress messages on build path", async () => {
+		const { uiDir } = setupUiDir(tempDir);
+		// node_modules missing → install + build → 3 log lines (install, build, built).
+		const messages: string[] = [];
+		const { runner } = makeRunner([
+			{ exitCode: 0, stderr: "" },
+			{ exitCode: 0, stderr: "" },
+		]);
+		await ensureUiBuild({ uiDir, _runner: runner, log: (m) => messages.push(m) });
+
+		expect(messages).toEqual(["Installing UI dependencies…", "Building UI…", "UI built"]);
+	});
+
+	test("no-ops when ui/src is absent (production-install case)", async () => {
+		// No setupUiDir() — tempDir has no ui/ at all, mirroring a fresh `ap init`
+		// in a project that doesn't carry a UI workspace (agentplate-916d).
+		const uiDir = join(tempDir, "ui");
+
+		const messages: string[] = [];
+		const { runner, calls } = makeRunner([]);
+		await ensureUiBuild({ uiDir, _runner: runner, log: (m) => messages.push(m) });
+
+		// Neither install nor build runs, and no progress messages are emitted.
+		expect(calls.length).toBe(0);
+		expect(messages.length).toBe(0);
+	});
+
+	test("walks ui/src/ recursively and triggers on nested-file mtime", async () => {
+		const { uiDir } = setupUiDir(tempDir);
+		mkdirSync(join(uiDir, "node_modules"));
+		mkdirSync(join(uiDir, "src", "components"), { recursive: true });
+		writeFileSync(join(uiDir, "src", "components", "App.tsx"), "export default null;");
+		mkdirSync(join(uiDir, "dist"));
+		writeFileSync(join(uiDir, "dist", "index.html"), "<html>old</html>");
+
+		// dist older than the nested file.
+		const past = new Date(Date.now() - 60_000);
+		const future = new Date(Date.now() + 60_000);
+		utimesSync(join(uiDir, "dist", "index.html"), past, past);
+		utimesSync(join(uiDir, "src", "main.ts"), past, past);
+		utimesSync(join(uiDir, "src", "components", "App.tsx"), future, future);
+
+		const { runner, calls } = makeRunner([{ exitCode: 0, stderr: "" }]);
+		await ensureUiBuild({ uiDir, _runner: runner, log: () => {} });
+
+		expect(calls.length).toBe(1);
+	});
+});

package/src/commands/serve/build.ts

@@ -0,0 +1,206 @@
+/**
+ * Auto-build helper for `ap serve` (production mode).
+ *
+ * Detects whether ui/dist/index.html is missing or older than any tracked
+ * source/config file in the ui/ workspace, runs `bun install` (only if
+ * node_modules is missing) followed by `bun run build` when so. Silent when
+ * the existing build is up to date.
+ *
+ * No-ops when the project has no `ui/src` directory — the production-install
+ * case where the user's project doesn't carry a UI workspace and is meant to
+ * serve the prebuilt assets shipped inside the @ag-eco/agentplate-cli package
+ * (see agentplate-916d).
+ *
+ * The runner and filesystem helpers are injectable so tests can drive the
+ * decision logic without invoking real subprocess builds.
+ */
+
+import {
+	existsSync as defaultExistsSync,
+	readdirSync as defaultReaddirSync,
+	statSync as defaultStatSync,
+} from "node:fs";
+import { join, sep } from "node:path";
+
+export interface RunnerResult {
+	exitCode: number;
+	stderr: string;
+}
+
+export interface EnsureUiBuildOptions {
+	uiDir: string;
+	log?: (msg: string) => void;
+	_statSync?: typeof defaultStatSync;
+	_existsSync?: typeof defaultExistsSync;
+	_readdirSync?: typeof defaultReaddirSync;
+	_runner?: (cmd: string[], cwd: string) => Promise<RunnerResult>;
+}
+
+/** Files at the workspace root that affect the build output. */
+const ROOT_TRACKED_FILES = [
+	"index.html",
+	"build.ts",
+	"package.json",
+	"tsconfig.app.json",
+	"tsconfig.json",
+	"components.json",
+];
+
+/**
+ * Recursively walk a directory, calling visit() on each regular file path.
+ * Skips entries that throw on stat (broken symlinks, races during npm
+ * install). Uses the injected readdir/stat for testability.
+ */
+function walkDir(
+	dir: string,
+	visit: (path: string) => void,
+	exists: typeof defaultExistsSync,
+	readdir: typeof defaultReaddirSync,
+	stat: typeof defaultStatSync,
+): void {
+	if (!exists(dir)) return;
+	let entries: string[];
+	try {
+		entries = readdir(dir);
+	} catch {
+		return;
+	}
+	for (const name of entries) {
+		const full = dir + sep + name;
+		let st: ReturnType<typeof defaultStatSync>;
+		try {
+			st = stat(full);
+		} catch {
+			continue;
+		}
+		if (st.isDirectory()) {
+			walkDir(full, visit, exists, readdir, stat);
+		} else if (st.isFile()) {
+			visit(full);
+		}
+	}
+}
+
+async function defaultRunner(cmd: string[], cwd: string): Promise<RunnerResult> {
+	if (cmd.length === 0) {
+		throw new Error("ensureUiBuild runner: empty command");
+	}
+	const proc = Bun.spawn(cmd as string[], {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+
+	const stderrChunks: string[] = [];
+	const pipe = async (
+		stream: ReadableStream<Uint8Array> | null,
+		sink: (line: string) => void,
+		capture?: string[],
+	): Promise<void> => {
+		if (stream === null) return;
+		const decoder = new TextDecoder();
+		let buf = "";
+		const reader = stream.getReader();
+		try {
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				const chunk = decoder.decode(value, { stream: true });
+				if (capture) capture.push(chunk);
+				buf += chunk;
+				let idx = buf.indexOf("\n");
+				while (idx !== -1) {
+					sink(buf.slice(0, idx));
+					buf = buf.slice(idx + 1);
+					idx = buf.indexOf("\n");
+				}
+			}
+			if (buf.length > 0) sink(buf);
+		} finally {
+			reader.releaseLock();
+		}
+	};
+
+	const writeOut = (line: string): void => {
+		process.stderr.write(`[ui-build] ${line}\n`);
+	};
+
+	await Promise.all([pipe(proc.stdout, writeOut), pipe(proc.stderr, writeOut, stderrChunks)]);
+
+	const exitCode = await proc.exited;
+	return { exitCode, stderr: stderrChunks.join("") };
+}
+
+/**
+ * Ensure that ui/dist/ has a build that is newer than every tracked source
+ * file. No-op when the build is current. Throws when a required subprocess
+ * (install / build) fails; the thrown Error includes the captured stderr.
+ */
+export async function ensureUiBuild(opts: EnsureUiBuildOptions): Promise<void> {
+	const exists = opts._existsSync ?? defaultExistsSync;
+	const stat = opts._statSync ?? defaultStatSync;
+	const readdir = opts._readdirSync ?? defaultReaddirSync;
+	const runner = opts._runner ?? defaultRunner;
+	const log =
+		opts.log ??
+		((msg: string): void => {
+			process.stderr.write(`[ui-build] ${msg}\n`);
+		});
+
+	// Production-install case: when the project has no ui/src, there are no
+	// sources to build from. ap serve falls back to the prebuilt assets shipped
+	// inside the npm package — see resolveUiDistPath() in serve.ts.
+	if (!exists(join(opts.uiDir, "src"))) return;
+
+	const distIndex = join(opts.uiDir, "dist", "index.html");
+	let needBuild = false;
+	if (!exists(distIndex)) {
+		needBuild = true;
+	} else {
+		let distMtime = 0;
+		try {
+			distMtime = stat(distIndex).mtimeMs;
+		} catch {
+			needBuild = true;
+		}
+
+		if (!needBuild) {
+			let newest = 0;
+			const visit = (path: string): void => {
+				try {
+					const m = stat(path).mtimeMs;
+					if (m > newest) newest = m;
+				} catch {
+					// File vanished between readdir and stat — ignore.
+				}
+			};
+
+			walkDir(join(opts.uiDir, "src"), visit, exists, readdir, stat);
+			for (const name of ROOT_TRACKED_FILES) {
+				const full = join(opts.uiDir, name);
+				if (exists(full)) visit(full);
+			}
+
+			if (newest > distMtime) needBuild = true;
+		}
+	}
+
+	if (!needBuild) return;
+
+	if (!exists(join(opts.uiDir, "node_modules"))) {
+		log("Installing UI dependencies…");
+		const install = await runner(["bun", "install"], opts.uiDir);
+		if (install.exitCode !== 0) {
+			throw new Error(
+				`UI dependency install failed (exit ${install.exitCode}): ${install.stderr.trim()}`,
+			);
+		}
+	}
+
+	log("Building UI…");
+	const build = await runner(["bun", "run", "build"], opts.uiDir);
+	if (build.exitCode !== 0) {
+		throw new Error(`UI build failed (exit ${build.exitCode}): ${build.stderr.trim()}`);
+	}
+	log("UI built");
+}