feat(plugin-kit): @punktfunk/plugin-kit 0.1.0 — the Effect plugin framework

The ~80% of every plugin that was copy-pasted (rom-manager ↔ playnite),
extracted as one Effect-v4 package:

- runtime: definePluginKit — async-main boundary hiding a ManagedRuntime
  (two-effect-instances discipline), signal-driven interruption with a
  bounded shutdown grace
- config: Schema-driven raw round-trip (defaults only in the Schema via
  withDecodingDefaultKey + encodingStrategy omit; file stays authored-shape),
  atomic writes, world-writable refusal, changes stream
- cache-store: disposable derived state, corrupt→empty, write-through
- reconcile: kit-owned provider wire schemas + typed client over the
  skew-safe untyped pf.request seam
- sync-engine: generic poll/watch/debounce/single-flight-coalesce/
  fingerprint-skip engine with a status PubSub (the SSE feed)
- ui-server + sse: effect/unstable/httpapi behind servePluginUi with
  core-only env layers (validated by the phase-0 spikes); raw SSE route
  (httpapi has no event-stream media type)
- cli: minimal command dispatcher reusing the plugin layer graph
  (deliberately not effect/unstable/cli — it needs platform packages)
- react subpath: plugin router (path→hash→fallback deep-link restore +
  pf-ui:navigate bridge), ResultGate, sseAtom, resolvePluginBase
- theme.css: the console's violet identity packaged for plugin UIs

18 bun tests incl. the two phase-0 spikes; publish workflow mirrors
sdk-publish (tag plugin-kit-v*; 0.1.0 published manually).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

plugin-kit/test/config.test.ts

@@ -0,0 +1,143 @@
+// ConfigService semantics (the canonical suite — ported from rom-manager's state.test.ts
+// obligations): raw round-trip, schema defaults at decode only, atomic writes, missing
+// file == defaults, world-writable refusal, changes stream.
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { Effect, Fiber, Schema, Stream } from "effect";
+import {
+	type ConfigService,
+	makeConfigService,
+	pluginInfoLayer,
+	pluginStateDir,
+} from "../src/index.js";
+
+const TestSchema = Schema.Struct({
+	roots: Schema.Array(Schema.String).pipe(
+		Schema.withDecodingDefaultKey(Effect.succeed([]), {
+			encodingStrategy: "omit",
+		}),
+	),
+	sync: Schema.Struct({
+		pollMinutes: Schema.Number.pipe(
+			Schema.withDecodingDefaultKey(Effect.succeed(15), {
+				encodingStrategy: "omit",
+			}),
+		),
+		watch: Schema.Boolean.pipe(
+			Schema.withDecodingDefaultKey(Effect.succeed(true), {
+				encodingStrategy: "omit",
+			}),
+		),
+	}).pipe(
+		Schema.withDecodingDefaultKey(Effect.succeed({}), {
+			encodingStrategy: "omit",
+		}),
+	),
+});
+
+const PLUGIN = "kit-config-test";
+let tmp: string;
+
+const withService = <A>(
+	f: (svc: ConfigService<typeof TestSchema>) => Effect.Effect<A, unknown>,
+): Promise<A> =>
+	Effect.runPromise(
+		makeConfigService({ schema: TestSchema }).pipe(
+			Effect.flatMap(f),
+			Effect.provide(pluginInfoLayer({ name: PLUGIN })),
+		) as Effect.Effect<A, never>,
+	);
+
+beforeEach(() => {
+	tmp = fs.mkdtempSync(path.join(os.tmpdir(), "pf-kit-config-"));
+	process.env.PUNKTFUNK_CONFIG_DIR = tmp;
+});
+afterEach(() => {
+	delete process.env.PUNKTFUNK_CONFIG_DIR;
+	fs.rmSync(tmp, { recursive: true, force: true });
+});
+
+describe("ConfigService", () => {
+	test("missing file decodes to full defaults", async () => {
+		const loaded = await withService((svc) => svc.load);
+		expect(loaded).toEqual({
+			roots: [],
+			sync: { pollMinutes: 15, watch: true },
+		});
+	});
+
+	test("saveRaw persists the RAW shape verbatim (no defaults baked in)", async () => {
+		await withService((svc) => svc.saveRaw({ roots: ["/roms"] }));
+		const onDisk = JSON.parse(
+			fs.readFileSync(
+				path.join(pluginStateDir(PLUGIN), "config.json"),
+				"utf8",
+			),
+		);
+		expect(onDisk).toEqual({ roots: ["/roms"] }); // no sync block materialized
+		const loaded = await withService((svc) => svc.load);
+		expect(loaded.sync.pollMinutes).toBe(15);
+	});
+
+	test("saveRaw rejects an invalid raw config and leaves the file untouched", async () => {
+		await withService((svc) => svc.saveRaw({ roots: ["/a"] }));
+		const before = fs.readFileSync(
+			path.join(pluginStateDir(PLUGIN), "config.json"),
+			"utf8",
+		);
+		const exit = await withService((svc) =>
+			Effect.exit(svc.saveRaw({ roots: "not-an-array" })),
+		);
+		expect(exit._tag).toBe("Failure");
+		const after = fs.readFileSync(
+			path.join(pluginStateDir(PLUGIN), "config.json"),
+			"utf8",
+		);
+		expect(after).toBe(before);
+	});
+
+	test("unknown keys in the file are tolerated and survive loadRaw", async () => {
+		fs.mkdirSync(pluginStateDir(PLUGIN), { recursive: true, mode: 0o700 });
+		fs.writeFileSync(
+			path.join(pluginStateDir(PLUGIN), "config.json"),
+			JSON.stringify({ roots: [], ui: { port: 5885 }, devEntry: true }),
+			{ mode: 0o600 },
+		);
+		const raw = (await withService((svc) => svc.loadRaw)) as Record<
+			string,
+			unknown
+		>;
+		expect(raw.ui).toEqual({ port: 5885 }); // verbatim — a save decides what survives
+	});
+
+	test("refuses a group/world-writable config file (POSIX)", async () => {
+		if (process.platform === "win32") return;
+		fs.mkdirSync(pluginStateDir(PLUGIN), { recursive: true, mode: 0o700 });
+		const file = path.join(pluginStateDir(PLUGIN), "config.json");
+		fs.writeFileSync(file, "{}");
+		fs.chmodSync(file, 0o666); // bypass umask — writeFileSync's mode is masked
+		const exit = await withService((svc) => Effect.exit(svc.load));
+		expect(exit._tag).toBe("Failure");
+		if (exit._tag === "Failure") {
+			expect(String(exit.cause)).toContain("ConfigPermissionError");
+		}
+	});
+
+	test("changes stream emits the decoded config after saveRaw", async () => {
+		const decoded = await withService((svc) =>
+			Effect.gen(function* () {
+				const fiber = yield* Effect.forkChild(
+					svc.changes.pipe(Stream.take(1), Stream.runCollect),
+				);
+				yield* Effect.sleep("20 millis"); // let the subscription attach
+				yield* svc.saveRaw({ roots: ["/x"], sync: { pollMinutes: 5 } });
+				return yield* Fiber.join(fiber);
+			}),
+		);
+		expect(decoded).toEqual([
+			{ roots: ["/x"], sync: { pollMinutes: 5, watch: true } },
+		]);
+	});
+});

plugin-kit/test/spike-httpapi.test.ts

@@ -43,11 +43,11 @@ const groupLive = HttpApiBuilder.group(api, "spike", (handlers) =>
 		.handle("echo", ({ payload }) => Effect.succeed({ echoed: payload.msg })),
 );
 
-// Core-only environment for HttpApiBuilder: no platform package needed.
-const env = Layer.mergeAll(
-	Etag.layerWeak,
-	Path.layer,
-	HttpPlatform.layer.pipe(Layer.provide(FileSystem.layerNoop({}))),
+// Core-only environment for HttpApiBuilder: no platform package needed. FileSystem is
+// provideMerge'd so both HttpPlatform.layer and HttpApiBuilder see it satisfied.
+const env = Layer.provideMerge(
+	Layer.mergeAll(Etag.layerWeak, Path.layer, HttpPlatform.layer),
+	FileSystem.layerNoop({}),
 );
 
 const appLayer = HttpApiBuilder.layer(api).pipe(

plugin-kit/test/sse.test.ts

@@ -0,0 +1,35 @@
+// sseRoute: frame format + integration with the toWebHandler pipeline.
+import { describe, expect, test } from "bun:test";
+import { Layer, Schedule, Stream } from "effect";
+import { HttpRouter } from "effect/unstable/http";
+import { httpApiEnv, sseRoute } from "../src/index.js";
+
+describe("sseRoute", () => {
+	test("streams event frames in SSE wire format", async () => {
+		const stream = Stream.fromSchedule(Schedule.spaced("5 millis")).pipe(
+			Stream.map((n) => ({ tick: Number(n) })),
+			Stream.take(3),
+		);
+		const routes = sseRoute("/api/events", stream, {
+			event: "status",
+			pingSeconds: 0,
+		});
+		const { handler, dispose } = HttpRouter.toWebHandler(
+			Layer.provide(routes, httpApiEnv),
+		);
+		try {
+			const res = await handler(
+				new Request("http://127.0.0.1/api/events"),
+			);
+			expect(res.status).toBe(200);
+			expect(res.headers.get("content-type")).toContain(
+				"text/event-stream",
+			);
+			const text = await res.text();
+			expect(text).toContain('event: status\ndata: {"tick":0}\n\n');
+			expect(text).toContain('event: status\ndata: {"tick":2}\n\n');
+		} finally {
+			await dispose();
+		}
+	});
+});

plugin-kit/test/sync-engine.test.ts

@@ -0,0 +1,128 @@
+// SyncEngine semantics: fingerprint skip, single-flight coalescing, status feed.
+import { describe, expect, test } from "bun:test";
+import { Duration, Effect, Fiber, Ref, Scope, Stream } from "effect";
+import {
+	type LastSync,
+	makeSyncEngine,
+	type SyncOutcome,
+} from "../src/index.js";
+
+interface Report {
+	readonly included: number;
+}
+
+const harness = (opts?: {
+	computeDelayMs?: number;
+	entries?: () => ReadonlyArray<string>;
+}) =>
+	Effect.gen(function* () {
+		const applied = yield* Ref.make(0);
+		const last = yield* Ref.make<LastSync | undefined>(undefined);
+		const entries = opts?.entries ?? (() => ["a", "b"]);
+		const engine = yield* makeSyncEngine<Report, ReadonlyArray<string>, never>(
+			{
+				compute: () =>
+					Effect.suspend(() => {
+						const e = entries();
+						return Effect.succeed({
+							entries: e,
+							report: { included: e.length },
+						});
+					}).pipe(
+						opts?.computeDelayMs
+							? Effect.delay(Duration.millis(opts.computeDelayMs))
+							: (x) => x,
+					),
+				apply: () => Ref.update(applied, (n) => n + 1),
+				lastSync: {
+					get: Ref.get(last),
+					set: (l) => Ref.set(last, l),
+				},
+				settings: Effect.succeed({
+					pollInterval: Duration.minutes(60),
+					watch: false,
+					debounce: Duration.millis(10),
+					watchDirs: [],
+				}),
+			},
+		);
+		return { engine, applied, last };
+	});
+
+const run = <A>(eff: Effect.Effect<A, unknown, Scope.Scope>): Promise<A> =>
+	Effect.runPromise(Effect.scoped(eff) as Effect.Effect<A>);
+
+describe("SyncEngine", () => {
+	test("first sync applies; unchanged content skips the apply", async () => {
+		const { first, second, count } = await run(
+			Effect.gen(function* () {
+				const h = yield* harness();
+				const first = yield* h.engine.sync("manual");
+				const second = yield* h.engine.sync("manual");
+				return {
+					first,
+					second,
+					count: yield* Ref.get(h.applied),
+				};
+			}),
+		);
+		expect(first._tag).toBe("Applied");
+		if (first._tag === "Applied") expect(first.count).toBe(2);
+		expect(second._tag).toBe("Unchanged");
+		expect(count).toBe(1);
+	});
+
+	test("changed content re-applies", async () => {
+		let call = 0;
+		const { outcomes, count } = await run(
+			Effect.gen(function* () {
+				const h = yield* harness({
+					entries: () => (call++ === 0 ? ["a"] : ["a", "b"]),
+				});
+				const o1 = yield* h.engine.sync("manual");
+				const o2 = yield* h.engine.sync("manual");
+				return { outcomes: [o1, o2], count: yield* Ref.get(h.applied) };
+			}),
+		);
+		expect(outcomes.map((o: SyncOutcome<Report>) => o._tag)).toEqual([
+			"Applied",
+			"Applied",
+		]);
+		expect(count).toBe(2);
+	});
+
+	test("concurrent trigger returns AlreadyRunning and coalesces into a follow-up", async () => {
+		const { during, count } = await run(
+			Effect.gen(function* () {
+				const h = yield* harness({ computeDelayMs: 50 });
+				const fiber = yield* Effect.forkChild(h.engine.sync("manual"));
+				yield* Effect.sleep("10 millis");
+				const during = yield* h.engine.sync("manual");
+				yield* Fiber.join(fiber);
+				// the coalesced re-run is forked detached — give it a beat
+				yield* Effect.sleep("120 millis");
+				return { during, count: yield* Ref.get(h.applied) };
+			}),
+		);
+		expect(during._tag).toBe("AlreadyRunning");
+		// first sync applied; the coalesced pass found identical content → skipped
+		expect(count).toBe(1);
+	});
+
+	test("status feed publishes syncing transitions", async () => {
+		const statuses = await run(
+			Effect.gen(function* () {
+				const h = yield* harness();
+				const fiber = yield* Effect.forkChild(
+					h.engine.changes.pipe(Stream.take(2), Stream.runCollect),
+				);
+				yield* Effect.sleep("20 millis");
+				yield* h.engine.sync("manual");
+				return yield* Fiber.join(fiber);
+			}),
+		);
+		expect(statuses[0]?.syncing).toBe(true);
+		expect(statuses[1]?.syncing).toBe(false);
+		expect(statuses[1]?.lastSync?.count).toBe(2);
+	});
+});