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/src/cli.ts

@@ -0,0 +1,88 @@
+// Minimal plugin CLI scaffold. Deliberately NOT `effect/unstable/cli`: its runner needs
+// Stdio/Terminal/FileSystem service implementations that only ship in platform packages,
+// which would add a runtime dependency to every plugin for what is a five-verb ops tool.
+// A plugin CLI is `<bin> <command> [args...]` — this dispatcher gives that shape the same
+// ManagedRuntime + layer graph as the plugin entry, so commands reuse the exact services.
+import { connect, type Punktfunk } from "@punktfunk/host";
+import { Effect, Layer, ManagedRuntime } from "effect";
+import {
+	type HostClient,
+	hostClientFromFacade,
+	type PluginInfo,
+	pluginInfoLayer,
+} from "./host-client.js";
+import { HostRequestError } from "./errors.js";
+import { loggingLayer } from "./logging.js";
+import type { PluginKitDef } from "./runtime.js";
+
+export interface CliCommand<R> {
+	readonly summary: string;
+	/** Set when the command works without a running host (scan/preview style). */
+	readonly offline?: boolean;
+	readonly run: (
+		argv: ReadonlyArray<string>,
+	) => Effect.Effect<void, unknown, R | HostClient | PluginInfo>;
+}
+
+/** A HostClient whose calls fail — the offline lane for host-free commands. */
+const offlineFacade = (name: string): Punktfunk =>
+	({
+		request: async (method: string, path: string) => {
+			throw new Error(
+				`${name}: this command ran offline but tried ${method} ${path} — is the host running?`,
+			);
+		},
+		close: () => {},
+	}) as unknown as Punktfunk;
+
+const usage = <R>(
+	def: { name: string; version?: string },
+	commands: Record<string, CliCommand<R>>,
+): string => {
+	const rows = Object.entries(commands)
+		.map(([cmd, c]) => `  ${cmd.padEnd(12)} ${c.summary}`)
+		.join("\n");
+	return `${def.name}${def.version ? ` ${def.version}` : ""}\n\nUsage: punktfunk-plugin-${def.name} <command> [args...]\n\nCommands:\n${rows}\n`;
+};
+
+/**
+ * Run one CLI invocation: dispatch `process.argv[2]`, build the plugin's layer graph,
+ * run the command, tear down. Exits the process (0 ok / 1 failure / 2 usage).
+ */
+export const runPluginCli = async <E, R>(opts: {
+	readonly def: PluginKitDef<E, R>;
+	readonly commands: Record<string, CliCommand<R>>;
+	readonly argv?: ReadonlyArray<string>;
+}): Promise<void> => {
+	const argv = opts.argv ?? process.argv.slice(2);
+	const [name, ...rest] = argv;
+	const command = name ? opts.commands[name] : undefined;
+	if (!command) {
+		console.log(usage(opts.def, opts.commands));
+		process.exit(name === undefined || name === "help" ? 0 : 2);
+	}
+
+	const pf = command.offline
+		? offlineFacade(opts.def.name)
+		: await connect();
+	const base = Layer.mergeAll(
+		hostClientFromFacade(pf),
+		pluginInfoLayer({ name: opts.def.name, version: opts.def.version }),
+		loggingLayer(opts.def.name),
+	);
+	const rt = ManagedRuntime.make(Layer.provideMerge(opts.def.layer, base));
+	try {
+		await rt.runPromise(Effect.scoped(command.run(rest)));
+		process.exitCode = 0;
+	} catch (e) {
+		const hint =
+			e instanceof HostRequestError
+				? " (is the punktfunk host running?)"
+				: "";
+		console.error(`${opts.def.name}: ${name} failed: ${e}${hint}`);
+		process.exitCode = 1;
+	} finally {
+		await rt.dispose();
+		pf.close();
+	}
+};