@ag-eco/agentplate-cli 0.13.0

package/src/sessions/compat.test.ts

@@ -0,0 +1,281 @@
+/**
+ * Tests for the session compat shim (JSON -> SQLite migration).
+ *
+ * Uses real filesystem and bun:sqlite. No mocks.
+ * Tests file-based migration behavior, so temp files are required (not :memory:).
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { cleanupTempDir } from "../test-helpers.ts";
+import { openSessionStore } from "./compat.ts";
+
+let tempDir: string;
+let agentplateDir: string;
+
+beforeEach(async () => {
+	tempDir = await mkdtemp(join(tmpdir(), "agentplate-compat-test-"));
+	agentplateDir = join(tempDir, ".agentplate");
+	const { mkdir } = await import("node:fs/promises");
+	await mkdir(agentplateDir, { recursive: true });
+});
+
+afterEach(async () => {
+	await cleanupTempDir(tempDir);
+});
+
+/** Create a sessions.json with the given entries. */
+async function writeSessionsJson(sessions: Record<string, unknown>[]): Promise<void> {
+	const jsonPath = join(agentplateDir, "sessions.json");
+	await writeFile(jsonPath, `${JSON.stringify(sessions, null, "\t")}\n`, "utf-8");
+}
+
+/** A valid session object as it would appear in sessions.json. */
+function makeJsonSession(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+	return {
+		id: "session-001-test-agent",
+		agentName: "test-agent",
+		capability: "builder",
+		worktreePath: "/tmp/worktrees/test-agent",
+		branchName: "agentplate/test-agent/task-1",
+		taskId: "task-1",
+		tmuxSession: "agentplate-test-agent",
+		state: "working",
+		pid: 12345,
+		parentAgent: null,
+		depth: 0,
+		startedAt: "2026-01-15T10:00:00.000Z",
+		lastActivity: "2026-01-15T10:05:00.000Z",
+		escalationLevel: 0,
+		stalledSince: null,
+		...overrides,
+	};
+}
+
+// === Migration from sessions.json ===
+
+describe("openSessionStore", () => {
+	test("creates empty DB when neither sessions.json nor sessions.db exist", () => {
+		const { store, migrated } = openSessionStore(agentplateDir);
+
+		expect(migrated).toBe(false);
+		expect(store.getAll()).toEqual([]);
+		store.close();
+	});
+
+	test("imports sessions from sessions.json when sessions.db does not exist", async () => {
+		await writeSessionsJson([
+			makeJsonSession({ agentName: "agent-a", id: "s-a" }),
+			makeJsonSession({ agentName: "agent-b", id: "s-b", state: "completed" }),
+		]);
+
+		const { store, migrated } = openSessionStore(agentplateDir);
+
+		expect(migrated).toBe(true);
+		const all = store.getAll();
+		expect(all).toHaveLength(2);
+
+		const agentA = store.getByName("agent-a");
+		expect(agentA).not.toBeNull();
+		expect(agentA?.id).toBe("s-a");
+		expect(agentA?.state).toBe("working");
+
+		const agentB = store.getByName("agent-b");
+		expect(agentB).not.toBeNull();
+		expect(agentB?.state).toBe("completed");
+
+		store.close();
+	});
+
+	test("migration adds runId=null when sessions.json entries lack runId", async () => {
+		// Write a session WITHOUT runId (old format)
+		const oldFormatSession = makeJsonSession();
+		(oldFormatSession as Record<string, unknown>).runId = undefined;
+
+		await writeSessionsJson([oldFormatSession]);
+
+		const { store, migrated } = openSessionStore(agentplateDir);
+
+		expect(migrated).toBe(true);
+		const session = store.getByName("test-agent");
+		expect(session).not.toBeNull();
+		expect(session?.runId).toBeNull();
+
+		store.close();
+	});
+
+	test("does not re-migrate when sessions.db already exists", async () => {
+		// First call: create the DB with migration
+		await writeSessionsJson([makeJsonSession({ agentName: "original", id: "s-1" })]);
+
+		const { store: store1, migrated: migrated1 } = openSessionStore(agentplateDir);
+		expect(migrated1).toBe(true);
+		store1.close();
+
+		// Modify sessions.json to add a new entry
+		await writeSessionsJson([
+			makeJsonSession({ agentName: "original", id: "s-1" }),
+			makeJsonSession({ agentName: "new-agent", id: "s-2" }),
+		]);
+
+		// Second call: DB exists, so no migration
+		const { store: store2, migrated: migrated2 } = openSessionStore(agentplateDir);
+		expect(migrated2).toBe(false);
+
+		// Should still have only the original session from the first migration
+		const all = store2.getAll();
+		expect(all).toHaveLength(1);
+		expect(all[0]?.agentName).toBe("original");
+
+		store2.close();
+	});
+
+	test("imports from sessions.json when sessions.db exists but is empty", async () => {
+		// Simulate the scenario where sessions.db was created (e.g., by init) but
+		// no sessions were ever written to it, while sessions.json has records from
+		// a previous coordinator start that used the old code path (agentplate-036f).
+		const { store: emptyStore } = openSessionStore(agentplateDir);
+		expect(emptyStore.getAll()).toHaveLength(0);
+		emptyStore.close();
+
+		// Now write records to sessions.json (simulating old code path)
+		await writeSessionsJson([
+			makeJsonSession({ agentName: "orphaned-coordinator", id: "s-orphan", state: "booting" }),
+		]);
+
+		// Re-open: DB exists but is empty, so JSON records should be imported
+		const { store: store2, migrated } = openSessionStore(agentplateDir);
+		expect(migrated).toBe(true);
+
+		const all = store2.getAll();
+		expect(all).toHaveLength(1);
+		expect(all[0]?.agentName).toBe("orphaned-coordinator");
+		expect(all[0]?.state).toBe("booting");
+		store2.close();
+	});
+
+	test("handles empty sessions.json (no migration needed)", async () => {
+		await writeSessionsJson([]);
+
+		const { store, migrated } = openSessionStore(agentplateDir);
+
+		expect(migrated).toBe(false);
+		expect(store.getAll()).toEqual([]);
+		store.close();
+	});
+
+	test("handles malformed sessions.json gracefully", async () => {
+		const jsonPath = join(agentplateDir, "sessions.json");
+		await writeFile(jsonPath, "this is not json", "utf-8");
+
+		const { store, migrated } = openSessionStore(agentplateDir);
+
+		expect(migrated).toBe(false);
+		expect(store.getAll()).toEqual([]);
+		store.close();
+	});
+
+	test("handles sessions.json with non-array content gracefully", async () => {
+		const jsonPath = join(agentplateDir, "sessions.json");
+		await writeFile(jsonPath, '{"not": "an array"}', "utf-8");
+
+		const { store, migrated } = openSessionStore(agentplateDir);
+
+		expect(migrated).toBe(false);
+		expect(store.getAll()).toEqual([]);
+		store.close();
+	});
+});
+
+// === Data integrity after migration ===
+
+describe("data integrity", () => {
+	test("all fields from sessions.json are preserved in SQLite", async () => {
+		const fullSession = makeJsonSession({
+			id: "session-full",
+			agentName: "full-agent",
+			capability: "scout",
+			worktreePath: "/tmp/worktrees/full-agent",
+			branchName: "agentplate/full-agent/task-42",
+			taskId: "task-42",
+			tmuxSession: "agentplate-full-agent",
+			state: "stalled",
+			pid: 99999,
+			parentAgent: "lead-agent",
+			depth: 2,
+			startedAt: "2026-02-01T08:00:00.000Z",
+			lastActivity: "2026-02-01T09:00:00.000Z",
+			escalationLevel: 3,
+			stalledSince: "2026-02-01T08:50:00.000Z",
+		});
+
+		await writeSessionsJson([fullSession]);
+
+		const { store } = openSessionStore(agentplateDir);
+		const result = store.getByName("full-agent");
+
+		expect(result).not.toBeNull();
+		expect(result?.id).toBe("session-full");
+		expect(result?.agentName).toBe("full-agent");
+		expect(result?.capability).toBe("scout");
+		expect(result?.worktreePath).toBe("/tmp/worktrees/full-agent");
+		expect(result?.branchName).toBe("agentplate/full-agent/task-42");
+		expect(result?.taskId).toBe("task-42");
+		expect(result?.tmuxSession).toBe("agentplate-full-agent");
+		expect(result?.state).toBe("stalled");
+		expect(result?.pid).toBe(99999);
+		expect(result?.parentAgent).toBe("lead-agent");
+		expect(result?.depth).toBe(2);
+		expect(result?.runId).toBeNull(); // Not in old JSON format
+		expect(result?.startedAt).toBe("2026-02-01T08:00:00.000Z");
+		expect(result?.lastActivity).toBe("2026-02-01T09:00:00.000Z");
+		expect(result?.escalationLevel).toBe(3);
+		expect(result?.stalledSince).toBe("2026-02-01T08:50:00.000Z");
+
+		store.close();
+	});
+
+	test("migrated store supports all SessionStore operations", async () => {
+		await writeSessionsJson([
+			makeJsonSession({ agentName: "agent-a", id: "s-a", state: "working" }),
+			makeJsonSession({ agentName: "agent-b", id: "s-b", state: "completed" }),
+		]);
+
+		const { store } = openSessionStore(agentplateDir);
+
+		// getActive should return only "working" sessions
+		const active = store.getActive();
+		expect(active).toHaveLength(1);
+		expect(active[0]?.agentName).toBe("agent-a");
+
+		// updateState should work on migrated data
+		store.updateState("agent-a", "completed");
+		expect(store.getByName("agent-a")?.state).toBe("completed");
+
+		// remove should work on migrated data
+		store.remove("agent-b");
+		expect(store.getByName("agent-b")).toBeNull();
+
+		store.close();
+	});
+
+	test("multiple sessions with same agent name in JSON: last one wins", async () => {
+		// This edge case shouldn't happen in practice, but test defensive behavior
+		await writeSessionsJson([
+			makeJsonSession({ agentName: "dupe", id: "s-1", state: "booting" }),
+			makeJsonSession({ agentName: "dupe", id: "s-2", state: "working" }),
+		]);
+
+		const { store } = openSessionStore(agentplateDir);
+
+		const all = store.getAll();
+		expect(all).toHaveLength(1);
+		// Last upsert wins (s-2)
+		expect(all[0]?.id).toBe("s-2");
+		expect(all[0]?.state).toBe("working");
+
+		store.close();
+	});
+});

package/src/sessions/compat.ts

@@ -0,0 +1,105 @@
+/**
+ * Backward-compatible session reader.
+ *
+ * On first call, if sessions.json exists and sessions.db does not,
+ * imports all entries from JSON into SQLite. After migration,
+ * SQLite is the authoritative source.
+ *
+ * This module does NOT modify consumers -- it provides a migration
+ * bridge that can be called by consumers when they are ready to switch.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { AgentSession } from "../types.ts";
+import { createSessionStore, type SessionStore } from "./store.ts";
+
+/**
+ * Normalize a session object that may have been parsed from JSON
+ * and is missing the `runId` field (added after sessions.json was designed).
+ */
+function normalizeSession(raw: Record<string, unknown>): AgentSession {
+	return {
+		id: raw.id as string,
+		agentName: raw.agentName as string,
+		capability: raw.capability as string,
+		worktreePath: raw.worktreePath as string,
+		branchName: raw.branchName as string,
+		taskId: raw.taskId as string,
+		tmuxSession: raw.tmuxSession as string,
+		state: raw.state as AgentSession["state"],
+		pid: (raw.pid as number | null) ?? null,
+		parentAgent: (raw.parentAgent as string | null) ?? null,
+		depth: (raw.depth as number) ?? 0,
+		runId: (raw.runId as string | null) ?? null,
+		startedAt: raw.startedAt as string,
+		lastActivity: raw.lastActivity as string,
+		escalationLevel: (raw.escalationLevel as number) ?? 0,
+		stalledSince: (raw.stalledSince as string | null) ?? null,
+		transcriptPath: (raw.transcriptPath as string | null) ?? null,
+	};
+}
+
+/**
+ * Load sessions from a sessions.json file.
+ * Returns an empty array if the file does not exist or is malformed.
+ */
+function loadJsonSessions(jsonPath: string): AgentSession[] {
+	if (!existsSync(jsonPath)) {
+		return [];
+	}
+	try {
+		const text = readFileSync(jsonPath, "utf-8");
+		const parsed: unknown = JSON.parse(text);
+		if (!Array.isArray(parsed)) {
+			return [];
+		}
+		return parsed.map((entry) => normalizeSession(entry as Record<string, unknown>));
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Open or create a SessionStore at the given .agentplate directory root.
+ *
+ * Migration logic:
+ * 1. If sessions.db exists AND has rows, open it directly (SQLite is authoritative).
+ * 2. If sessions.db exists but is empty, check sessions.json for importable records.
+ * 3. If sessions.db does NOT exist but sessions.json does, create sessions.db
+ *    and import all entries from sessions.json.
+ * 4. If neither exists, create an empty sessions.db.
+ *
+ * @param agentplateDir - Path to the .agentplate directory (e.g., /project/.agentplate)
+ * @returns An object with the SessionStore and whether a migration occurred.
+ */
+export function openSessionStore(agentplateDir: string): {
+	store: SessionStore;
+	migrated: boolean;
+} {
+	const dbPath = join(agentplateDir, "sessions.db");
+	const jsonPath = join(agentplateDir, "sessions.json");
+
+	const dbExists = existsSync(dbPath);
+
+	const store = createSessionStore(dbPath);
+
+	// If the DB already existed AND has data, it is authoritative -- no migration needed.
+	// If the DB file exists but is empty (e.g., created by init before any sessions were
+	// recorded), fall through to check sessions.json for importable records (agentplate-036f).
+	if (dbExists && store.count() > 0) {
+		return { store, migrated: false };
+	}
+
+	// DB was just created. If sessions.json exists, import its entries.
+	const jsonSessions = loadJsonSessions(jsonPath);
+	if (jsonSessions.length === 0) {
+		return { store, migrated: false };
+	}
+
+	for (const session of jsonSessions) {
+		store.upsert(session);
+	}
+
+	return { store, migrated: true };
+}