granola-toolkit 0.29.0 → 0.30.0

package/README.md

@@ -208,6 +208,7 @@ The machine-readable `export` command includes:
 The initial server API includes:
 
 - `GET /health`
+- `GET /server/info`
 - `POST /auth/unlock` for password-protected servers
 - `POST /auth/lock` to clear the browser/API unlock cookie
 - `GET /auth/status`
@@ -272,6 +273,16 @@ Use it when you want:
 
 The attach flow uses the existing local HTTP API plus `GET /events` for live state updates.
 
+### Runtime Boundaries
+
+The toolkit now keeps its local persistence and transport contracts explicit:
+
+- one shared local data directory for export jobs, meeting index data, and any file-backed session state
+- one versioned local HTTP transport contract, exposed by `GET /server/info`
+- one remote client handshake that validates the transport protocol before attaching
+
+That keeps the current single-package repo simple, while making a future split into separate server/client packages or remote-hosted clients much less invasive.
+
 ### TUI
 
 `tui` starts a full-screen terminal workspace on the shared app core, without requiring the local server or browser client. Use `attach` when you want the same workspace against an existing shared server instance instead.

package/dist/cli.js

@@ -9,6 +9,60 @@ import { NodeHtmlMarkdown } from "node-html-markdown";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { createServer } from "node:http";
+//#region src/transport.ts
+const granolaTransportPaths = {
+	authLock: "/auth/lock",
+	authLogin: "/auth/login",
+	authLogout: "/auth/logout",
+	authMode: "/auth/mode",
+	authRefresh: "/auth/refresh",
+	authStatus: "/auth/status",
+	authUnlock: "/auth/unlock",
+	events: "/events",
+	exportJobs: "/exports/jobs",
+	exportNotes: "/exports/notes",
+	exportTranscripts: "/exports/transcripts",
+	health: "/health",
+	meetingResolve: "/meetings/resolve",
+	meetings: "/meetings",
+	root: "/",
+	serverInfo: "/server/info",
+	state: "/state"
+};
+function appendSearchParams(path, params) {
+	const url = new URL(path, "http://localhost");
+	for (const [key, value] of Object.entries(params)) {
+		if (value === void 0 || value === false || value === "") continue;
+		url.searchParams.set(key, String(value));
+	}
+	return `${url.pathname}${url.search}`;
+}
+function granolaMeetingPath(id) {
+	return `${granolaTransportPaths.meetings}/${encodeURIComponent(id)}`;
+}
+function granolaMeetingResolvePath(query, options = {}) {
+	return appendSearchParams(granolaTransportPaths.meetingResolve, {
+		includeTranscript: options.includeTranscript ? "true" : void 0,
+		q: query
+	});
+}
+function granolaMeetingsPath(options = {}) {
+	return appendSearchParams(granolaTransportPaths.meetings, {
+		limit: options.limit,
+		refresh: options.forceRefresh ? "true" : void 0,
+		search: options.search,
+		sort: options.sort,
+		updatedFrom: options.updatedFrom,
+		updatedTo: options.updatedTo
+	});
+}
+function granolaExportJobsPath(options = {}) {
+	return appendSearchParams(granolaTransportPaths.exportJobs, { limit: options.limit });
+}
+function granolaExportJobRerunPath(id) {
+	return `${granolaTransportPaths.exportJobs}/${encodeURIComponent(id)}/rerun`;
+}
+//#endregion
 //#region src/server/client.ts
 function cloneValue(value) {
 	return structuredClone(value);
@@ -24,14 +78,6 @@ function normaliseServerUrl(serverUrl) {
 	parsed.hash = "";
 	return parsed;
 }
-function appendSearchParams(path, params) {
-	const url = new URL(path, "http://localhost");
-	for (const [key, value] of Object.entries(params)) {
-		if (value === void 0 || value === false || value === "") continue;
-		url.searchParams.set(key, String(value));
-	}
-	return `${url.pathname}${url.search}`;
-}
 function mergeHeaders(...values) {
 	const headers = new Headers();
 	for (const value of values) {
@@ -66,22 +112,32 @@ var GranolaServerClient = class GranolaServerClient {
 	#fetchImpl;
 	#password;
 	#reconnectDelayMs;
+	info;
 	#streamAbortController;
-	constructor(url, initialState, options = {}) {
+	constructor(info, url, initialState, options = {}) {
 		this.url = url;
 		this.#fetchImpl = options.fetchImpl ?? fetch;
+		this.info = cloneValue(info);
 		this.#password = options.password?.trim() || void 0;
 		this.#reconnectDelayMs = options.reconnectDelayMs ?? 1e3;
 		this.#state = cloneValue(initialState);
 	}
 	static async connect(serverUrl, options = {}) {
 		const url = normaliseServerUrl(serverUrl);
-		const response = await (options.fetchImpl ?? fetch)(new URL("/state", url), { headers: mergeHeaders({
+		const fetchImpl = options.fetchImpl ?? fetch;
+		const infoResponse = await fetchImpl(new URL(granolaTransportPaths.serverInfo, url), { headers: mergeHeaders({
+			...options.password?.trim() ? { "x-granola-password": options.password.trim() } : {},
+			accept: "application/json"
+		}) });
+		if (!infoResponse.ok) throw await responseError(infoResponse);
+		const info = await infoResponse.json();
+		if (info.protocolVersion !== 1) throw new Error(`unsupported Granola transport protocol: expected 1, got ${info.protocolVersion}`);
+		const response = await fetchImpl(new URL(granolaTransportPaths.state, url), { headers: mergeHeaders({
 			...options.password?.trim() ? { "x-granola-password": options.password.trim() } : {},
 			accept: "application/json"
 		}) });
 		if (!response.ok) throw await responseError(response);
-		const client = new GranolaServerClient(url, await response.json(), options);
+		const client = new GranolaServerClient(info, url, await response.json(), options);
 		client.startEvents();
 		return client;
 	}
@@ -103,66 +159,56 @@ var GranolaServerClient = class GranolaServerClient {
 		};
 	}
 	async inspectAuth() {
-		return await this.requestJson("/auth/status");
+		return await this.requestJson(granolaTransportPaths.authStatus);
 	}
 	async loginAuth(options = {}) {
-		return await this.requestJson("/auth/login", {
+		return await this.requestJson(granolaTransportPaths.authLogin, {
 			body: JSON.stringify(options),
 			headers: { "content-type": "application/json" },
 			method: "POST"
 		});
 	}
 	async logoutAuth() {
-		return await this.requestJson("/auth/logout", { method: "POST" });
+		return await this.requestJson(granolaTransportPaths.authLogout, { method: "POST" });
 	}
 	async refreshAuth() {
-		return await this.requestJson("/auth/refresh", { method: "POST" });
+		return await this.requestJson(granolaTransportPaths.authRefresh, { method: "POST" });
 	}
 	async switchAuthMode(mode) {
-		return await this.requestJson("/auth/mode", {
+		return await this.requestJson(granolaTransportPaths.authMode, {
 			body: JSON.stringify({ mode }),
 			headers: { "content-type": "application/json" },
 			method: "POST"
 		});
 	}
 	async listMeetings(options = {}) {
-		return await this.requestJson(appendSearchParams("/meetings", {
-			limit: options.limit,
-			refresh: options.forceRefresh ? "true" : void 0,
-			search: options.search,
-			sort: options.sort,
-			updatedFrom: options.updatedFrom,
-			updatedTo: options.updatedTo
-		}));
+		return await this.requestJson(granolaMeetingsPath(options));
 	}
 	async getMeeting(id, options = {}) {
-		return await this.requestJson(appendSearchParams(`/meetings/${encodeURIComponent(id)}`, { includeTranscript: options.requireCache ? "true" : void 0 }));
+		return await this.requestJson(`${granolaMeetingPath(id)}${options.requireCache ? "?includeTranscript=true" : ""}`);
 	}
 	async findMeeting(query, options = {}) {
-		return await this.requestJson(appendSearchParams("/meetings/resolve", {
-			includeTranscript: options.requireCache ? "true" : void 0,
-			q: query
-		}));
+		return await this.requestJson(granolaMeetingResolvePath(query, { includeTranscript: options.requireCache }));
 	}
 	async listExportJobs(options = {}) {
-		return await this.requestJson(appendSearchParams("/exports/jobs", { limit: options.limit }));
+		return await this.requestJson(granolaExportJobsPath(options));
 	}
 	async exportNotes(format = "markdown") {
-		return await this.requestJson("/exports/notes", {
+		return await this.requestJson(granolaTransportPaths.exportNotes, {
 			body: JSON.stringify({ format }),
 			headers: { "content-type": "application/json" },
 			method: "POST"
 		});
 	}
 	async exportTranscripts(format = "text") {
-		return await this.requestJson("/exports/transcripts", {
+		return await this.requestJson(granolaTransportPaths.exportTranscripts, {
 			body: JSON.stringify({ format }),
 			headers: { "content-type": "application/json" },
 			method: "POST"
 		});
 	}
 	async rerunExportJob(id) {
-		return await this.requestJson(`/exports/jobs/${encodeURIComponent(id)}/rerun`, { method: "POST" });
+		return await this.requestJson(granolaExportJobRerunPath(id), { method: "POST" });
 	}
 	async request(path, init = {}) {
 		const response = await this.#fetchImpl(new URL(path, this.url), {
@@ -192,7 +238,7 @@ var GranolaServerClient = class GranolaServerClient {
 			const controller = new AbortController();
 			this.#streamAbortController = controller;
 			try {
-				const response = await this.request("/events", {
+				const response = await this.request(granolaTransportPaths.events, {
 					headers: { accept: "text/event-stream" },
 					signal: controller.signal
 				});
@@ -2131,6 +2177,22 @@ function parseCacheContents(contents) {
 	};
 }
 //#endregion
+//#region src/persistence/layout.ts
+function defaultGranolaToolkitDataDirectory(targetPlatform = platform(), homeDirectory = homedir()) {
+	return targetPlatform === "darwin" ? join(homeDirectory, "Library", "Application Support", "granola-toolkit") : join(homeDirectory, ".config", "granola-toolkit");
+}
+function defaultGranolaToolkitPersistenceLayout(options = {}) {
+	const targetPlatform = options.platform ?? platform();
+	const dataDirectory = defaultGranolaToolkitDataDirectory(targetPlatform, options.homeDirectory ?? homedir());
+	return {
+		dataDirectory,
+		exportJobsFile: join(dataDirectory, "export-jobs.json"),
+		meetingIndexFile: join(dataDirectory, "meeting-index.json"),
+		sessionFile: join(dataDirectory, "session.json"),
+		sessionStoreKind: targetPlatform === "darwin" ? "keychain" : "file"
+	};
+}
+//#endregion
 //#region src/client/auth.ts
 const execFileAsync$1 = promisify(execFile);
 const DEFAULT_CLIENT_ID = "client_GranolaMac";
@@ -2351,11 +2413,10 @@ async function refreshGranolaSession(session, fetchImpl = fetch) {
 	};
 }
 function defaultSessionFilePath() {
-	const home = homedir();
-	return platform() === "darwin" ? join(home, "Library", "Application Support", "granola-toolkit", "session.json") : join(home, ".config", "granola-toolkit", "session.json");
+	return defaultGranolaToolkitPersistenceLayout().sessionFile;
 }
 function createDefaultSessionStore() {
-	return platform() === "darwin" ? new KeychainSessionStore() : new FileSessionStore();
+	return defaultGranolaToolkitPersistenceLayout().sessionStoreKind === "keychain" ? new KeychainSessionStore() : new FileSessionStore();
 }
 //#endregion
 //#region src/client/default-auth.ts
@@ -2736,8 +2797,7 @@ function createExportJobId(kind) {
 	return `${kind}-${randomUUID()}`;
 }
 function defaultExportJobsFilePath() {
-	const home = homedir();
-	return platform() === "darwin" ? join(home, "Library", "Application Support", "granola-toolkit", "export-jobs.json") : join(home, ".config", "granola-toolkit", "export-jobs.json");
+	return defaultGranolaToolkitPersistenceLayout().exportJobsFile;
 }
 var FileExportJobStore = class {
 	constructor(filePath = defaultExportJobsFilePath()) {
@@ -2801,8 +2861,7 @@ var FileMeetingIndexStore = class {
 	}
 };
 function defaultMeetingIndexFilePath() {
-	const home = homedir();
-	return platform() === "darwin" ? join(home, "Library", "Application Support", "granola-toolkit", "meeting-index.json") : join(home, ".config", "granola-toolkit", "meeting-index.json");
+	return defaultGranolaToolkitPersistenceLayout().meetingIndexFile;
 }
 function createDefaultMeetingIndexStore() {
 	return new FileMeetingIndexStore();
@@ -5355,7 +5414,7 @@ function isPasswordAuthenticated(request, password) {
 	return parseCookies(request)[PASSWORD_COOKIE_NAME] === password;
 }
 function publicRoute(path, enableWebClient) {
-	return path === "/health" || path === "/auth/unlock" || enableWebClient && path === "/";
+	return path === granolaTransportPaths.health || path === granolaTransportPaths.serverInfo || path === granolaTransportPaths.authUnlock || enableWebClient && path === granolaTransportPaths.root;
 }
 async function startGranolaServer(app, options = {}) {
 	const enableWebClient = options.enableWebClient ?? false;
@@ -5365,6 +5424,24 @@ async function startGranolaServer(app, options = {}) {
 		password: options.security?.password?.trim() || void 0,
 		trustedOrigins: (options.security?.trustedOrigins ?? []).map((origin) => origin.trim()).filter(Boolean)
 	};
+	const serverInfo = {
+		capabilities: {
+			attach: true,
+			auth: true,
+			events: true,
+			exports: true,
+			meetingOpen: true,
+			webClient: enableWebClient
+		},
+		persistence: {
+			exportJobs: true,
+			meetingIndex: true,
+			sessionStore: defaultGranolaToolkitPersistenceLayout().sessionStoreKind
+		},
+		product: "granola-toolkit",
+		protocolVersion: 1,
+		transport: "local-http"
+	};
 	const server = createServer(async (request, response) => {
 		const method = request.method ?? "GET";
 		const url = new URL(request.url ?? "/", `http://${hostname}`);
@@ -5392,11 +5469,11 @@ async function startGranolaServer(app, options = {}) {
 				sendNoContent(response, 204, originHeaders);
 				return;
 			}
-			if (method === "GET" && path === "/" && enableWebClient) {
+			if (method === "GET" && path === granolaTransportPaths.root && enableWebClient) {
 				sendHtml(response, renderGranolaWebPage({ serverPasswordRequired: Boolean(security.password) }), 200, originHeaders);
 				return;
 			}
-			if (method === "GET" && path === "/health") {
+			if (method === "GET" && path === granolaTransportPaths.health) {
 				sendJson(response, {
 					ok: true,
 					service: "granola-toolkit",
@@ -5404,7 +5481,11 @@ async function startGranolaServer(app, options = {}) {
 				}, { headers: originHeaders });
 				return;
 			}
-			if (method === "POST" && path === "/auth/unlock") {
+			if (method === "GET" && path === granolaTransportPaths.serverInfo) {
+				sendJson(response, serverInfo, { headers: originHeaders });
+				return;
+			}
+			if (method === "POST" && path === granolaTransportPaths.authUnlock) {
 				if (!security.password) {
 					sendJson(response, {
 						ok: true,
@@ -5443,22 +5524,22 @@ async function startGranolaServer(app, options = {}) {
 				});
 				return;
 			}
-			if (method === "GET" && path === "/state") {
+			if (method === "GET" && path === granolaTransportPaths.state) {
 				sendJson(response, app.getState(), { headers: originHeaders });
 				return;
 			}
-			if (method === "GET" && path === "/auth/status") {
+			if (method === "GET" && path === granolaTransportPaths.authStatus) {
 				sendJson(response, await app.inspectAuth(), { headers: originHeaders });
 				return;
 			}
-			if (method === "POST" && path === "/auth/lock") {
+			if (method === "POST" && path === granolaTransportPaths.authLock) {
 				sendJson(response, { ok: true }, { headers: {
 					...originHeaders,
 					"set-cookie": clearPasswordCookieHeader()
 				} });
 				return;
 			}
-			if (method === "GET" && path === "/events") {
+			if (method === "GET" && path === granolaTransportPaths.events) {
 				response.writeHead(200, {
 					"cache-control": "no-cache, no-transform",
 					connection: "keep-alive",
@@ -5479,7 +5560,7 @@ async function startGranolaServer(app, options = {}) {
 				});
 				return;
 			}
-			if (method === "GET" && path === "/meetings") {
+			if (method === "GET" && path === granolaTransportPaths.meetings) {
 				const limit = parseInteger(url.searchParams.get("limit"));
 				const refresh = url.searchParams.get("refresh") === "true";
 				const search = url.searchParams.get("search")?.trim() || void 0;
@@ -5505,38 +5586,38 @@ async function startGranolaServer(app, options = {}) {
 				}, { headers: originHeaders });
 				return;
 			}
-			if (method === "GET" && path === "/meetings/resolve") {
+			if (method === "GET" && path === granolaTransportPaths.meetingResolve) {
 				const query = url.searchParams.get("q")?.trim();
 				if (!query) throw new Error("meeting query is required");
 				sendJson(response, await app.findMeeting(query, { requireCache: url.searchParams.get("includeTranscript") === "true" }), { headers: originHeaders });
 				return;
 			}
-			if (method === "GET" && path.startsWith("/meetings/")) {
-				const id = decodeURIComponent(path.slice(10));
+			if (method === "GET" && path.startsWith(`${granolaTransportPaths.meetings}/`) && path !== granolaTransportPaths.meetingResolve) {
+				const id = decodeURIComponent(path.slice(`${granolaTransportPaths.meetings}/`.length));
 				if (!id) throw new Error("meeting id is required");
 				sendJson(response, await app.getMeeting(id, { requireCache: url.searchParams.get("includeTranscript") === "true" }), { headers: originHeaders });
 				return;
 			}
-			if (method === "POST" && path === "/auth/login") {
+			if (method === "POST" && path === granolaTransportPaths.authLogin) {
 				const body = await readJsonBody(request);
 				const supabasePath = typeof body.supabasePath === "string" && body.supabasePath.trim() ? body.supabasePath.trim() : void 0;
 				sendJson(response, await app.loginAuth({ supabasePath }), { headers: originHeaders });
 				return;
 			}
-			if (method === "POST" && path === "/auth/logout") {
+			if (method === "POST" && path === granolaTransportPaths.authLogout) {
 				sendJson(response, await app.logoutAuth(), { headers: originHeaders });
 				return;
 			}
-			if (method === "POST" && path === "/auth/refresh") {
+			if (method === "POST" && path === granolaTransportPaths.authRefresh) {
 				sendJson(response, await app.refreshAuth(), { headers: originHeaders });
 				return;
 			}
-			if (method === "POST" && path === "/auth/mode") {
+			if (method === "POST" && path === granolaTransportPaths.authMode) {
 				const body = await readJsonBody(request);
 				sendJson(response, await app.switchAuthMode(parseAuthMode(body.mode)), { headers: originHeaders });
 				return;
 			}
-			if (method === "POST" && path === "/exports/notes") {
+			if (method === "POST" && path === granolaTransportPaths.exportNotes) {
 				const body = await readJsonBody(request);
 				sendJson(response, await app.exportNotes(noteFormatFromBody(body.format)), {
 					headers: originHeaders,
@@ -5544,13 +5625,13 @@ async function startGranolaServer(app, options = {}) {
 				});
 				return;
 			}
-			if (method === "GET" && path === "/exports/jobs") {
+			if (method === "GET" && path === granolaTransportPaths.exportJobs) {
 				const limit = parseInteger(url.searchParams.get("limit"));
 				sendJson(response, await app.listExportJobs({ limit }), { headers: originHeaders });
 				return;
 			}
-			if (method === "POST" && path.startsWith("/exports/jobs/") && path.endsWith("/rerun")) {
-				const id = decodeURIComponent(path.slice(14, -6));
+			if (method === "POST" && path.startsWith(`${granolaTransportPaths.exportJobs}/`) && path.endsWith("/rerun")) {
+				const id = decodeURIComponent(path.slice(`${granolaTransportPaths.exportJobs}/`.length, -6));
 				if (!id) throw new Error("export job id is required");
 				sendJson(response, await app.rerunExportJob(id), {
 					headers: originHeaders,
@@ -5558,7 +5639,7 @@ async function startGranolaServer(app, options = {}) {
 				});
 				return;
 			}
-			if (method === "POST" && path === "/exports/transcripts") {
+			if (method === "POST" && path === granolaTransportPaths.exportTranscripts) {
 				const body = await readJsonBody(request);
 				sendJson(response, await app.exportTranscripts(transcriptFormatFromBody(body.format)), {
 					headers: originHeaders,
@@ -5630,6 +5711,7 @@ function printWebRoutes() {
 	console.log("Routes:");
 	console.log("  GET  /");
 	console.log("  GET  /health");
+	console.log("  GET  /server/info");
 	console.log("  POST /auth/unlock");
 	console.log("  POST /auth/lock");
 	console.log("  GET  /auth/status");
@@ -6042,6 +6124,7 @@ const serveCommand = {
 		if (trustedOrigins.length > 0) console.log(`Trusted origins: ${trustedOrigins.join(", ")}`);
 		console.log("Endpoints:");
 		console.log("  GET  /health");
+		console.log("  GET  /server/info");
 		console.log("  POST /auth/unlock");
 		console.log("  POST /auth/lock");
 		console.log("  GET  /auth/status");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "granola-toolkit",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Toolkit for exporting and working with Granola meetings, notes, and transcripts",
   "keywords": [
     "cli",