saeeol 1.3.0 → 1.3.1

package/test/plugin/meta.test.ts

@@ -0,0 +1,137 @@
+import { afterEach, describe, expect, test } from "bun:test"
+import fs from "fs/promises"
+import path from "path"
+import { pathToFileURL } from "url"
+
+import { tmpdir } from "../fixture/fixture"
+import { Process } from "@/util/process"
+import { Filesystem } from "@/util/filesystem"
+
+const { PluginMeta } = await import("../../src/plugin/meta")
+const root = path.join(import.meta.dir, "../..")
+const worker = path.join(import.meta.dir, "../fixture/plugin-meta-worker.ts")
+
+function run(input: { file: string; spec: string; target: string; id: string }) {
+  return Process.run([process.execPath, worker, JSON.stringify(input)], {
+    cwd: root,
+    nothrow: true,
+  })
+}
+
+async function map<Value>(file: string): Promise<Record<string, Value>> {
+  return Filesystem.readJson<Record<string, Value>>(file)
+}
+
+afterEach(() => {
+  delete process.env.SAEEOL_PLUGIN_META_FILE
+})
+
+describe("plugin.meta", () => {
+  test("tracks file plugin loads and changes", async () => {
+    await using tmp = await tmpdir<{ file: string }>({
+      init: async (dir) => {
+        const file = path.join(dir, "plugin.ts")
+        await Bun.write(file, "export default async () => ({})\n")
+        return { file }
+      },
+    })
+
+    process.env.SAEEOL_PLUGIN_META_FILE = path.join(tmp.path, "state", "plugin-meta.json")
+    const file = process.env.SAEEOL_PLUGIN_META_FILE!
+    const spec = pathToFileURL(tmp.extra.file).href
+
+    const one = await PluginMeta.touch(spec, spec, "demo.file")
+    expect(one.state).toBe("first")
+    expect(one.entry.source).toBe("file")
+    expect(one.entry.id).toBe("demo.file")
+    expect(one.entry.modified).toBeDefined()
+
+    const two = await PluginMeta.touch(spec, spec, "demo.file")
+    expect(two.state).toBe("same")
+    expect(two.entry.load_count).toBe(2)
+    // WORKAROUND: bun 1.3.11 fs.utimes produces 32-bit overflow for current-era timestamps.
+    // Use a real write after a brief sleep so the OS assigns a naturally different mtime.
+    await Bun.sleep(1100)
+    await Bun.write(tmp.extra.file, "export default async () => ({ ok: true })\n")
+
+    const three = await PluginMeta.touch(spec, spec, "demo.file")
+    expect(three.state).toBe("updated")
+    expect(three.entry.load_count).toBe(3)
+    expect((three.entry.modified ?? 0) > (one.entry.modified ?? 0)).toBe(true)
+
+    const all = await PluginMeta.list()
+    expect(Object.values(all).some((item) => item.spec === spec && item.source === "file")).toBe(true)
+    const saved = await map<{ spec: string; load_count: number }>(file)
+    expect(saved["demo.file"]?.spec).toBe(spec)
+    expect(saved["demo.file"]?.load_count).toBe(3)
+  })
+
+  test("tracks npm plugin versions", async () => {
+    await using tmp = await tmpdir<{ mod: string; pkg: string }>({
+      init: async (dir) => {
+        const mod = path.join(dir, "node_modules", "acme-plugin")
+        const pkg = path.join(mod, "package.json")
+        await fs.mkdir(mod, { recursive: true })
+        await Bun.write(pkg, JSON.stringify({ name: "acme-plugin", version: "1.0.0" }, null, 2))
+        return { mod, pkg }
+      },
+    })
+
+    process.env.SAEEOL_PLUGIN_META_FILE = path.join(tmp.path, "state", "plugin-meta.json")
+    const file = process.env.SAEEOL_PLUGIN_META_FILE!
+
+    const one = await PluginMeta.touch("acme-plugin@latest", tmp.extra.mod, "acme-plugin")
+    expect(one.state).toBe("first")
+    expect(one.entry.source).toBe("npm")
+    expect(one.entry.requested).toBe("latest")
+    expect(one.entry.version).toBe("1.0.0")
+
+    await Bun.write(tmp.extra.pkg, JSON.stringify({ name: "acme-plugin", version: "1.1.0" }, null, 2))
+
+    const two = await PluginMeta.touch("acme-plugin@latest", tmp.extra.mod, "acme-plugin")
+    expect(two.state).toBe("updated")
+    expect(two.entry.version).toBe("1.1.0")
+    expect(two.entry.load_count).toBe(2)
+
+    const all = await PluginMeta.list()
+    expect(Object.values(all).some((item) => item.id === "acme-plugin" && item.version === "1.1.0")).toBe(true)
+    const saved = await map<{ id: string; version?: string }>(file)
+    expect(Object.values(saved).some((item) => item.id === "acme-plugin" && item.version === "1.1.0")).toBe(true)
+  })
+
+  test("serializes concurrent metadata updates across processes", async () => {
+    await using tmp = await tmpdir<{ file: string }>({
+      init: async (dir) => {
+        const file = path.join(dir, "plugin.ts")
+        await Bun.write(file, "export default async () => ({})\n")
+        return { file }
+      },
+    })
+
+    process.env.SAEEOL_PLUGIN_META_FILE = path.join(tmp.path, "state", "plugin-meta.json")
+    const file = process.env.SAEEOL_PLUGIN_META_FILE!
+    const spec = pathToFileURL(tmp.extra.file).href
+    const n = 12
+
+    const out = await Promise.all(
+      Array.from({ length: n }, () =>
+        run({
+          file,
+          spec,
+          target: spec,
+          id: "demo.file",
+        }),
+      ),
+    )
+
+    expect(out.map((item) => item.code)).toEqual(Array.from({ length: n }, () => 0))
+    expect(out.map((item) => item.stderr.toString()).filter(Boolean)).toEqual([])
+
+    const all = await PluginMeta.list()
+    const hit = Object.values(all).find((item) => item.spec === spec)
+    expect(hit?.load_count).toBe(n)
+
+    const saved = await map<{ spec: string; load_count: number }>(file)
+    expect(Object.values(saved).find((item) => item.spec === spec)?.load_count).toBe(n)
+  }, 20_000)
+})

package/test/plugin/plugin-contract.test.ts

@@ -0,0 +1,291 @@
+/**
+ * plugin-contract.test.ts — 플러그인 시스템 컨슈머 계약 테스트
+ *
+ * closebook: consumer-contract
+ *
+ * 플러그인 인터페이스 계약 검증:
+ * - Plugin 함수가 올바른 Hooks 객체를 반환하는지
+ * - Hooks 인터페이스가 각 hook의 시그니처를 만족하는지
+ * - PluginInput 컨텍스트가 기대하는 필드를 제공하는지
+ * - 계약 파일(JSON) 직렬화 및 검증
+ */
+
+import { describe, expect, test } from "bun:test"
+import { z } from "zod"
+import { Hono } from "hono"
+import type { Plugin, Hooks, PluginInput, AuthHook, ProviderHook } from "@saeeol/plugin"
+import { tool } from "@saeeol/plugin"
+
+// ── 계약 스키마 정의 ──
+
+const HooksSchema = z.object({
+	event: z.unknown().optional(),
+	config: z.unknown().optional(),
+	tool: z.record(z.string(), z.unknown()).optional(),
+	auth: z
+		.object({
+			provider: z.string(),
+			methods: z.array(z.unknown()),
+		})
+		.optional(),
+	provider: z
+		.object({
+			id: z.string(),
+		})
+		.optional(),
+})
+
+const PluginInputSchema = z.object({
+	client: z.unknown(),
+	project: z.unknown(),
+	directory: z.string(),
+	worktree: z.string(),
+	serverUrl: z.instanceof(URL),
+	experimental_workspace: z.object({
+		register: z.unknown(),
+	}),
+})
+
+// ── 모의 Hono 앱 생성 (인터랙션 기반) ──
+
+function createMockApp(interactions: Array<{ method: string; path: string; body?: unknown; status: number; response: unknown }>) {
+	const app = new Hono()
+	for (const ix of interactions) {
+		app.on(ix.method, ix.path, (c) => c.json(ix.response, ix.status as 200))
+	}
+	return app
+}
+
+// ── 계약 정의 헬퍼 ──
+
+interface ContractInteraction {
+	state?: string
+	description: string
+	request: { method: string; path: string; headers?: Record<string, string>; body?: unknown }
+	response: { status: number; body?: unknown }
+}
+
+interface PluginContract {
+	consumer: string
+	provider: string
+	interactions: ContractInteraction[]
+}
+
+function defineContract(spec: PluginContract) {
+	return {
+		spec,
+		serialize(): string {
+			return JSON.stringify(
+				{
+					consumer: { name: spec.consumer },
+					provider: { name: spec.provider },
+					interactions: spec.interactions.map((ix) => ({
+						description: ix.description,
+						providerStates: ix.state ? [{ name: ix.state }] : [],
+						request: ix.request,
+						response: ix.response,
+					})),
+					metadata: { version: "1.0.0" },
+				},
+				null,
+				2,
+			)
+		},
+	}
+}
+
+// ── 테스트 ──
+
+describe("plugin consumer contract: Plugin function signature", () => {
+	test("plugin function returns valid Hooks object", async () => {
+		const mock: Plugin = async () => ({
+			event: async () => {},
+			config: async () => {},
+		})
+		const hooks = await mock({} as PluginInput)
+		const parsed = HooksSchema.safeParse(hooks)
+		expect(parsed.success).toBe(true)
+		if (!parsed.success) {
+			console.error("Hooks contract violations:", parsed.error.issues)
+		}
+	})
+
+	test("plugin with tool hook returns valid Hooks", async () => {
+		const mock: Plugin = async () => ({
+			tool: {
+				example: tool({
+					description: "example tool",
+					args: { input: z.string() },
+					async execute(args, ctx) {
+						return args.input
+					},
+				}),
+			},
+		})
+		const hooks = await mock({} as PluginInput)
+		expect(hooks.tool).toBeDefined()
+		expect(hooks.tool?.example).toBeDefined()
+		expect(hooks.tool?.example.description).toBe("example tool")
+	})
+
+	test("plugin with auth hook returns valid Hooks", async () => {
+		const authHook: AuthHook = {
+			provider: "test-provider",
+			methods: [
+				{
+					type: "api",
+					label: "Test Auth",
+					async authorize() {
+						return { type: "success", key: "test-key" }
+					},
+				},
+			],
+		}
+		const mock: Plugin = async () => ({ auth: authHook })
+		const hooks = await mock({} as PluginInput)
+		expect(hooks.auth).toBeDefined()
+		expect(hooks.auth?.provider).toBe("test-provider")
+		expect(hooks.auth?.methods.length).toBe(1)
+	})
+
+	test("plugin with provider hook returns valid Hooks", async () => {
+		const providerHook: ProviderHook = {
+			id: "test-provider",
+		}
+		const mock: Plugin = async () => ({ provider: providerHook })
+		const hooks = await mock({} as PluginInput)
+		expect(hooks.provider).toBeDefined()
+		expect(hooks.provider?.id).toBe("test-provider")
+	})
+})
+
+describe("plugin consumer contract: PluginInput shape", () => {
+	test("PluginInput schema validates required fields", () => {
+		const input = {
+			client: {},
+			project: {},
+			directory: "/tmp/test",
+			worktree: "/tmp/test",
+			serverUrl: new URL("http://localhost:4096"),
+			experimental_workspace: {
+				register: () => {},
+			},
+			$: undefined,
+		}
+		const parsed = PluginInputSchema.safeParse(input)
+		expect(parsed.success).toBe(true)
+		if (!parsed.success) {
+			console.error("PluginInput contract violations:", parsed.error.issues)
+		}
+	})
+})
+
+describe("plugin consumer contract: trigger hook contracts", () => {
+	test("chat.message hook receives correct input/output shape", async () => {
+		const received: unknown[] = []
+		const mock: Plugin = async () => ({
+			"chat.message": async (input, output) => {
+				received.push({ input, output })
+			},
+		})
+		const hooks = await mock({} as PluginInput)
+
+		const testInput = {
+			sessionID: "sess_123",
+			agent: "build",
+			model: { providerID: "test", modelID: "test-model" },
+		}
+		const testOutput = {
+			message: { id: "msg_1", role: "user" as const },
+			parts: [],
+		}
+		await hooks["chat.message"]?.(testInput as any, testOutput as any)
+		expect(received.length).toBe(1)
+		expect((received[0] as any).input.sessionID).toBe("sess_123")
+	})
+
+	test("chat.params hook can modify output", async () => {
+		const mock: Plugin = async () => ({
+			"chat.params": async (_input, output) => {
+				output.temperature = 0.5
+			},
+		})
+		const hooks = await mock({} as PluginInput)
+
+		const output = { temperature: 1.0, topP: 1.0, topK: 40, maxOutputTokens: undefined, options: {} }
+		await hooks["chat.params"]?.({} as any, output as any)
+		expect(output.temperature).toBe(0.5)
+	})
+
+	test("shell.env hook can inject environment variables", async () => {
+		const mock: Plugin = async () => ({
+			"shell.env": async (_input, output) => {
+				output.env.CUSTOM_VAR = "injected"
+			},
+		})
+		const hooks = await mock({} as PluginInput)
+
+		const output = { env: {} as Record<string, string> }
+		await hooks["shell.env"]?.({ cwd: "/tmp" } as any, output as any)
+		expect(output.env.CUSTOM_VAR).toBe("injected")
+	})
+
+	test("permission.ask hook can override permission decision", async () => {
+		const mock: Plugin = async () => ({
+			"permission.ask": async (_input, output) => {
+				output.status = "allow"
+			},
+		})
+		const hooks = await mock({} as PluginInput)
+
+		const output = { status: "ask" as "ask" | "deny" | "allow" }
+		await hooks["permission.ask"]?.({} as any, output)
+		expect(output.status).toBe("allow")
+	})
+})
+
+describe("plugin consumer contract: pact artifact generation", () => {
+	test("generates valid contract JSON from plugin interactions", async () => {
+		const contract = defineContract({
+			consumer: "saeeol-server",
+			provider: "saeeol-plugin-interface",
+			interactions: [
+				{
+					state: "plugin loaded",
+					description: "plugin returns hooks with event callback",
+					request: { method: "POST", path: "/plugin/init", body: {} },
+					response: { status: 200, body: { event: "[function]" } },
+				},
+				{
+					description: "trigger chat.message hook",
+					request: { method: "POST", path: "/plugin/hook/chat.message", body: { sessionID: "test" } },
+					response: { status: 200, body: {} },
+				},
+			],
+		})
+
+		const serialized = contract.serialize()
+		const parsed = JSON.parse(serialized)
+		expect(parsed.consumer.name).toBe("saeeol-server")
+		expect(parsed.provider.name).toBe("saeeol-plugin-interface")
+		expect(parsed.interactions.length).toBe(2)
+		expect(parsed.metadata.version).toBe("1.0.0")
+	})
+
+	test("mock app serves contract interactions correctly", async () => {
+		const mockApp = createMockApp([
+			{ method: "GET", path: "/api/test", status: 200, response: { ok: true } },
+			{ method: "POST", path: "/api/create", status: 201, response: { id: "new" } },
+		])
+
+		const getRes = await mockApp.request("/api/test")
+		const getBody = await getRes.json()
+		expect(getRes.status).toBe(200)
+		expect(getBody).toEqual({ ok: true })
+
+		const postRes = await mockApp.request("/api/create", { method: "POST" })
+		const postBody = await postRes.json()
+		expect(postRes.status).toBe(201)
+		expect(postBody).toEqual({ id: "new" })
+	})
+})

package/test/plugin/shared.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, test } from "bun:test"
+import { parsePluginSpecifier } from "../../src/plugin/shared"
+
+describe("parsePluginSpecifier", () => {
+  test("parses standard npm package without version", () => {
+    expect(parsePluginSpecifier("acme")).toEqual({
+      pkg: "acme",
+      version: "latest",
+    })
+  })
+
+  test("parses standard npm package with version", () => {
+    expect(parsePluginSpecifier("acme@1.0.0")).toEqual({
+      pkg: "acme",
+      version: "1.0.0",
+    })
+  })
+
+  test("parses scoped npm package without version", () => {
+    expect(parsePluginSpecifier("@saeeol/acme")).toEqual({
+      pkg: "@saeeol/acme",
+      version: "latest",
+    })
+  })
+
+  test("parses scoped npm package with version", () => {
+    expect(parsePluginSpecifier("@saeeol/acme@1.0.0")).toEqual({
+      pkg: "@saeeol/acme",
+      version: "1.0.0",
+    })
+  })
+
+  test("parses package with git+https url", () => {
+    expect(parsePluginSpecifier("acme@git+https://github.com/saeeol/acme.git")).toEqual({
+      pkg: "acme",
+      version: "git+https://github.com/saeeol/acme.git",
+    })
+  })
+
+  test("parses scoped package with git+https url", () => {
+    expect(parsePluginSpecifier("@saeeol/acme@git+https://github.com/saeeol/acme.git")).toEqual({
+      pkg: "@saeeol/acme",
+      version: "git+https://github.com/saeeol/acme.git",
+    })
+  })
+
+  test("parses package with git+ssh url containing another @", () => {
+    expect(parsePluginSpecifier("acme@git+ssh://git@github.com/saeeol/acme.git")).toEqual({
+      pkg: "acme",
+      version: "git+ssh://git@github.com/saeeol/acme.git",
+    })
+  })
+
+  test("parses scoped package with git+ssh url containing another @", () => {
+    expect(parsePluginSpecifier("@saeeol/acme@git+ssh://git@github.com/saeeol/acme.git")).toEqual({
+      pkg: "@saeeol/acme",
+      version: "git+ssh://git@github.com/saeeol/acme.git",
+    })
+  })
+
+  test("parses unaliased git+ssh url", () => {
+    expect(parsePluginSpecifier("git+ssh://git@github.com/saeeol/acme.git")).toEqual({
+      pkg: "git+ssh://git@github.com/saeeol/acme.git",
+      version: "",
+    })
+  })
+
+  test("parses npm alias using the alias name", () => {
+    expect(parsePluginSpecifier("acme@npm:@saeeol/acme@1.0.0")).toEqual({
+      pkg: "acme",
+      version: "npm:@saeeol/acme@1.0.0",
+    })
+  })
+
+  test("parses bare npm protocol specifier using the target package", () => {
+    expect(parsePluginSpecifier("npm:@saeeol/acme@1.0.0")).toEqual({
+      pkg: "@saeeol/acme",
+      version: "1.0.0",
+    })
+  })
+
+  test("parses unversioned npm protocol specifier", () => {
+    expect(parsePluginSpecifier("npm:@saeeol/acme")).toEqual({
+      pkg: "@saeeol/acme",
+      version: "latest",
+    })
+  })
+})

package/test/plugin/trigger.test.ts

@@ -0,0 +1,102 @@
+import { afterAll, describe, expect } from "bun:test"
+import { Effect, Layer } from "effect"
+import { CrossSpawnSpawner } from "@saeeol/core/cross-spawn-spawner"
+import path from "path"
+import { pathToFileURL } from "url"
+import { ModelID, ProviderID } from "../../src/provider/schema"
+import { provideTmpdirInstance } from "../fixture/fixture"
+import { testEffect } from "../lib/effect"
+
+const disableDefault = process.env.SAEEOL_DISABLE_DEFAULT_PLUGINS
+process.env.SAEEOL_DISABLE_DEFAULT_PLUGINS = "1"
+
+const { Plugin } = await import("../../src/plugin/index")
+const it = testEffect(Layer.mergeAll(Plugin.defaultLayer, CrossSpawnSpawner.defaultLayer))
+const systemHook = "experimental.chat.system.transform"
+
+afterAll(() => {
+  if (disableDefault === undefined) {
+    delete process.env.SAEEOL_DISABLE_DEFAULT_PLUGINS
+    return
+  }
+  process.env.SAEEOL_DISABLE_DEFAULT_PLUGINS = disableDefault
+})
+
+function withProject<A, E, R>(source: string, self: Effect.Effect<A, E, R>) {
+  return provideTmpdirInstance((dir) =>
+    Effect.gen(function* () {
+      const file = path.join(dir, "plugin.ts")
+      yield* Effect.all(
+        [
+          Effect.promise(() => Bun.write(file, source)),
+          Effect.promise(() =>
+            Bun.write(
+              path.join(dir, "saeeol.json"),
+              JSON.stringify(
+                {
+                  $schema: "https://saeeol.ai/config.json",
+                  plugin: [pathToFileURL(file).href],
+                },
+                null,
+                2,
+              ),
+            ),
+          ),
+        ],
+        { discard: true, concurrency: 2 },
+      )
+      return yield* self
+    }),
+  )
+}
+
+const triggerSystemTransform = Effect.fn("PluginTriggerTest.triggerSystemTransform")(function* () {
+  const plugin = yield* Plugin.Service
+  const out = { system: [] as string[] }
+  yield* plugin.trigger(
+    systemHook,
+    {
+      model: {
+        providerID: ProviderID.anthropic,
+        modelID: ModelID.make("claude-sonnet-4-6"),
+      },
+    },
+    out,
+  )
+  return out.system
+})
+
+describe("plugin.trigger", () => {
+  it.live("runs synchronous hooks without crashing", () =>
+    withProject(
+      [
+        "export default async () => ({",
+        `  ${JSON.stringify(systemHook)}: (_input, output) => {`,
+        '    output.system.unshift("sync")',
+        "  },",
+        "})",
+        "",
+      ].join("\n"),
+      Effect.gen(function* () {
+        expect(yield* triggerSystemTransform()).toEqual(["sync"])
+      }),
+    ),
+  )
+
+  it.live("awaits asynchronous hooks", () =>
+    withProject(
+      [
+        "export default async () => ({",
+        `  ${JSON.stringify(systemHook)}: async (_input, output) => {`,
+        "    await Bun.sleep(1)",
+        '    output.system.unshift("async")',
+        "  },",
+        "})",
+        "",
+      ].join("\n"),
+      Effect.gen(function* () {
+        expect(yield* triggerSystemTransform()).toEqual(["async"])
+      }),
+    ),
+  )
+})