spur-board 0.7.0 → 0.8.1

package/dist/cli.mjs

@@ -1,6 +1,6 @@
-import { B as SLACK_BOT_SCOPES, R as configSchema, s as OPERATIONS, z as requiredSecretKeys } from "./src-BFgTh55w.mjs";
-import { a as renderCliError, i as errorExitCode, n as requestTokenEnrollment, o as escapeTerminalControls, r as CliError, t as requestOperation } from "./client-Ln76BdDz.mjs";
-import { i as resolveDaemonAddress, n as loadClientConfig, r as loadEnrollmentConfig, t as configFile } from "./config-B_6fA4Au.mjs";
+import { B as requiredSecretKeys, V as SLACK_BOT_SCOPES, j as ERRORS, s as OPERATIONS, z as configSchema } from "./src-g7u1onIP.mjs";
+import { a as errorExitCode, i as CliError, n as requestOperation, o as renderCliError, r as requestTokenEnrollment, s as escapeTerminalControls } from "./client-D4cveOHQ.mjs";
+import { a as memoryVerdictCache, c as loadEnrollmentConfig, i as fileVerdictCache, l as resolveDaemonAddress, n as cliPackageVersion, o as configFile, s as loadClientConfig, t as checkCatalog } from "./config-B1fVOLzp.mjs";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { chmodSync, closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir, hostname, userInfo } from "node:os";
@@ -1082,8 +1082,25 @@ function createProgram(options = {}) {
 			const config = options.clientConfig ?? loadClientConfig(env);
 			const key = op.kind === "mutation" ? keyOption || randomUUID() : void 0;
 			if (key) io.stderr(`key: ${escapeTerminalControls(key)}\n`);
+			let instance;
+			let outcome;
 			try {
-				const result = await (options.sendOperation ?? requestOperation)(op, input, key, config);
+				outcome = { value: await (options.sendOperation ?? requestOperation)(op, input, key, config, (seen) => {
+					instance = seen;
+				}) };
+			} catch (error) {
+				outcome = { error };
+			}
+			const reportedMismatch = "error" in outcome && outcome.error instanceof CliError && outcome.error.code === "version_mismatch";
+			if (instance !== void 0 && !reportedMismatch) {
+				const cliVersion = cliPackageVersion();
+				const cache = cliVersion === void 0 ? memoryVerdictCache() : fileVerdictCache(join(dirname(configFile(env, options.home ?? homedir())), "version-check.json"), cliVersion);
+				const verdict = await checkCatalog(config, instance, cache);
+				if (verdict !== void 0 && !verdict.matches) io.stderr(`warning: the daemon catalog ${verdict.serverVersion.slice(0, 12)} differs from this CLI's ${verdict.clientVersion.slice(0, 12)}. ${ERRORS.version_mismatch.hint}\n`);
+			}
+			try {
+				if ("error" in outcome) throw outcome.error;
+				const result = outcome.value;
 				io.stdout(`${json || !io.isTTY ? JSON.stringify(result) : formatHuman(result)}\n`);
 			} catch (error) {
 				if (error instanceof CliError) {

package/dist/{client-Ln76BdDz.mjs → client-D4cveOHQ.mjs}

@@ -1,4 +1,4 @@
-import { M as errorContextSchema, N as errorEnvelopeSchema, P as successEnvelopeSchema, j as ERRORS, l as renderJsonError } from "./src-BFgTh55w.mjs";
+import { M as errorContextSchema, N as errorEnvelopeSchema, P as successEnvelopeSchema, j as ERRORS, l as renderJsonError } from "./src-g7u1onIP.mjs";
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import { request } from "node:http";
@@ -84,9 +84,15 @@ function decodeResponse(output, response, raw) {
 	}
 	throw problemError(response.statusCode ?? 0, response.headers["content-type"], body);
 }
-async function post(path, body, config, output, anonymous) {
+const instanceHeader = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** The daemon instance a response came from, when it sends a well-formed one. */
+function responseInstance(response) {
+	const value = response.headers["x-board-instance"];
+	return typeof value === "string" && instanceHeader.test(value) ? value : void 0;
+}
+function send({ method, path, body, config, anonymous, decode, observe }) {
 	const target = new URL(path, config.address);
-	const payload = JSON.stringify(body);
+	const payload = method === "POST" ? JSON.stringify(body) : void 0;
 	const transport = target.protocol === "https:" ? request$1 : request;
 	return new Promise((resolve, reject) => {
 		let connected = false;
@@ -100,15 +106,19 @@ async function post(path, body, config, output, anonymous) {
 			else resolve(result.value);
 		};
 		const req = transport(target, {
-			method: "POST",
+			method,
 			agent: false,
 			headers: {
-				"content-type": "application/json",
 				accept: "application/json, application/problem+json",
-				"content-length": Buffer.byteLength(payload),
+				...payload === void 0 ? {} : {
+					"content-type": "application/json",
+					"content-length": Buffer.byteLength(payload)
+				},
 				...anonymous ? {} : config.session ? { "x-board-session": config.session } : { authorization: `Bearer ${config.token ?? ""}` }
 			}
 		}, (response) => {
+			const instance = responseInstance(response);
+			if (instance !== void 0) observe?.(instance);
 			const chunks = [];
 			response.on("data", (chunk) => {
 				chunks.push(chunk);
@@ -118,7 +128,7 @@ async function post(path, body, config, output, anonymous) {
 			});
 			response.once("end", () => {
 				try {
-					settle({ value: decodeResponse(output, response, Buffer.concat(chunks).toString()) });
+					settle({ value: decode(response, Buffer.concat(chunks).toString()) });
 				} catch (error) {
 					settle({ error: error instanceof CliError ? error : new CliError("outcome_unknown") });
 				}
@@ -142,12 +152,48 @@ async function post(path, body, config, output, anonymous) {
 	});
 }
 /** Shared daemon HTTP client. The CLI owns output; this module owns transport and wire parsing. */
-async function requestOperation(op, input, key, config) {
+async function requestOperation(op, input, key, config, observe) {
 	if (!config.session && !config.token) throw new CliError("config");
-	return post(`/v1/ops/${encodeURIComponent(op.id)}`, {
-		input,
-		...key ? { key } : {}
-	}, config, op.output, false);
+	return send({
+		method: "POST",
+		path: `/v1/ops/${encodeURIComponent(op.id)}`,
+		body: {
+			input,
+			...key ? { key } : {}
+		},
+		config,
+		anonymous: false,
+		decode: (response, raw) => decodeResponse(op.output, response, raw),
+		observe
+	});
+}
+const schemaVersion = z.looseObject({ version: z.string().regex(/^[0-9a-f]{64}$/) });
+/**
+* The daemon's catalog version and instance. `/v1/schema` answers with the bare snapshot, not a
+* success envelope.
+*/
+function fetchCatalogVersion(config) {
+	return send({
+		method: "GET",
+		path: "/v1/schema",
+		config,
+		anonymous: true,
+		decode: (response, raw) => {
+			let body;
+			try {
+				body = JSON.parse(raw);
+			} catch {
+				throw new CliError("outcome_unknown");
+			}
+			if (response.statusCode !== 200) throw problemError(response.statusCode ?? 0, response.headers["content-type"], body);
+			const parsed = schemaVersion.safeParse(body);
+			if (!parsed.success) throw new CliError("outcome_unknown");
+			return {
+				version: parsed.data.version,
+				instance: responseInstance(response)
+			};
+		}
+	});
 }
 const enrollmentOutput = z.strictObject({
 	name: z.string(),
@@ -156,7 +202,14 @@ const enrollmentOutput = z.strictObject({
 });
 /** Bootstrap sends a hash and no authorization header. */
 function requestTokenEnrollment(input, config) {
-	return post("/v1/tokens/requests", input, config, enrollmentOutput, true);
+	return send({
+		method: "POST",
+		path: "/v1/tokens/requests",
+		body: input,
+		config,
+		anonymous: true,
+		decode: (response, raw) => decodeResponse(enrollmentOutput, response, raw)
+	});
 }
 //#endregion
-export { renderCliError as a, errorExitCode as i, requestTokenEnrollment as n, escapeTerminalControls as o, CliError as r, requestOperation as t };
+export { errorExitCode as a, CliError as i, requestOperation as n, renderCliError as o, requestTokenEnrollment as r, escapeTerminalControls as s, fetchCatalogVersion as t };

package/dist/client.mjs

@@ -1,2 +1,2 @@
-import { n as requestTokenEnrollment, t as requestOperation } from "./client-Ln76BdDz.mjs";
-export { requestOperation, requestTokenEnrollment };
+import { n as requestOperation, r as requestTokenEnrollment, t as fetchCatalogVersion } from "./client-D4cveOHQ.mjs";
+export { fetchCatalogVersion, requestOperation, requestTokenEnrollment };

package/dist/config-B1fVOLzp.mjs

@@ -0,0 +1,229 @@
+import { a as buildCatalogSnapshot, s as OPERATIONS, z as configSchema } from "./src-g7u1onIP.mjs";
+import { i as CliError, t as fetchCatalogVersion } from "./client-D4cveOHQ.mjs";
+import { randomUUID } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { z } from "zod";
+import YAML from "yaml";
+//#region src/config.ts
+const CONNECT_TIMEOUT_MS = 2e3;
+const RESPONSE_TIMEOUT_MS = 3e4;
+function configFile(env, home) {
+	const boardHome = env["BOARD_HOME"];
+	if (boardHome) return join(resolve(boardHome), "config.yaml");
+	const xdg = env["XDG_CONFIG_HOME"];
+	return join(xdg && isAbsolute(xdg) ? xdg : join(home, ".config"), "spur-board", "config.yaml");
+}
+function resolveDaemonAddress(env = process.env, home = homedir(), configuredPort) {
+	const rawAddress = env["BOARD_DAEMON_URL"];
+	if (rawAddress === void 0) {
+		let port = configuredPort ?? 4311;
+		if (configuredPort === void 0) try {
+			const parsed = YAML.parseDocument(readFileSync(configFile(env, home), "utf8"));
+			if (parsed.errors.length === 0) {
+				const config = configSchema.safeParse(parsed.toJS());
+				if (config.success) port = config.data.http.port;
+			}
+		} catch {}
+		if (port === 0) throw new CliError("config", void 0, void 0, "http.port: 0 assigns a runtime port that clients cannot discover. Set BOARD_DAEMON_URL to the daemon listening address.");
+		return new URL(`http://127.0.0.1:${String(port)}`);
+	}
+	let address;
+	try {
+		address = new URL(rawAddress);
+	} catch {
+		throw new CliError("config", { environmentVariable: "BOARD_DAEMON_URL" });
+	}
+	if (!["http:", "https:"].includes(address.protocol) || address.username || address.password) throw new CliError("config", { environmentVariable: "BOARD_DAEMON_URL" });
+	return address;
+}
+function tokenInFolder(folder, warn) {
+	const directory = join(folder, ".spur-board");
+	const file = join(directory, "token");
+	try {
+		const owner = process.getuid?.();
+		const directoryInfo = lstatSync(directory);
+		if (!directoryInfo.isDirectory() || directoryInfo.uid !== owner || (directoryInfo.mode & 63) !== 0) throw new Error("unsafe token directory");
+		const descriptor = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+		let value;
+		try {
+			const fileInfo = fstatSync(descriptor);
+			if (!fileInfo.isFile() || fileInfo.uid !== owner || (fileInfo.mode & 63) !== 0) throw new Error("unsafe token file");
+			value = readFileSync(descriptor, "utf8").trimEnd();
+		} finally {
+			closeSync(descriptor);
+		}
+		if (value === "") throw new Error("empty token file");
+		return value;
+	} catch (error) {
+		if (error !== null && typeof error === "object" && "code" in error && error.code === "ENOENT") return;
+		warn("Ignoring an unsafe .spur-board/token candidate.\n");
+		return;
+	}
+}
+function findTokenFile(cwd, home, warn = (message) => {
+	process.stderr.write(message);
+}) {
+	const current = realpathSync(cwd);
+	const boundary = realpathSync(home);
+	if (current === boundary) return void 0;
+	const toCurrent = relative(boundary, current);
+	const outsideHome = toCurrent === ".." || toCurrent.startsWith(`..${sep}`) || isAbsolute(toCurrent);
+	let folder = current;
+	while (folder !== boundary) {
+		if (outsideHome) {
+			const info = statSync(folder);
+			if (info.uid !== process.getuid?.() || (info.mode & 2) !== 0) break;
+		}
+		const token = tokenInFolder(folder, warn);
+		if (token !== void 0) return token;
+		const parent = dirname(folder);
+		if (parent === folder) break;
+		folder = parent;
+	}
+}
+function loadClientConfig(env = process.env, paths = {
+	cwd: process.cwd(),
+	home: homedir()
+}) {
+	const address = resolveDaemonAddress(env, paths.home);
+	const session = env["SPUR_SESSION"] || void 0;
+	const token = session ? void 0 : env["BOARD_TOKEN"] === void 0 ? findTokenFile(paths.cwd, paths.home) : env["BOARD_TOKEN"];
+	if (!session && !token) throw new CliError("config", { environmentVariable: "BOARD_TOKEN" });
+	return {
+		address,
+		session,
+		token,
+		connectTimeoutMs: CONNECT_TIMEOUT_MS,
+		responseTimeoutMs: RESPONSE_TIMEOUT_MS
+	};
+}
+/** Enrollment sends only a hash and works before any operator credential exists. */
+function loadEnrollmentConfig(env = process.env) {
+	return {
+		address: resolveDaemonAddress(env),
+		session: void 0,
+		token: void 0,
+		connectTimeoutMs: CONNECT_TIMEOUT_MS,
+		responseTimeoutMs: RESPONSE_TIMEOUT_MS
+	};
+}
+//#endregion
+//#region src/version.ts
+let clientVersion;
+/** The catalog version this client was built with; the snapshot is built once per process. */
+function clientCatalogVersion() {
+	if (clientVersion === void 0) {
+		const pending = buildCatalogSnapshot(OPERATIONS).then((snapshot) => snapshot.version);
+		clientVersion = pending;
+		pending.catch(() => {
+			if (clientVersion === pending) clientVersion = void 0;
+		});
+	}
+	return clientVersion;
+}
+/** The CLI package version, or `undefined` when its manifest cannot be read. */
+function cliPackageVersion() {
+	try {
+		const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"))?.version;
+		return typeof version === "string" && version ? version : void 0;
+	} catch {
+		return;
+	}
+}
+/** Compares the client catalog with the daemon's; rejects when the daemon cannot answer. */
+async function compareCatalogs(config) {
+	const [clientVersion, served] = await Promise.all([clientCatalogVersion(), fetchCatalogVersion(config)]);
+	return {
+		clientVersion,
+		serverVersion: served.version,
+		matches: clientVersion === served.version,
+		instance: served.instance
+	};
+}
+/**
+* Compares the client catalog with the daemon instance's catalog once per cache entry. Any
+* failure returns `undefined`, so the caller carries on unchanged.
+*/
+function checkCatalog(config, instance, cache) {
+	return cache.check(config.address, instance, () => compareCatalogs(config).catch(() => void 0));
+}
+/** In-process cache that shares an in-flight check between overlapping callers. */
+function memoryVerdictCache() {
+	const entries = /* @__PURE__ */ new Map();
+	const keyOf = (address, instance) => `${address.href} ${instance}`;
+	return {
+		check(address, instance, run) {
+			const key = keyOf(address, instance);
+			const held = entries.get(key);
+			if (held !== void 0) return held;
+			const pending = run();
+			entries.set(key, pending);
+			pending.then((verdict) => {
+				if (verdict === void 0 && entries.get(key) === pending) entries.delete(key);
+			});
+			return pending;
+		},
+		remember(address, instance, verdict) {
+			entries.set(keyOf(address, instance), Promise.resolve(verdict));
+		}
+	};
+}
+const fileEntrySchema = z.object({
+	cliPackageVersion: z.string(),
+	address: z.string(),
+	instance: z.string(),
+	clientVersion: z.string(),
+	serverVersion: z.string()
+});
+const fileSchema = z.object({ entries: z.array(fileEntrySchema) });
+function readEntries(path) {
+	try {
+		const parsed = fileSchema.safeParse(JSON.parse(readFileSync(path, "utf8")));
+		return parsed.success ? parsed.data.entries : [];
+	} catch {
+		return [];
+	}
+}
+function writeEntries(path, entries) {
+	const temporary = `${path}.${randomUUID()}.tmp`;
+	try {
+		mkdirSync(dirname(path), {
+			recursive: true,
+			mode: 448
+		});
+		writeFileSync(temporary, `${JSON.stringify({ entries })}\n`, { mode: 384 });
+		renameSync(temporary, path);
+	} catch {
+		try {
+			unlinkSync(temporary);
+		} catch {}
+	}
+}
+/** Verdicts kept across CLI invocations, keyed by CLI package version, address and instance. */
+function fileVerdictCache(path, cliVersion) {
+	return { async check(address, instance, run) {
+		const matchesKey = (entry) => entry.cliPackageVersion === cliVersion && entry.address === address.href && entry.instance === instance;
+		const held = readEntries(path).find(matchesKey);
+		if (held !== void 0) return {
+			clientVersion: held.clientVersion,
+			serverVersion: held.serverVersion,
+			matches: held.clientVersion === held.serverVersion
+		};
+		const verdict = await run();
+		if (verdict !== void 0) {
+			const entry = {
+				cliPackageVersion: cliVersion,
+				address: address.href,
+				instance,
+				clientVersion: verdict.clientVersion,
+				serverVersion: verdict.serverVersion
+			};
+			writeEntries(path, [...readEntries(path).filter((item) => !matchesKey(item)), entry].slice(-16));
+		}
+		return verdict;
+	} };
+}
+//#endregion
+export { memoryVerdictCache as a, loadEnrollmentConfig as c, fileVerdictCache as i, resolveDaemonAddress as l, cliPackageVersion as n, configFile as o, compareCatalogs as r, loadClientConfig as s, checkCatalog as t };