granola-toolkit 0.35.0 → 0.37.0

package/README.md

@@ -22,6 +22,7 @@ The published package exposes both `granola` and `granola-toolkit` as executable
 ```bash
 granola auth login
 granola sync
+granola sync --watch
 granola folder list
 granola meeting list --limit 10
 granola notes --folder Team

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { Input, ProcessTerminal, TUI, matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui";
 import { createHash, randomUUID } from "node:crypto";
-import { mkdir, readFile, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, readFile, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { existsSync } from "node:fs";
 import { homedir, platform } from "node:os";
@@ -30,6 +30,7 @@ const granolaTransportPaths = {
 	root: "/",
 	serverInfo: "/server/info",
 	syncRun: "/sync",
+	syncEvents: "/sync/events",
 	state: "/state"
 };
 function appendSearchParams(path, params) {
@@ -181,6 +182,10 @@ var GranolaServerClient = class GranolaServerClient {
 	async inspectSync() {
 		return cloneValue(this.#state.sync);
 	}
+	async listSyncEvents(options = {}) {
+		const path = options.limit ? `${granolaTransportPaths.syncEvents}?limit=${encodeURIComponent(String(options.limit))}` : granolaTransportPaths.syncEvents;
+		return await this.requestJson(path);
+	}
 	async loginAuth(options = {}) {
 		return await this.requestJson(granolaTransportPaths.authLogin, {
 			body: JSON.stringify(options),
@@ -1378,7 +1383,7 @@ function renderGranolaTuiMeetingTab(bundle, tab) {
 	}
 }
 function buildGranolaTuiSummary(state, meetingSource) {
-	return `auth ${state.auth.mode === "stored-session" ? "stored" : "supabase"} | ${state.documents.loaded ? `${state.documents.count} docs` : "docs pending"} | ${state.folders.loaded ? `${state.folders.count} folders` : "folders pending"} | ${state.cache.loaded ? `${state.cache.transcriptCount} transcript sets` : state.cache.configured ? "cache configured" : "cache missing"} | ${state.index.loaded ? `${state.index.meetingCount} indexed` : "index pending"} | list ${meetingSource}`;
+	return `auth ${state.auth.mode === "stored-session" ? "stored" : "supabase"} | ${state.documents.loaded ? `${state.documents.count} docs` : "docs pending"} | ${state.folders.loaded ? `${state.folders.count} folders` : "folders pending"} | ${state.cache.loaded ? `${state.cache.transcriptCount} transcript sets` : state.cache.configured ? "cache configured" : "cache missing"} | ${state.index.loaded ? `${state.index.meetingCount} indexed` : "index pending"} | ${state.sync.running ? "sync running" : state.sync.lastError ? "sync error" : state.sync.lastCompletedAt ? `sync ${state.sync.lastCompletedAt.slice(11, 16)}` : "sync idle"} | list ${meetingSource}`;
 }
 //#endregion
 //#region src/tui/theme.ts
@@ -1849,6 +1854,10 @@ var GranolaTuiWorkspace = class {
 	}
 	async refresh(forceRefresh) {
 		try {
+			if (forceRefresh) {
+				this.setStatus("Syncing…");
+				await this.app.sync();
+			}
 			await this.loadFolders({
 				forceRefresh,
 				setStatus: false
@@ -1858,7 +1867,9 @@ var GranolaTuiWorkspace = class {
 				preferredMeetingId: this.#selectedMeetingId
 			});
 			if (this.#selectedMeetingId) await this.loadMeeting(this.#selectedMeetingId, { ensureMeetingVisible: true });
-		} catch {}
+		} catch (error) {
+			if (error instanceof Error && error.message) this.setStatus(error.message, "error");
+		}
 	}
 	async moveMeetingSelection(delta) {
 		if (this.#meetings.length === 0) return;
@@ -2245,7 +2256,7 @@ var GranolaTuiWorkspace = class {
 		const bodyLines = [];
 		for (let index = 0; index < bodyHeight; index += 1) bodyLines.push(`${padLine(listLines[index] ?? "", listWidth)} | ${padLine(detailLines[index] ?? "", detailWidth)}`);
 		const footerStatus = padLine(toneText(this.#statusTone, this.#statusMessage), width);
-		const footerHints = padLine(granolaTuiTheme.dim("h/l or Tab pane  j/k move  / quick open  a auth  r refresh  1-4 tabs  PgUp/PgDn scroll  q quit"), width);
+		const footerHints = padLine(granolaTuiTheme.dim("h/l or Tab pane  j/k move  / quick open  a auth  r sync  1-4 tabs  PgUp/PgDn scroll  q quit"), width);
 		return [
 			headerTitle,
 			headerSummary,
@@ -2263,7 +2274,7 @@ async function runGranolaTui(app, options = {}) {
 			onExit: () => {
 				workspace.dispose();
 				tui.stop();
-				Promise.resolve(app.close?.()).catch(() => {}).finally(() => {
+				Promise.resolve(options.onClose?.()).then(() => Promise.resolve(app.close?.())).catch(() => {}).finally(() => {
 					resolve(0);
 				});
 			}
@@ -2273,7 +2284,7 @@ async function runGranolaTui(app, options = {}) {
 				await workspace.initialise();
 			} catch (error) {
 				workspace.dispose();
-				await Promise.resolve(app.close?.()).catch(() => {});
+				await Promise.resolve(options.onClose?.()).then(() => Promise.resolve(app.close?.())).catch(() => {});
 				reject(error);
 				return;
 			}
@@ -2382,6 +2393,7 @@ function defaultGranolaToolkitPersistenceLayout(options = {}) {
 		meetingIndexFile: join(dataDirectory, "meeting-index.json"),
 		sessionFile: join(dataDirectory, "session.json"),
 		sessionStoreKind: targetPlatform === "darwin" ? "keychain" : "file",
+		syncEventsFile: join(dataDirectory, "sync-events.jsonl"),
 		syncStateFile: join(dataDirectory, "sync-state.json")
 	};
 }
@@ -3275,14 +3287,17 @@ function cloneSyncSummary(summary) {
 }
 function normaliseSyncState(filePath, file) {
 	return {
+		eventCount: file?.eventCount ?? 0,
+		eventsFile: file?.eventsFile ?? defaultSyncEventsFilePath$1(),
 		filePath,
 		lastChanges: (file?.lastChanges ?? []).slice(0, MAX_STORED_CHANGES).map(cloneSyncChange$1),
-		lastCompletedAt: file?.lastCompletedAt,
-		lastError: file?.lastError,
-		lastFailedAt: file?.lastFailedAt,
-		lastStartedAt: file?.lastStartedAt,
 		running: false,
-		summary: cloneSyncSummary(file?.summary)
+		...file?.lastCompletedAt ? { lastCompletedAt: file.lastCompletedAt } : {},
+		...file?.lastError ? { lastError: file.lastError } : {},
+		...file?.lastFailedAt ? { lastFailedAt: file.lastFailedAt } : {},
+		...file?.lastRunId ? { lastRunId: file.lastRunId } : {},
+		...file?.lastStartedAt ? { lastStartedAt: file.lastStartedAt } : {},
+		...file?.summary ? { summary: cloneSyncSummary(file.summary) } : {}
 	};
 }
 var FileSyncStateStore = class {
@@ -3301,10 +3316,13 @@ var FileSyncStateStore = class {
 	async writeState(state) {
 		await mkdir(dirname(this.filePath), { recursive: true });
 		const payload = {
+			eventCount: state.eventCount,
+			eventsFile: state.eventsFile,
 			lastChanges: state.lastChanges.slice(0, MAX_STORED_CHANGES).map(cloneSyncChange$1),
 			lastCompletedAt: state.lastCompletedAt,
 			lastError: state.lastError,
 			lastFailedAt: state.lastFailedAt,
+			lastRunId: state.lastRunId,
 			lastStartedAt: state.lastStartedAt,
 			summary: cloneSyncSummary(state.summary),
 			version: SYNC_STATE_VERSION
@@ -3318,10 +3336,45 @@ var FileSyncStateStore = class {
 function defaultSyncStateFilePath() {
 	return defaultGranolaToolkitPersistenceLayout().syncStateFile;
 }
+function defaultSyncEventsFilePath$1() {
+	return defaultGranolaToolkitPersistenceLayout().syncEventsFile;
+}
 function createDefaultSyncStateStore() {
 	return new FileSyncStateStore();
 }
 //#endregion
+//#region src/sync-events.ts
+function cloneSyncEvent$1(event) {
+	return { ...event };
+}
+var FileSyncEventStore = class {
+	constructor(filePath = defaultSyncEventsFilePath()) {
+		this.filePath = filePath;
+	}
+	async appendEvents(events) {
+		if (events.length === 0) return;
+		await mkdir(dirname(this.filePath), { recursive: true });
+		const payload = events.map((event) => JSON.stringify(event)).join("\n");
+		await appendFile(this.filePath, `${payload}\n`, {
+			encoding: "utf8",
+			mode: 384
+		});
+	}
+	async readEvents(limit = 50) {
+		try {
+			return (await readFile(this.filePath, "utf8")).split("\n").map((line) => line.trim()).filter(Boolean).map((line) => parseJsonString(line)).filter((event) => Boolean(event)).map(cloneSyncEvent$1).slice(-limit).reverse();
+		} catch {
+			return [];
+		}
+	}
+};
+function defaultSyncEventsFilePath() {
+	return defaultGranolaToolkitPersistenceLayout().syncEventsFile;
+}
+function createDefaultSyncEventStore() {
+	return new FileSyncEventStore();
+}
+//#endregion
 //#region src/sync.ts
 function normaliseMeeting(meeting) {
 	return {
@@ -3419,6 +3472,18 @@ function diffMeetingSummaries(previous, next, folderCount) {
 		}
 	};
 }
+function buildSyncEvents(runId, occurredAt, changes) {
+	return changes.map((change, index) => ({
+		id: `${runId}:${index + 1}`,
+		kind: change.kind === "created" ? "meeting.created" : change.kind === "changed" ? "meeting.changed" : change.kind === "removed" ? "meeting.removed" : "transcript.ready",
+		meetingId: change.meetingId,
+		occurredAt,
+		previousUpdatedAt: change.previousUpdatedAt,
+		runId,
+		title: change.title,
+		updatedAt: change.updatedAt
+	}));
+}
 //#endregion
 //#region src/app/core.ts
 function transcriptCount(cacheData) {
@@ -3449,6 +3514,9 @@ function cloneSyncState(state) {
 		summary: state.summary ? { ...state.summary } : void 0
 	};
 }
+function cloneSyncEvent(event) {
+	return { ...event };
+}
 function cloneMeetingSummary(meeting) {
 	return {
 		...meeting,
@@ -3508,6 +3576,8 @@ function defaultState(config, auth, surface) {
 			meetingCount: 0
 		},
 		sync: {
+			eventCount: 0,
+			eventsFile: defaultSyncEventsFilePath$1(),
 			filePath: defaultSyncStateFilePath(),
 			lastChanges: [],
 			running: false
@@ -3544,6 +3614,8 @@ var GranolaApp = class {
 		this.#state.sync = {
 			...this.#state.sync,
 			...cloneSyncState(deps.syncState ?? {
+				eventCount: 0,
+				eventsFile: defaultSyncEventsFilePath$1(),
 				filePath: defaultSyncStateFilePath(),
 				lastChanges: [],
 				running: false
@@ -3603,6 +3675,9 @@ var GranolaApp = class {
 		if (!this.deps.syncStateStore) return;
 		await this.deps.syncStateStore.writeState(this.#state.sync);
 	}
+	createSyncRunId() {
+		return `sync-${this.nowIso().replaceAll(/[-:.]/g, "").replace("T", "").replace("Z", "")}`;
+	}
 	applyAuthState(auth, options = {}) {
 		if (options.resetDocuments) this.resetRemoteState();
 		this.#state.auth = { ...auth };
@@ -3787,6 +3862,10 @@ var GranolaApp = class {
 	async inspectSync() {
 		return cloneSyncState(this.#state.sync);
 	}
+	async listSyncEvents(options = {}) {
+		if (!this.deps.syncEventStore) return { events: [] };
+		return { events: (await this.deps.syncEventStore.readEvents(options.limit)).map(cloneSyncEvent) };
+	}
 	async loginAuth(options = {}) {
 		const controller = this.requireAuthController();
 		try {
@@ -3850,11 +3929,17 @@ var GranolaApp = class {
 			const snapshot = await this.liveMeetingSnapshot({ forceRefresh: options.forceRefresh ?? true });
 			await this.persistMeetingIndex(snapshot.meetings);
 			const { changes, summary } = diffMeetingSummaries(previousMeetings, snapshot.meetings, snapshot.folders?.length ?? 0);
+			const completedAt = this.nowIso();
+			const runId = this.createSyncRunId();
+			const events = buildSyncEvents(runId, completedAt, changes);
+			if (events.length > 0 && this.deps.syncEventStore) await this.deps.syncEventStore.appendEvents(events);
 			this.#state.sync = {
 				...this.#state.sync,
+				eventCount: this.#state.sync.eventCount + events.length,
 				lastChanges: changes.slice(0, 50).map(cloneSyncChange),
-				lastCompletedAt: this.nowIso(),
+				lastCompletedAt: completedAt,
 				lastError: void 0,
+				lastRunId: runId,
 				running: false,
 				summary: { ...summary }
 			};
@@ -3880,7 +3965,7 @@ var GranolaApp = class {
 	async sync(options = {}) {
 		return await this.runSync({
 			forceRefresh: options.forceRefresh,
-			foreground: true
+			foreground: options.foreground ?? true
 		});
 	}
 	async listDocuments(options = {}) {
@@ -4203,6 +4288,7 @@ async function createGranolaApp(config, options = {}) {
 	const exportJobs = await exportJobStore.readJobs();
 	const meetingIndexStore = createDefaultMeetingIndexStore();
 	const meetingIndex = await meetingIndexStore.readIndex();
+	const syncEventStore = createDefaultSyncEventStore();
 	const syncStateStore = createDefaultSyncStateStore();
 	const syncState = await syncStateStore.readState();
 	return new GranolaApp(config, {
@@ -4215,6 +4301,7 @@ async function createGranolaApp(config, options = {}) {
 		meetingIndex,
 		meetingIndexStore,
 		now: options.now,
+		syncEventStore,
 		syncState,
 		syncStateStore
 	}, { surface: options.surface });
@@ -4325,6 +4412,14 @@ function parseTrustedOrigins(value) {
 	if (typeof value !== "string" || !value.trim()) return [];
 	return value.split(",").map((origin) => origin.trim()).filter(Boolean);
 }
+function parseSyncInterval(value, fallbackMs = 6e4) {
+	if (value === void 0) return fallbackMs;
+	if (typeof value !== "string" || !value.trim()) throw new Error("invalid sync interval: expected a duration like 60s or 5m");
+	return parseDuration(value);
+}
+function syncEnabled(commandFlags) {
+	return commandFlags["no-sync"] !== true;
+}
 async function waitForShutdown(close) {
 	await new Promise((resolve, reject) => {
 		let closing = false;
@@ -4903,12 +4998,20 @@ function renderAppState() {
   const folderStatus = appState.folders.loaded
     ? appState.folders.count + " folders"
     : "not loaded";
+  const syncStatus = appState.sync.running
+    ? "running"
+    : appState.sync.lastError
+      ? "error"
+      : appState.sync.lastCompletedAt
+        ? "last " + appState.sync.lastCompletedAt.slice(11, 19)
+        : "idle";
 
   els.appState.innerHTML = [
     '<div class="status-grid">',
     '<div><span class="status-label">Surface</span><strong>' + escapeHtml(appState.ui.surface) + "</strong></div>",
     '<div><span class="status-label">View</span><strong>' + escapeHtml(appState.ui.view) + "</strong></div>",
     '<div><span class="status-label">Auth</span><strong>' + escapeHtml(authMode) + "</strong></div>",
+    '<div><span class="status-label">Sync</span><strong>' + escapeHtml(syncStatus) + "</strong></div>",
     '<div><span class="status-label">Documents</span><strong>' + escapeHtml(docs) + "</strong></div>",
     '<div><span class="status-label">Folders</span><strong>' + escapeHtml(folderStatus) + "</strong></div>",
     '<div><span class="status-label">Cache</span><strong>' + escapeHtml(cache) + "</strong></div>",
@@ -5055,7 +5158,7 @@ function renderMeetingList() {
     });
     const message = filterSummary
       ? "No meetings match " + filterSummary + "."
-      : "No meetings yet. Try Refresh.";
+      : "No meetings yet. Try Sync now.";
     els.list.innerHTML = '<div class="meeting-empty">' + escapeHtml(message) + "</div>";
     renderMeetingDetail();
     return;
@@ -5334,8 +5437,16 @@ async function quickOpenMeeting() {
 }
 
 async function refreshAll(forceLiveMeetings = false) {
-  setStatus("Refreshing…", "busy");
+  setStatus(forceLiveMeetings ? "Syncing…" : "Refreshing…", "busy");
   try {
+    if (forceLiveMeetings) {
+      await fetchJson("/sync", {
+        body: JSON.stringify({ forceRefresh: true }),
+        headers: { "content-type": "application/json" },
+        method: "POST",
+      });
+    }
+
     await loadFolders({ refresh: forceLiveMeetings });
     const [appState, authState] = await Promise.all([fetchJson("/state"), fetchJson("/auth/status")]);
     await loadMeetings({ refresh: forceLiveMeetings });
@@ -5345,7 +5456,14 @@ async function refreshAll(forceLiveMeetings = false) {
       auth: authState,
     };
     renderAppState();
-    setStatus(forceLiveMeetings ? "Live data refreshed" : state.meetingSource === "index" ? "Loaded from index" : "Connected", "ok");
+    setStatus(
+      forceLiveMeetings
+        ? "Sync complete"
+        : state.meetingSource === "index"
+          ? "Loaded from index"
+          : "Connected",
+      "ok",
+    );
   } catch (error) {
     if (error.authRequired) {
       setStatus("Server locked", "error");
@@ -5790,7 +5908,7 @@ const granolaWebMarkup = String.raw`
     </section>
     <section class="toolbar">
       <div class="toolbar-actions">
-        <button class="button button--primary" data-refresh>Refresh</button>
+        <button class="button button--primary" data-refresh>Sync now</button>
         <button class="button button--secondary" data-export-notes>Export Notes</button>
         <button class="button button--secondary" data-export-transcripts>Export Transcripts</button>
       </div>
@@ -6566,6 +6684,7 @@ async function startGranolaServer(app, options = {}) {
 			exportJobs: true,
 			meetingIndex: true,
 			sessionStore: defaultGranolaToolkitPersistenceLayout().sessionStoreKind,
+			syncEvents: true,
 			syncState: true
 		},
 		product: "granola-toolkit",
@@ -6664,7 +6783,14 @@ async function startGranolaServer(app, options = {}) {
 			}
 			if (method === "POST" && path === granolaTransportPaths.syncRun) {
 				const body = await readJsonBody(request);
-				sendJson(response, await app.sync({ forceRefresh: typeof body.forceRefresh === "boolean" ? body.forceRefresh : void 0 }), { headers: originHeaders });
+				sendJson(response, await app.sync({
+					foreground: typeof body.foreground === "boolean" ? body.foreground : void 0,
+					forceRefresh: typeof body.forceRefresh === "boolean" ? body.forceRefresh : void 0
+				}), { headers: originHeaders });
+				return;
+			}
+			if (method === "GET" && path === granolaTransportPaths.syncEvents) {
+				sendJson(response, await app.listSyncEvents({ limit: parseInteger(url.searchParams.get("limit")) ?? 20 }), { headers: originHeaders });
 				return;
 			}
 			if (method === "POST" && path === granolaTransportPaths.authLock) {
@@ -6851,6 +6977,59 @@ async function startGranolaServer(app, options = {}) {
 	};
 }
 //#endregion
+//#region src/sync-loop.ts
+function createGranolaSyncLoop(options) {
+	const clearTimeoutImpl = options.clearTimeoutImpl ?? clearTimeout;
+	const setTimeoutImpl = options.setTimeoutImpl ?? setTimeout;
+	let inFlight;
+	let stopped = true;
+	let timer;
+	const schedule = () => {
+		if (stopped) return;
+		timer = setTimeoutImpl(() => {
+			runCycle();
+		}, options.intervalMs);
+	};
+	const runCycle = async () => {
+		if (stopped || inFlight) return;
+		inFlight = (async () => {
+			try {
+				const result = await options.app.sync({
+					forceRefresh: true,
+					foreground: false
+				});
+				await options.onSynced?.(result);
+			} catch (error) {
+				options.logger?.warn?.(`background sync failed: ${error instanceof Error ? error.message : String(error)}`);
+				await options.onError?.(error);
+			} finally {
+				inFlight = void 0;
+				schedule();
+			}
+		})();
+		await inFlight;
+	};
+	return {
+		start(loopOptions = {}) {
+			if (!stopped) return;
+			stopped = false;
+			if (loopOptions.immediate === false) {
+				schedule();
+				return;
+			}
+			runCycle();
+		},
+		async stop() {
+			stopped = true;
+			if (timer !== void 0) {
+				clearTimeoutImpl(timer);
+				timer = void 0;
+			}
+			await inFlight;
+		}
+	};
+}
+//#endregion
 //#region src/web-url.ts
 function buildGranolaMeetingUrl(baseUrl, meetingId) {
 	const url = new URL(baseUrl);
@@ -6869,6 +7048,8 @@ function resolveGranolaWebWorkspaceOptions(commandFlags) {
 		openBrowser: commandFlags.open !== false,
 		password: typeof commandFlags.password === "string" && commandFlags.password.trim() ? commandFlags.password.trim() : void 0,
 		port,
+		syncEnabled: syncEnabled(commandFlags),
+		syncIntervalMs: parseSyncInterval(commandFlags["sync-interval"]),
 		trustedOrigins: parseTrustedOrigins(commandFlags["trusted-origins"])
 	};
 }
@@ -6896,6 +7077,7 @@ function printWebRoutes() {
 	console.log("  POST /exports/notes");
 	console.log("  POST /exports/jobs/:id/rerun");
 	console.log("  POST /exports/transcripts");
+	console.log("  GET  /sync/events");
 	console.log("  POST /sync");
 }
 async function runGranolaWebWorkspace(app, options) {
@@ -6908,6 +7090,12 @@ async function runGranolaWebWorkspace(app, options) {
 			trustedOrigins: options.trustedOrigins
 		}
 	});
+	const syncLoop = options.syncEnabled ? createGranolaSyncLoop({
+		app,
+		intervalMs: options.syncIntervalMs,
+		logger: console
+	}) : void 0;
+	syncLoop?.start();
 	const targetUrl = options.targetMeetingId ? buildGranolaMeetingUrl(server.url, options.targetMeetingId) : new URL(server.url);
 	console.log(`Granola Toolkit web workspace listening on ${server.url.href}`);
 	if (targetUrl.href !== server.url.href) console.log(`Focused meeting URL: ${targetUrl.href}`);
@@ -6915,6 +7103,7 @@ async function runGranolaWebWorkspace(app, options) {
 	if (options.password) console.log("Server password protection: enabled");
 	else if (options.networkMode === "lan") console.log("Warning: LAN mode is enabled without a server password");
 	if (options.trustedOrigins.length > 0) console.log(`Trusted origins: ${options.trustedOrigins.join(", ")}`);
+	console.log(options.syncEnabled ? `Background sync: enabled (${options.syncIntervalMs}ms)` : "Background sync: disabled");
 	printWebRoutes();
 	console.log(`Attach: granola attach ${server.url.href}`);
 	if (options.password) console.log("Attach password: add --password <value>");
@@ -6925,7 +7114,10 @@ async function runGranolaWebWorkspace(app, options) {
 		console.error(`failed to open browser automatically: ${message}`);
 		console.error(`open ${targetUrl.href} manually`);
 	}
-	await waitForShutdown(async () => await server.close());
+	await waitForShutdown(async () => {
+		await syncLoop?.stop();
+		await server.close();
+	});
 	return 0;
 }
 //#endregion
@@ -7256,6 +7448,8 @@ Options:
   --hostname <value>      Hostname to bind (overrides network default)
   --port <value>          Port to bind (default: 0 for any available port)
   --password <value>      Optional server password for API and browser access
+  --sync-interval <value> Background sync interval, e.g. 60s or 5m (default: 60s)
+  --no-sync               Disable the background sync loop
   --trusted-origins <v>   Comma-separated extra browser origins to trust
   --cache <path>          Path to Granola cache JSON
   --timeout <value>       Request timeout, e.g. 2m, 30s, 120000 (default: 2m)
@@ -7272,8 +7466,10 @@ const serveCommand = {
 		help: { type: "boolean" },
 		hostname: { type: "string" },
 		network: { type: "string" },
+		"no-sync": { type: "boolean" },
 		password: { type: "string" },
 		port: { type: "string" },
+		"sync-interval": { type: "string" },
 		timeout: { type: "string" },
 		"trusted-origins": { type: "string" }
 	},
@@ -7293,6 +7489,8 @@ const serveCommand = {
 		const hostname = resolveServerHostname(networkMode, commandFlags.hostname);
 		const port = parsePort(commandFlags.port);
 		const password = typeof commandFlags.password === "string" && commandFlags.password.trim() ? commandFlags.password : void 0;
+		const backgroundSyncEnabled = syncEnabled(commandFlags);
+		const syncIntervalMs = parseSyncInterval(commandFlags["sync-interval"]);
 		const trustedOrigins = parseTrustedOrigins(commandFlags["trusted-origins"]);
 		const server = await startGranolaServer(app, {
 			hostname,
@@ -7302,11 +7500,18 @@ const serveCommand = {
 				trustedOrigins
 			}
 		});
+		const syncLoop = backgroundSyncEnabled ? createGranolaSyncLoop({
+			app,
+			intervalMs: syncIntervalMs,
+			logger: console
+		}) : void 0;
+		syncLoop?.start();
 		console.log(`Granola server listening on ${server.url.href}`);
 		console.log(`Network mode: ${networkMode}`);
 		if (password) console.log("Server password protection: enabled");
 		else if (networkMode === "lan") console.log("Warning: LAN mode is enabled without a server password");
 		if (trustedOrigins.length > 0) console.log(`Trusted origins: ${trustedOrigins.join(", ")}`);
+		console.log(backgroundSyncEnabled ? `Background sync: enabled (${syncIntervalMs}ms)` : "Background sync: disabled");
 		console.log("Endpoints:");
 		console.log("  GET  /health");
 		console.log("  GET  /server/info");
@@ -7325,10 +7530,14 @@ const serveCommand = {
 		console.log("  POST /exports/notes");
 		console.log("  POST /exports/jobs/:id/rerun");
 		console.log("  POST /exports/transcripts");
+		console.log("  GET  /sync/events");
 		console.log("  POST /sync");
 		console.log(`Attach: granola attach ${server.url.href}`);
 		if (password) console.log("Attach password: add --password <value>");
-		await waitForShutdown(async () => await server.close());
+		await waitForShutdown(async () => {
+			await syncLoop?.stop();
+			await server.close();
+		});
 		return 0;
 	}
 };
@@ -7339,8 +7548,12 @@ function syncHelp() {
 
 Usage:
   granola sync [options]
+  granola sync events [options]
 
 Options:
+  --watch             Keep syncing in the background until interrupted
+  --interval <value>  Poll interval for --watch, e.g. 60s or 5m (default: 60s)
+  --limit <value>     Event count for sync events output (default: 20)
   --cache <path>      Path to Granola cache JSON
   --timeout <value>   Request timeout, e.g. 2m, 30s, 120000 (default: 2m)
   --supabase <path>   Path to supabase.json
@@ -7352,16 +7565,27 @@ Options:
 function pluralise(count, singular, plural = singular) {
 	return `${count} ${count === 1 ? singular : plural}`;
 }
+function printSyncResult(result, log = console.log) {
+	log(`✓ Synced ${pluralise(result.summary.meetingCount, "meeting", "meetings")} across ${pluralise(result.summary.folderCount, "folder", "folders")} (${pluralise(result.summary.createdCount, "created")}, ${pluralise(result.summary.changedCount, "updated")}, ${pluralise(result.summary.removedCount, "removed")}, ${pluralise(result.summary.transcriptReadyCount, "transcript ready", "transcripts ready")})`);
+	const lines = result.changes.slice(0, 10).map((change) => {
+		return `  ${change.kind.padEnd(16)} ${change.title} (${change.meetingId})`;
+	});
+	for (const line of lines) log(line);
+	if (result.changes.length > lines.length) log(`  ...and ${result.changes.length - lines.length} more change(s)`);
+}
 const syncCommand = {
 	description: "Refresh the local meeting index and sync state",
 	flags: {
 		cache: { type: "string" },
 		help: { type: "boolean" },
-		timeout: { type: "string" }
+		interval: { type: "string" },
+		limit: { type: "string" },
+		timeout: { type: "string" },
+		watch: { type: "boolean" }
 	},
 	help: syncHelp,
 	name: "sync",
-	async run({ commandFlags, globalFlags }) {
+	async run({ commandArgs, commandFlags, globalFlags }) {
 		const config = await loadConfig({
 			globalFlags,
 			subcommandFlags: commandFlags
@@ -7372,14 +7596,38 @@ const syncCommand = {
 		debug(config.debug, "timeoutMs", config.notes.timeoutMs);
 		const app = await createGranolaApp(config);
 		debug(config.debug, "authMode", app.getState().auth.mode);
+		if (commandArgs[0] === "events") {
+			const limit = typeof commandFlags.limit === "string" && /^\d+$/.test(commandFlags.limit) ? Number(commandFlags.limit) : 20;
+			const result = await app.listSyncEvents({ limit });
+			if (result.events.length === 0) {
+				console.log("No sync events yet.");
+				return 0;
+			}
+			for (const event of result.events) console.log(`${event.occurredAt} ${event.kind.padEnd(18)} ${event.title} (${event.meetingId})`);
+			return 0;
+		}
 		const result = await app.sync();
-		console.log(`✓ Synced ${pluralise(result.summary.meetingCount, "meeting", "meetings")} across ${pluralise(result.summary.folderCount, "folder", "folders")} (${pluralise(result.summary.createdCount, "created")}, ${pluralise(result.summary.changedCount, "updated")}, ${pluralise(result.summary.removedCount, "removed")}, ${pluralise(result.summary.transcriptReadyCount, "transcript ready", "transcripts ready")})`);
-		const lines = result.changes.slice(0, 10).map((change) => {
-			return `  ${change.kind.padEnd(16)} ${change.title} (${change.meetingId})`;
-		});
-		for (const line of lines) console.log(line);
-		if (result.changes.length > lines.length) console.log(`  ...and ${result.changes.length - lines.length} more change(s)`);
+		printSyncResult(result);
 		if (result.state.lastCompletedAt) debug(config.debug, "syncCompletedAt", result.state.lastCompletedAt);
+		if (commandFlags.watch === true) {
+			const intervalMs = parseSyncInterval(commandFlags.interval);
+			const syncLoop = createGranolaSyncLoop({
+				app,
+				intervalMs,
+				logger: console,
+				onError: async (error) => {
+					console.error(error instanceof Error ? error.message : String(error));
+				},
+				onSynced: async (nextResult) => {
+					printSyncResult(nextResult);
+				}
+			});
+			syncLoop.start({ immediate: false });
+			console.log(`Watching for Granola changes every ${intervalMs}ms. Press Ctrl+C to stop.`);
+			await waitForShutdown(async () => {
+				await syncLoop.stop();
+			});
+		}
 		return 0;
 	}
 };
@@ -7393,6 +7641,8 @@ Usage:
 
 Options:
   --meeting <id>     Open the workspace focused on a specific meeting
+  --sync-interval <value> Background sync interval, e.g. 60s or 5m (default: 60s)
+  --no-sync          Disable the background sync loop
   --cache <path>     Path to Granola cache JSON
   --timeout <value>  Request timeout, e.g. 2m, 30s, 120000 (default: 2m)
   --supabase <path>  Path to supabase.json
@@ -7407,6 +7657,8 @@ const tuiCommand = {
 		cache: { type: "string" },
 		help: { type: "boolean" },
 		meeting: { type: "string" },
+		"no-sync": { type: "boolean" },
+		"sync-interval": { type: "string" },
 		timeout: { type: "string" }
 	},
 	help: tuiHelp,
@@ -7420,7 +7672,23 @@ const tuiCommand = {
 		debug(config.debug, "supabase", config.supabase);
 		debug(config.debug, "cacheFile", config.transcripts.cacheFile || "(none)");
 		debug(config.debug, "timeoutMs", config.notes.timeoutMs);
-		return await runGranolaTui(await createGranolaApp(config, { surface: "tui" }), { initialMeetingId: typeof commandFlags.meeting === "string" && commandFlags.meeting.trim() ? commandFlags.meeting.trim() : void 0 });
+		const app = await createGranolaApp(config, { surface: "tui" });
+		const initialMeetingId = typeof commandFlags.meeting === "string" && commandFlags.meeting.trim() ? commandFlags.meeting.trim() : void 0;
+		const backgroundSyncEnabled = syncEnabled(commandFlags);
+		const syncIntervalMs = parseSyncInterval(commandFlags["sync-interval"]);
+		const syncLoop = backgroundSyncEnabled ? createGranolaSyncLoop({
+			app,
+			intervalMs: syncIntervalMs,
+			logger: console
+		}) : void 0;
+		syncLoop?.start();
+		debug(config.debug, "backgroundSync", backgroundSyncEnabled ? `${syncIntervalMs}ms` : "disabled");
+		return await runGranolaTui(app, {
+			initialMeetingId,
+			onClose: async () => {
+				await syncLoop?.stop();
+			}
+		});
 	}
 };
 //#endregion
@@ -7500,6 +7768,8 @@ Options:
   --hostname <value>      Hostname to bind (overrides network default)
   --port <value>          Port to bind (default: 0 for any available port)
   --password <value>      Optional server password for API and browser access
+  --sync-interval <value> Background sync interval, e.g. 60s or 5m (default: 60s)
+  --no-sync               Disable the background sync loop
   --trusted-origins <v>   Comma-separated extra browser origins to trust
   --cache <path>          Path to Granola cache JSON
   --timeout <value>       Request timeout, e.g. 2m, 30s, 120000 (default: 2m)
@@ -7531,9 +7801,11 @@ const commands = [
 			hostname: { type: "string" },
 			meeting: { type: "string" },
 			network: { type: "string" },
+			"no-sync": { type: "boolean" },
 			open: { type: "boolean" },
 			password: { type: "string" },
 			port: { type: "string" },
+			"sync-interval": { type: "string" },
 			timeout: { type: "string" },
 			"trusted-origins": { type: "string" }
 		},

package/package.json

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