feat(plugin): add lifecycle hooks with debug logging support

Signed-off-by: leocavalcante <leo@cavalcante.dev>

Author: leocavalcante

src/plugin.ts

@@ -8,7 +8,69 @@
  * does not currently support dynamic agent registration.
  */
 
-import type { Plugin } from "@opencode-ai/plugin"
+import type { Hooks, Plugin, PluginInput } from "@opencode-ai/plugin"
+
+/** Plugin metadata for logging */
+const PLUGIN_NAME = "opencoder"
+
+/**
+ * Creates lifecycle hooks for debugging and visibility.
+ *
+ * These hooks provide optional logging points for plugin activity.
+ * Set OPENCODER_DEBUG=1 environment variable to enable debug logging.
+ *
+ * @param ctx - Plugin context from OpenCode
+ * @returns Hooks object with lifecycle callbacks
+ */
+function createLifecycleHooks(ctx: PluginInput): Hooks {
+	const debug = process.env.OPENCODER_DEBUG === "1"
+
+	const log = (message: string, data?: Record<string, unknown>) => {
+		if (debug) {
+			const timestamp = new Date().toISOString()
+			const prefix = `[${timestamp}] [${PLUGIN_NAME}]`
+			const context = { directory: ctx.directory, ...data }
+			console.log(prefix, message, JSON.stringify(context, null, 2))
+		}
+	}
+
+	return {
+		/**
+		 * Called on OpenCode events (sessions, messages, etc.)
+		 */
+		event: async ({ event }) => {
+			log("Event received", {
+				type: event.type,
+				properties: Object.keys(event.properties),
+			})
+		},
+
+		/**
+		 * Called before tool execution
+		 */
+		"tool.execute.before": async ({ tool, sessionID, callID }, output) => {
+			log("Tool executing", {
+				tool,
+				sessionID,
+				callID,
+				argsKeys: Object.keys(output.args || {}),
+			})
+		},
+
+		/**
+		 * Called after tool execution completes
+		 */
+		"tool.execute.after": async ({ tool, sessionID, callID }, output) => {
+			log("Tool completed", {
+				tool,
+				sessionID,
+				callID,
+				title: output.title,
+				outputLength: output.output?.length ?? 0,
+			})
+		},
+	}
+}
 
 /**
  * The OpenCoder plugin function.
@@ -22,10 +84,8 @@ import type { Plugin } from "@opencode-ai/plugin"
  *   opencode @opencoder
  *
  * @param ctx - Plugin context provided by OpenCode
- * @returns Hooks object for event subscriptions (minimal for now)
+ * @returns Hooks object with lifecycle callbacks for debugging visibility
  */
-export const OpenCoderPlugin: Plugin = async (_ctx) => {
-	// Return minimal hooks object
-	// Can be extended with event handlers in the future
-	return {}
+export const OpenCoderPlugin: Plugin = async (ctx) => {
+	return createLifecycleHooks(ctx)
 }

tests/plugin.test.ts

@@ -3,39 +3,66 @@ import type { PluginInput } from "@opencode-ai/plugin"
 import { OpenCoderPlugin } from "../src/plugin"
 
 describe("OpenCoderPlugin", () => {
-	it("should be an async function", () => {
-		expect(OpenCoderPlugin).toBeInstanceOf(Function)
-	})
-
-	it("should return a hooks object when called", async () => {
-		// Create a mock context (minimal implementation for testing)
-		const mockContext = {
+	// Create a mock context (minimal implementation for testing)
+	const createMockContext = () =>
+		({
 			project: {},
 			client: {},
 			$: () => {},
-			directory: "/tmp",
-			worktree: "/tmp",
+			directory: "/tmp/test-project",
+			worktree: "/tmp/test-project",
 			serverUrl: new URL("http://localhost:3000"),
-		} as unknown as PluginInput
+		}) as unknown as PluginInput
+
+	it("should be an async function", () => {
+		expect(OpenCoderPlugin).toBeInstanceOf(Function)
+	})
 
-		const result = await OpenCoderPlugin(mockContext)
+	it("should return a hooks object when called", async () => {
+		const result = await OpenCoderPlugin(createMockContext())
 
 		expect(result).toBeDefined()
 		expect(typeof result).toBe("object")
 	})
 
-	it("should return an empty hooks object (minimal implementation)", async () => {
-		const mockContext = {
-			project: {},
-			client: {},
-			$: () => {},
-			directory: "/tmp",
-			worktree: "/tmp",
-			serverUrl: new URL("http://localhost:3000"),
-		} as unknown as PluginInput
+	it("should return hooks object with lifecycle callbacks", async () => {
+		const result = await OpenCoderPlugin(createMockContext())
+
+		// Verify expected hooks are present
+		expect(result.event).toBeDefined()
+		expect(typeof result.event).toBe("function")
+		expect(result["tool.execute.before"]).toBeDefined()
+		expect(typeof result["tool.execute.before"]).toBe("function")
+		expect(result["tool.execute.after"]).toBeDefined()
+		expect(typeof result["tool.execute.after"]).toBe("function")
+	})
+
+	it("should have callable event hook", async () => {
+		const result = await OpenCoderPlugin(createMockContext())
+
+		// Event hook should be callable without throwing
+		const mockEvent = {
+			type: "session.created" as const,
+			properties: { sessionID: "test-123" },
+		}
+		await expect(result.event?.({ event: mockEvent as any })).resolves.toBeUndefined()
+	})
+
+	it("should have callable tool.execute.before hook", async () => {
+		const result = await OpenCoderPlugin(createMockContext())
+
+		const input = { tool: "bash", sessionID: "test-123", callID: "call-456" }
+		const output = { args: { command: "ls" } }
+
+		await expect(result["tool.execute.before"]?.(input, output)).resolves.toBeUndefined()
+	})
+
+	it("should have callable tool.execute.after hook", async () => {
+		const result = await OpenCoderPlugin(createMockContext())
 
-		const result = await OpenCoderPlugin(mockContext)
+		const input = { tool: "bash", sessionID: "test-123", callID: "call-456" }
+		const output = { title: "Command executed", output: "file1.txt\nfile2.txt", metadata: {} }
 
-		expect(Object.keys(result)).toHaveLength(0)
+		await expect(result["tool.execute.after"]?.(input, output)).resolves.toBeUndefined()
 	})
 })