feat(sdk): @punktfunk/host — the Effect TypeScript SDK (M3)

New top-level sdk/ package (RFC §7): a typed management-API client plus
the lifecycle event stream, built on Effect, two surfaces over one core:

- @punktfunk/host — the Promise facade front door: connect() resolves
  URL/token/TLS pin from the host's own files (zero config on the box),
  fails fast on bad credentials, pf.events.on() with typed callbacks
  (exact kinds, domain.* prefixes, "*", "dropped", "unknown"),
  pf.request() for the REST surface. Effect never required.
- @punktfunk/host/effect — the PunktfunkHost service + PunktfunkHostLive
  layer, Stream-based events()/eventsRaw(), typed errors
  (AuthError | ApiError | TransportError | VersionSkew — a 2xx that
  fails its schema is a typed skew, not undefined later), and every
  wire shape as an effect/Schema: REST generated via orval
  client:'effect' from api/openapi.json (S3 spike: works well; the
  text/event-stream payload is out of its reach), events hand-mirrored
  from the host's snapshot-tested wire format as a kind-discriminated
  union.

One reconnecting SSE core under both surfaces: spec-shaped parser,
exponential+jittered backoff (capped, resets after a healthy
connection), Last-Event-ID resume, 401 terminal. Default is LIVE tail
only — a fresh notify script must not re-fire on the host's replayed
ring (since: 0 opts into full replay).

TLS: the pin trusts exactly the host's self-signed identity cert
(chain-verified; hostname check waived — the cert is deliberately
CN-only for fingerprint pinning). Bun via fetch tls, Node via an undici
dispatcher (optionalDependency).

definePlugin() accepts both main shapes (async fn | Effect requiring
PunktfunkHost). Examples in both styles; README carries the compat
contract + systemd/Task Scheduler templates.

11 bun tests green (wire decode against the Rust snapshot strings,
SSE parser/reconnect/Last-Event-ID/401, both surfaces vs a mock host).
Live-verified against a real host on Bun AND Node through the pinned
loopback hop: connect → REST mutate → live event received → resume
cursor advanced; a wrong CA is rejected. npm publish + CI wiring
deferred (npm org = RFC open question 1).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

sdk/src/config.ts

@@ -0,0 +1,128 @@
+// Connection resolution (RFC §7): loopback URL + bearer token + the host's self-signed
+// identity cert, from the environment with file fallbacks — so `connect()` on the host machine
+// needs zero configuration.
+//
+//   PUNKTFUNK_MGMT_URL    (default https://127.0.0.1:47990)
+//   PUNKTFUNK_MGMT_TOKEN  (else <config_dir>/mgmt-token)
+//   PUNKTFUNK_MGMT_CA     (path; else <config_dir>/cert.pem when present)
+//
+// The CA is the host's own identity certificate — trusting exactly it (not the system roots)
+// IS the pin for the loopback hop. Per-runtime plumbing differs: Bun takes `tls.ca` on fetch,
+// Node (undici) takes a dispatcher with a CA-carrying TLS connector; anything else falls back
+// to plain fetch (document PUNKTFUNK_MGMT_CA + NODE_EXTRA_CA_CERTS there).
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export interface ConnectOptions {
+	/** Management API base URL (default `https://127.0.0.1:47990`). */
+	url?: string;
+	/** Bearer token (default: `PUNKTFUNK_MGMT_TOKEN`, else the host's `mgmt-token` file). */
+	token?: string;
+	/** PEM of the CA to trust — the host's identity cert (default: `PUNKTFUNK_MGMT_CA`, else `cert.pem`). */
+	ca?: string;
+}
+
+export interface ResolvedConfig {
+	url: string;
+	token: string;
+	ca?: string;
+	/** A fetch honoring `ca` on this runtime. */
+	fetch: typeof fetch;
+}
+
+/** The host's config dir — the same resolution the host itself uses. */
+export const configDir = (): string => {
+	const explicit = process.env.PUNKTFUNK_CONFIG_DIR;
+	if (explicit) return explicit;
+	if (process.platform === "win32") {
+		const base = process.env.ProgramData ?? process.env.APPDATA ?? ".";
+		return path.join(base, "punktfunk");
+	}
+	const base =
+		process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config");
+	return path.join(base, "punktfunk");
+};
+
+const readIfExists = (p: string): string | undefined => {
+	try {
+		return fs.readFileSync(p, "utf8");
+	} catch {
+		return undefined;
+	}
+};
+
+/** First token-looking line of the mgmt-token file (tolerates `TOKEN=`-style and blank lines). */
+const parseTokenFile = (raw: string): string | undefined => {
+	for (const line of raw.split(/\r?\n/)) {
+		const t = line.trim();
+		if (t.length === 0 || t.startsWith("#")) continue;
+		return t.includes("=") ? t.slice(t.indexOf("=") + 1).trim() : t;
+	}
+	return undefined;
+};
+
+export const resolveConfig = async (
+	options?: ConnectOptions,
+): Promise<ResolvedConfig> => {
+	const url = (
+		options?.url ??
+		process.env.PUNKTFUNK_MGMT_URL ??
+		"https://127.0.0.1:47990"
+	).replace(/\/+$/, "");
+	const token =
+		options?.token ??
+		process.env.PUNKTFUNK_MGMT_TOKEN ??
+		parseTokenFile(readIfExists(path.join(configDir(), "mgmt-token")) ?? "");
+	if (!token) {
+		throw new Error(
+			"no management token: set PUNKTFUNK_MGMT_TOKEN, pass { token }, or run where " +
+				`the host's token file exists (${path.join(configDir(), "mgmt-token")})`,
+		);
+	}
+	const caPath = process.env.PUNKTFUNK_MGMT_CA;
+	const ca =
+		options?.ca ??
+		(caPath ? readIfExists(caPath) : undefined) ??
+		(url.startsWith("https://")
+			? readIfExists(path.join(configDir(), "cert.pem"))
+			: undefined);
+	return { url, token, ca, fetch: await makeFetch(ca) };
+};
+
+/**
+ * A fetch that PINS `ca` — the host's self-signed identity cert — on this runtime.
+ *
+ * The pin is chain verification against exactly that certificate (nothing else can pass),
+ * with the HOSTNAME check waived: the host identity cert is deliberately CN-only/no-SAN
+ * (native clients pin its fingerprint; see `web/nitro-entry/bun-https.mjs` for the same
+ * finding), so standard SAN matching would always fail — and it adds nothing when the chain
+ * already admits only the one pinned cert.
+ */
+const makeFetch = async (ca: string | undefined): Promise<typeof fetch> => {
+	if (!ca) return fetch;
+	const skipHostname = { checkServerIdentity: () => undefined };
+	// Bun: fetch takes node-compatible `tls` options.
+	if (typeof (globalThis as Record<string, unknown>).Bun !== "undefined") {
+		return ((input: Parameters<typeof fetch>[0], init?: RequestInit) =>
+			fetch(input, {
+				...init,
+				tls: { ca, ...skipHostname },
+			} as RequestInit)) as typeof fetch;
+	}
+	// Node: global fetch is undici — a per-request dispatcher carries the pin.
+	try {
+		// Optional dependency — declared in package.json optionalDependencies; absent on
+		// runtimes that don't need it (the catch below falls back).
+		const { Agent } = (await import("undici" as string)) as {
+			Agent: new (opts: unknown) => unknown;
+		};
+		const dispatcher = new Agent({ connect: { ca, ...skipHostname } });
+		return ((input: Parameters<typeof fetch>[0], init?: RequestInit) =>
+			fetch(input, { ...init, dispatcher } as RequestInit)) as typeof fetch;
+	} catch {
+		// Unknown runtime: plain fetch (system trust) — PUNKTFUNK_MGMT_CA via the runtime's
+		// own CA mechanism (e.g. NODE_EXTRA_CA_CERTS / --cert) is the documented fallback.
+		return fetch;
+	}
+};