opencode-swarm-plugin 0.50.0 → 0.51.0

package/bin/commands/session.ts

@@ -0,0 +1,377 @@
+/**
+ * Session Command - Chainlink-inspired session management
+ *
+ * Commands:
+ *   swarm session start [--cell <id>] [--json]
+ *   swarm session end [--notes "..."] [--json]
+ *   swarm session status [--json]
+ *   swarm session history [--limit <n>] [--json]
+ *
+ * Inspired by: https://github.com/dollspace-gay/chainlink
+ * Credit: @dollspace-gay for the session handoff pattern
+ */
+
+import * as p from "@clack/prompts";
+import {
+	getSwarmMailLibSQL,
+	createHiveAdapter,
+} from "swarm-mail";
+
+// Color utilities (inline, same as swarm.ts)
+const cyan = (s: string) => `\x1b[36m${s}\x1b[0m`;
+const green = (s: string) => `\x1b[32m${s}\x1b[0m`;
+const yellow = (s: string) => `\x1b[33m${s}\x1b[0m`;
+const dim = (s: string) => `\x1b[2m${s}\x1b[0m`;
+
+/**
+ * Main session command handler
+ */
+export async function session() {
+	const args = process.argv.slice(3);
+	const subcommand = args[0];
+
+	if (!subcommand || subcommand === "help" || subcommand === "--help") {
+		showHelp();
+		return;
+	}
+
+	switch (subcommand) {
+		case "start":
+			await startSession(args.slice(1));
+			break;
+		case "end":
+			await endSession(args.slice(1));
+			break;
+		case "status":
+			await sessionStatus(args.slice(1));
+			break;
+		case "history":
+			await sessionHistory(args.slice(1));
+			break;
+		default:
+			p.log.error(`Unknown session subcommand: ${subcommand}`);
+			showHelp();
+			process.exit(1);
+	}
+}
+
+/**
+ * Start a new session
+ */
+async function startSession(args: string[]) {
+	// Parse arguments
+	let cellId: string | null = null;
+	let jsonOutput = false;
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+
+		if (arg === "--cell" && i + 1 < args.length) {
+			cellId = args[++i];
+		} else if (arg === "--json") {
+			jsonOutput = true;
+		}
+	}
+
+	const projectPath = process.cwd();
+
+	try {
+		const swarmMail = await getSwarmMailLibSQL(projectPath);
+		const db = await swarmMail.getDatabase();
+		const adapter = createHiveAdapter(db, projectPath);
+
+		// Run migrations to ensure schema exists
+		await adapter.runMigrations();
+
+		// Start session
+		const session = await adapter.startSession(projectPath, {
+			active_cell_id: cellId || undefined,
+		});
+
+		if (jsonOutput) {
+			console.log(JSON.stringify(session, null, 2));
+			return;
+		}
+
+		// Pretty output
+		p.log.success(green(`Session started: ${session.id}`));
+
+		if (session.active_cell_id) {
+			p.log.message(dim(`  Active cell: ${session.active_cell_id}`));
+		}
+
+		if (session.previous_handoff_notes) {
+			p.log.message(
+				`\n${yellow("Previous session notes:")}
+${dim(session.previous_handoff_notes)}`,
+			);
+		} else {
+			p.log.message(dim("\n  (No previous session notes)"));
+		}
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		p.log.error(`Failed to start session: ${message}`);
+		process.exit(1);
+	}
+}
+
+/**
+ * End the current session
+ */
+async function endSession(args: string[]) {
+	// Parse arguments
+	let notes: string | null = null;
+	let jsonOutput = false;
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+
+		if (arg === "--notes" && i + 1 < args.length) {
+			notes = args[++i];
+		} else if (arg === "--json") {
+			jsonOutput = true;
+		}
+	}
+
+	const projectPath = process.cwd();
+
+	try {
+		const swarmMail = await getSwarmMailLibSQL(projectPath);
+		const db = await swarmMail.getDatabase();
+		const adapter = createHiveAdapter(db, projectPath);
+
+		// Run migrations
+		await adapter.runMigrations();
+
+		// Get current session
+		const currentSession = await adapter.getCurrentSession(projectPath);
+
+		if (!currentSession) {
+			p.log.error("No active session to end");
+			process.exit(1);
+		}
+
+		// End session
+		const endedSession = await adapter.endSession(
+			projectPath,
+			currentSession.id,
+			{
+				handoff_notes: notes || undefined,
+			},
+		);
+
+		if (jsonOutput) {
+			console.log(JSON.stringify(endedSession, null, 2));
+			return;
+		}
+
+		// Pretty output
+		p.log.success(green(`Session ended: ${endedSession.id}`));
+
+		if (endedSession.handoff_notes) {
+			p.log.message(
+				dim(`  Handoff notes saved for next session:
+${endedSession.handoff_notes}`),
+			);
+		}
+
+		const duration = endedSession.ended_at! - endedSession.started_at;
+		const durationStr = formatDuration(duration);
+		p.log.message(dim(`  Duration: ${durationStr}`));
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		p.log.error(`Failed to end session: ${message}`);
+		process.exit(1);
+	}
+}
+
+/**
+ * Show current session status
+ */
+async function sessionStatus(args: string[]) {
+	const jsonOutput = args.includes("--json");
+	const projectPath = process.cwd();
+
+	try {
+		const swarmMail = await getSwarmMailLibSQL(projectPath);
+		const db = await swarmMail.getDatabase();
+		const adapter = createHiveAdapter(db, projectPath);
+
+		// Run migrations
+		await adapter.runMigrations();
+
+		// Get current session
+		const currentSession = await adapter.getCurrentSession(projectPath);
+
+		if (!currentSession) {
+			if (jsonOutput) {
+				console.log(JSON.stringify({ active: false }, null, 2));
+			} else {
+				p.log.message("No active session");
+			}
+			return;
+		}
+
+		if (jsonOutput) {
+			console.log(
+				JSON.stringify({ active: true, session: currentSession }, null, 2),
+			);
+			return;
+		}
+
+		// Pretty output
+		p.log.message(green("Active session:"));
+		p.log.message(dim(`  ID: ${currentSession.id}`));
+		p.log.message(
+			dim(`  Started: ${new Date(currentSession.started_at).toLocaleString()}`),
+		);
+
+		if (currentSession.active_cell_id) {
+			p.log.message(dim(`  Active cell: ${currentSession.active_cell_id}`));
+		}
+
+		const elapsed = Date.now() - currentSession.started_at;
+		p.log.message(dim(`  Elapsed: ${formatDuration(elapsed)}`));
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		p.log.error(`Failed to get session status: ${message}`);
+		process.exit(1);
+	}
+}
+
+/**
+ * Show session history
+ */
+async function sessionHistory(args: string[]) {
+	// Parse arguments
+	let limit = 10;
+	let jsonOutput = false;
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+
+		if (arg === "--limit" && i + 1 < args.length) {
+			limit = parseInt(args[++i], 10);
+			if (isNaN(limit) || limit <= 0) {
+				p.log.error(`Invalid limit: ${args[i]}`);
+				process.exit(1);
+			}
+		} else if (arg === "--json") {
+			jsonOutput = true;
+		}
+	}
+
+	const projectPath = process.cwd();
+
+	try {
+		const swarmMail = await getSwarmMailLibSQL(projectPath);
+		const db = await swarmMail.getDatabase();
+		const adapter = createHiveAdapter(db, projectPath);
+
+		// Run migrations
+		await adapter.runMigrations();
+
+		// Get history
+		const sessions = await adapter.getSessionHistory(projectPath, { limit });
+
+		if (jsonOutput) {
+			console.log(JSON.stringify(sessions, null, 2));
+			return;
+		}
+
+		// Pretty output
+		if (sessions.length === 0) {
+			p.log.message("No session history");
+			return;
+		}
+
+		p.log.message(cyan(`Recent sessions (${sessions.length}):\n`));
+
+		for (const session of sessions) {
+			const startedAt = new Date(session.started_at).toLocaleString();
+			const status = session.ended_at ? "ended" : green("active");
+
+			p.log.message(`  ${dim(`#${session.id}`)} - ${status}`);
+			p.log.message(dim(`    Started: ${startedAt}`));
+
+			if (session.ended_at) {
+				const duration = session.ended_at - session.started_at;
+				p.log.message(dim(`    Duration: ${formatDuration(duration)}`));
+			}
+
+			if (session.active_cell_id) {
+				p.log.message(dim(`    Cell: ${session.active_cell_id}`));
+			}
+
+			if (session.handoff_notes) {
+				p.log.message(dim(`    Notes: ${session.handoff_notes.slice(0, 60)}...`));
+			}
+
+			p.log.message(""); // Blank line
+		}
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		p.log.error(`Failed to get session history: ${message}`);
+		process.exit(1);
+	}
+}
+
+/**
+ * Format duration in human-readable format
+ */
+function formatDuration(ms: number): string {
+	const seconds = Math.floor(ms / 1000);
+	const minutes = Math.floor(seconds / 60);
+	const hours = Math.floor(minutes / 60);
+	const days = Math.floor(hours / 24);
+
+	if (days > 0) {
+		return `${days}d ${hours % 24}h`;
+	}
+	if (hours > 0) {
+		return `${hours}h ${minutes % 60}m`;
+	}
+	if (minutes > 0) {
+		return `${minutes}m ${seconds % 60}s`;
+	}
+	return `${seconds}s`;
+}
+
+/**
+ * Show help
+ */
+function showHelp() {
+	console.log(`
+${cyan("swarm session")} - Manage work sessions with handoff notes
+
+${cyan("Commands:")}
+  swarm session start [--cell <id>]  Start a new session
+  swarm session end [--notes "..."]  End current session with optional handoff notes
+  swarm session status               Show current session info
+  swarm session history [--limit n]  Show session history (default: 10)
+
+${cyan("Options:")}
+  --json                             Output as JSON
+  --cell <id>                        Set active cell when starting session
+  --notes "..."                      Save handoff notes for next session
+  --limit <n>                        Limit history results
+
+${cyan("Examples:")}
+  ${dim("# Start session")}
+  swarm session start
+
+  ${dim("# Start session with active cell")}
+  swarm session start --cell opencode-swarm-monorepo-lf2p4u-mk2uv4j7u3o
+
+  ${dim("# End session with handoff notes")}
+  swarm session end --notes "Completed auth flow. Next: add error handling"
+
+  ${dim("# Check current session")}
+  swarm session status
+
+  ${dim("# View recent sessions")}
+  swarm session history --limit 5
+
+${dim("Inspired by Chainlink: https://github.com/dollspace-gay/chainlink")}
+`);
+}

package/bin/commands/tree.test.ts

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview Tests for tree command
+ *
+ * Integration tests for CLI command that renders cell hierarchies.
+ */
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { createInMemorySwarmMailLibSQL, createHiveAdapter } from "swarm-mail";
+import type { SwarmMailAdapter } from "swarm-mail";
+
+describe("tree command integration", () => {
+  let swarmMail: SwarmMailAdapter;
+  const projectPath = "/tmp/test-tree-project";
+
+  beforeAll(async () => {
+    swarmMail = await createInMemorySwarmMailLibSQL("test-tree");
+    const db = await swarmMail.getDatabase();
+    const adapter = createHiveAdapter(db, projectPath);
+    await adapter.runMigrations();
+
+    // Create test data: epic with children
+    const epic = await adapter.createCell(projectPath, {
+      title: "Test Epic",
+      type: "epic",
+      priority: 0,
+    });
+
+    await adapter.createCell(projectPath, {
+      title: "Task 1",
+      type: "task",
+      priority: 1,
+      parent_id: epic.id,
+    });
+
+    await adapter.createCell(projectPath, {
+      title: "Task 2",
+      type: "task",
+      priority: 2,
+      parent_id: epic.id,
+    });
+
+    // Create standalone task
+    await adapter.createCell(projectPath, {
+      title: "Standalone Task",
+      type: "task",
+      priority: 1,
+    });
+  });
+
+  afterAll(async () => {
+    await swarmMail.close();
+  });
+
+  test("queries cells and builds tree structure", async () => {
+    const db = await swarmMail.getDatabase();
+    const adapter = createHiveAdapter(db, projectPath);
+
+    const cells = await adapter.queryCells(projectPath, {
+      limit: 100,
+    });
+
+    expect(cells.length).toBeGreaterThan(0);
+
+    // Verify we have epic and children
+    const epic = cells.find((c) => c.type === "epic");
+    expect(epic).toBeDefined();
+
+    const children = cells.filter((c) => c.parent_id === epic?.id);
+    expect(children.length).toBe(2);
+  });
+});

package/bin/commands/tree.ts

@@ -0,0 +1,131 @@
+/**
+ * @fileoverview Tree command for visualizing cell hierarchies
+ *
+ * Inspired by Chainlink's tree visualization.
+ * Credit: https://github.com/dollspace-gay/chainlink
+ *
+ * Usage:
+ *   swarm tree                 - Show all cells as tree
+ *   swarm tree --status open   - Filter by status
+ *   swarm tree --epic <id>     - Show specific epic subtree
+ *   swarm tree --json          - JSON output
+ */
+
+import * as p from "@clack/prompts";
+import { getSwarmMailLibSQL, createHiveAdapter } from "swarm-mail";
+import type { Cell } from "swarm-mail";
+import {
+  buildTreeStructure,
+  renderTree,
+} from "../../src/utils/tree-renderer.js";
+
+const dim = (s: string) => `\x1b[2m${s}\x1b[0m`;
+const red = (s: string) => `\x1b[31m${s}\x1b[0m`;
+
+export interface TreeOptions {
+  status?: string;
+  epic?: string;
+  json?: boolean;
+}
+
+/**
+ * Parse tree command arguments
+ */
+export function parseTreeArgs(args: string[]): TreeOptions {
+  const options: TreeOptions = {};
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === "--status" && i + 1 < args.length) {
+      options.status = args[++i];
+    } else if (arg === "--epic" && i + 1 < args.length) {
+      options.epic = args[++i];
+    } else if (arg === "--json") {
+      options.json = true;
+    }
+  }
+
+  return options;
+}
+
+/**
+ * Execute tree command
+ */
+export async function tree(args: string[] = []) {
+  const options = parseTreeArgs(args);
+
+  const projectPath = process.cwd();
+
+  try {
+    const swarmMail = await getSwarmMailLibSQL(projectPath);
+    const db = await swarmMail.getDatabase();
+    const adapter = createHiveAdapter(db, projectPath);
+
+    // Run migrations to ensure schema exists
+    await adapter.runMigrations();
+
+    // Query cells with filters
+    let cells: Cell[];
+
+    if (options.epic) {
+      // Get epic and its descendants
+      const epic = await adapter.getCell(projectPath, options.epic);
+      if (!epic) {
+        p.log.error(`Epic not found: ${options.epic}`);
+        process.exit(1);
+      }
+
+      // Get all cells that are children of this epic
+      const allCells = await adapter.queryCells(projectPath, {
+        limit: 1000,
+      });
+
+      // Filter to epic and its descendants
+      cells = [epic];
+      const childIds = new Set([epic.id]);
+
+      // Iteratively find all descendants
+      let foundNew = true;
+      while (foundNew) {
+        foundNew = false;
+        for (const cell of allCells) {
+          if (
+            cell.parent_id &&
+            childIds.has(cell.parent_id) &&
+            !childIds.has(cell.id)
+          ) {
+            cells.push(cell);
+            childIds.add(cell.id);
+            foundNew = true;
+          }
+        }
+      }
+    } else {
+      // Get all cells
+      cells = await adapter.queryCells(projectPath, {
+        status: options.status as any,
+        limit: 1000,
+      });
+    }
+
+    if (cells.length === 0) {
+      p.log.message(dim("No cells found"));
+      return;
+    }
+
+    // Output
+    if (options.json) {
+      const tree = buildTreeStructure(cells);
+      console.log(JSON.stringify(tree, null, 2));
+    } else {
+      const tree = buildTreeStructure(cells);
+      const output = renderTree(tree);
+      console.log(output);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    p.log.error(`Failed to render tree: ${message}`);
+    process.exit(1);
+  }
+}

package/bin/swarm.ts

@@ -82,6 +82,8 @@ import {
   exportToCSV,
   exportToJSON,
 } from "../src/export-tools.js";
+import { tree } from "./commands/tree.js";
+import { session } from "./commands/session.js";
 import {
   querySwarmHistory,
   formatSwarmHistory,
@@ -3283,6 +3285,11 @@ async function exportEvents() {
   }
 }
 
+async function treeCommand() {
+  const args = process.argv.slice(3);
+  await tree(args);
+}
+
 async function help() {
   console.log(yellow(BANNER));
   console.log(dim("  " + TAGLINE + " v" + VERSION));
@@ -3313,6 +3320,8 @@ ${cyan("Commands:")}
   swarm dashboard Live terminal UI with worker status (--epic, --refresh)
   swarm replay    Event replay with timing (--speed, --type, --agent, --since, --until)
   swarm export    Export events (--format otlp/csv/json, --epic, --output)
+  swarm tree      Visualize cell hierarchy as ASCII tree (--status, --epic, --json)
+  swarm session   Manage work sessions with handoff notes (start, end, status, history)
   swarm update    Update to latest version
   swarm version   Show version and banner
   swarm tool      Execute a tool (for plugin wrapper)
@@ -3394,6 +3403,16 @@ ${cyan("Observability Commands:")}
   swarm export --format csv            Export as CSV
   swarm export --epic <id>             Export specific epic only
   swarm export --output <file>         Write to file instead of stdout
+  swarm tree                           Show all cells as tree
+  swarm tree --status open             Show only open cells
+  swarm tree --epic <id>               Show specific epic subtree
+  swarm tree --json                    Output as JSON
+
+${cyan("Session Management (Chainlink-inspired):")}
+  swarm session start [--cell <id>]    Start new session (shows previous handoff notes)
+  swarm session end [--notes "..."]    End session with handoff notes for next session
+  swarm session status                 Show current session info
+  swarm session history [--limit n]    Show session history (default: 10)
 
 ${cyan("Usage in OpenCode:")}
   /swarm "Add user authentication with OAuth"
@@ -6220,6 +6239,12 @@ switch (command) {
   case "export":
     await exportEvents();
     break;
+  case "tree":
+    await treeCommand();
+    break;
+  case "session":
+    await session();
+    break;
   case "version":
   case "--version":
   case "-v":