granola-toolkit 0.17.0 → 0.19.0

package/README.md

@@ -35,7 +35,9 @@ granola --help
 granola auth login
 granola meeting --help
 granola notes --help
+granola serve --help
 granola transcripts --help
+granola web --help
 ```
 
 The published package exposes both `granola` and `granola-toolkit` as executable names.
@@ -47,7 +49,9 @@ vp pack
 node dist/cli.js --help
 node dist/cli.js meeting --help
 node dist/cli.js notes --help
+node dist/cli.js serve --help
 node dist/cli.js transcripts --help
+node dist/cli.js web --help
 ```
 
 You can also use the package scripts:
@@ -89,6 +93,17 @@ granola meeting transcript 1234abcd --format json
 granola meeting export 1234abcd --format yaml
 ```
 
+Run the local API server:
+
+```bash
+granola serve
+granola serve --port 4096
+granola serve --hostname 0.0.0.0 --port 4096
+
+granola web
+granola web --open=false --port 4096
+```
+
 ## How It Works
 
 ### Notes
@@ -167,6 +182,33 @@ The machine-readable `export` command includes:
 - structured note data plus rendered Markdown
 - structured transcript data plus rendered transcript text when available
 
+### Server
+
+`serve` starts a long-lived local `Granola Toolkit` server on one shared app instance.
+
+The initial server API includes:
+
+- `GET /health`
+- `GET /state`
+- `GET /events` for server-sent state updates
+- `GET /meetings`
+- `GET /meetings/:id`
+- `POST /exports/notes`
+- `POST /exports/transcripts`
+
+This is the foundation for the future `granola web` client and any attachable TUI flows.
+
+### Web
+
+`web` starts the same local server as `serve`, enables the browser client at `/`, and opens that workspace in your default browser unless you pass `--open=false`.
+
+The initial browser client includes:
+
+- a searchable meeting list
+- a meeting detail view with notes and transcript panes
+- app-state status from the shared core
+- note and transcript export actions backed by the same local API
+
 ## Auth
 
 If you do not want to keep passing `--supabase`, import the desktop app session once:

package/dist/cli.js

@@ -7,6 +7,7 @@ import { dirname, join } from "node:path";
 import { promisify } from "node:util";
 import { NodeHtmlMarkdown } from "node-html-markdown";
 import { createHash } from "node:crypto";
+import { createServer } from "node:http";
 //#region src/utils.ts
 const INVALID_FILENAME_CHARS = /[<>:"/\\|?*]/g;
 const CONTROL_CHARACTERS = /\p{Cc}/gu;
@@ -153,7 +154,7 @@ function transcriptSpeakerLabel(segment) {
 }
 //#endregion
 //#region src/client/auth.ts
-const execFileAsync = promisify(execFile);
+const execFileAsync$1 = promisify(execFile);
 const DEFAULT_CLIENT_ID = "client_GranolaMac";
 const KEYCHAIN_SERVICE_NAME = "com.granola.toolkit";
 const KEYCHAIN_ACCOUNT_NAME = "session";
@@ -243,7 +244,7 @@ var FileSessionStore = class {
 var KeychainSessionStore = class {
 	async clearSession() {
 		try {
-			await execFileAsync("security", [
+			await execFileAsync$1("security", [
 				"delete-generic-password",
 				"-s",
 				KEYCHAIN_SERVICE_NAME,
@@ -254,7 +255,7 @@ var KeychainSessionStore = class {
 	}
 	async readSession() {
 		try {
-			const { stdout } = await execFileAsync("security", [
+			const { stdout } = await execFileAsync$1("security", [
 				"find-generic-password",
 				"-s",
 				KEYCHAIN_SERVICE_NAME,
@@ -269,7 +270,7 @@ var KeychainSessionStore = class {
 		}
 	}
 	async writeSession(session) {
-		await execFileAsync("security", [
+		await execFileAsync$1("security", [
 			"add-generic-password",
 			"-U",
 			"-s",
@@ -1517,6 +1518,7 @@ var GranolaApp = class {
 	#cacheResolved = false;
 	#granolaClient;
 	#documents;
+	#listeners = /* @__PURE__ */ new Set();
 	#state;
 	constructor(config, deps, options = {}) {
 		this.config = config;
@@ -1526,16 +1528,31 @@ var GranolaApp = class {
 	getState() {
 		return cloneState(this.#state);
 	}
+	subscribe(listener) {
+		this.#listeners.add(listener);
+		return () => {
+			this.#listeners.delete(listener);
+		};
+	}
 	setUiState(patch) {
 		this.#state.ui = {
 			...this.#state.ui,
 			...patch
 		};
+		this.emitStateUpdate();
 		return this.getState();
 	}
 	nowIso() {
 		return (this.deps.now ?? (() => /* @__PURE__ */ new Date()))().toISOString();
 	}
+	emitStateUpdate() {
+		const event = {
+			state: this.getState(),
+			timestamp: this.nowIso(),
+			type: "state.updated"
+		};
+		for (const listener of this.#listeners) listener(event);
+	}
 	async getGranolaClient() {
 		if (this.#granolaClient) return this.#granolaClient;
 		if (this.deps.granolaClient) {
@@ -1546,6 +1563,7 @@ var GranolaApp = class {
 		const runtime = await this.deps.createGranolaClient();
 		this.#granolaClient = runtime.client;
 		this.#state.auth = { ...runtime.auth };
+		this.emitStateUpdate();
 		return this.#granolaClient;
 	}
 	missingCacheError() {
@@ -1560,6 +1578,7 @@ var GranolaApp = class {
 			loaded: true,
 			loadedAt: this.nowIso()
 		};
+		this.emitStateUpdate();
 		return documents;
 	}
 	async loadCache(options = {}) {
@@ -1585,6 +1604,7 @@ var GranolaApp = class {
 			loadedAt: cacheData ? this.nowIso() : void 0,
 			transcriptCount: cacheData ? transcriptCount(cacheData) : 0
 		};
+		this.emitStateUpdate();
 		if (options.required && !cacheData) throw this.missingCacheError();
 		return cacheData;
 	}
@@ -1626,6 +1646,7 @@ var GranolaApp = class {
 			ranAt: this.nowIso(),
 			written
 		};
+		this.emitStateUpdate();
 		this.setUiState({ view: "notes-export" });
 		return {
 			documentCount: documents.length,
@@ -1647,6 +1668,7 @@ var GranolaApp = class {
 			ranAt: this.nowIso(),
 			written
 		};
+		this.emitStateUpdate();
 		this.setUiState({ view: "transcripts-export" });
 		return {
 			cacheData,
@@ -1745,6 +1767,41 @@ async function loadConfig(options) {
 function debug(enabled, ...values) {
 	if (enabled) console.error("[debug]", ...values);
 }
+function parsePort(value) {
+	if (value === void 0) return;
+	if (typeof value !== "string" || !/^\d+$/.test(value)) throw new Error("invalid port: expected a non-negative integer");
+	const port = Number(value);
+	if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error("invalid port: expected a value between 0 and 65535");
+	return port;
+}
+function pickHostname(value, fallback = "127.0.0.1") {
+	return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}
+async function waitForShutdown(close) {
+	await new Promise((resolve, reject) => {
+		let closing = false;
+		const cleanup = () => {
+			process.off("SIGINT", handleSignal);
+			process.off("SIGTERM", handleSignal);
+		};
+		const finish = async () => {
+			if (closing) return;
+			closing = true;
+			cleanup();
+			try {
+				await close();
+				resolve();
+			} catch (error) {
+				reject(error);
+			}
+		};
+		const handleSignal = () => {
+			finish();
+		};
+		process.on("SIGINT", handleSignal);
+		process.on("SIGTERM", handleSignal);
+	});
+}
 //#endregion
 //#region src/commands/meeting.ts
 function meetingHelp() {
@@ -2010,6 +2067,778 @@ function resolveNoteFormat(value) {
 	}
 }
 //#endregion
+//#region src/server/web.ts
+function renderGranolaWebPage() {
+	return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Granola Toolkit</title>
+    <style>
+      :root {
+        --bg: #f2ede2;
+        --panel: rgba(255, 252, 247, 0.86);
+        --panel-strong: #fffaf2;
+        --line: rgba(36, 39, 44, 0.12);
+        --ink: #1d242c;
+        --muted: #5d6b77;
+        --accent: #0d6a6d;
+        --accent-soft: rgba(13, 106, 109, 0.12);
+        --warm: #a34f2f;
+        --ok: #246b4f;
+        --error: #9d2c2c;
+        --shadow: 0 24px 80px rgba(40, 32, 16, 0.12);
+        --radius: 24px;
+        --mono: "SF Mono", "IBM Plex Mono", "Cascadia Code", monospace;
+        --serif: "Iowan Old Style", "Palatino Linotype", "Book Antiqua", Georgia, serif;
+        --sans: "Avenir Next", "Segoe UI", sans-serif;
+      }
+
+      * { box-sizing: border-box; }
+
+      body {
+        margin: 0;
+        min-height: 100vh;
+        font-family: var(--sans);
+        color: var(--ink);
+        background:
+          radial-gradient(circle at top left, rgba(163, 79, 47, 0.18), transparent 32%),
+          radial-gradient(circle at right 12%, rgba(13, 106, 109, 0.16), transparent 28%),
+          linear-gradient(180deg, #f8f2e8 0%, var(--bg) 100%);
+      }
+
+      .shell {
+        display: grid;
+        grid-template-columns: 320px minmax(0, 1fr);
+        gap: 18px;
+        min-height: 100vh;
+        padding: 24px;
+      }
+
+      .pane {
+        background: var(--panel);
+        backdrop-filter: blur(18px);
+        border: 1px solid var(--line);
+        border-radius: var(--radius);
+        box-shadow: var(--shadow);
+      }
+
+      .sidebar {
+        display: grid;
+        grid-template-rows: auto auto 1fr;
+        overflow: hidden;
+      }
+
+      .hero, .toolbar, .detail-head {
+        padding: 22px 24px;
+        border-bottom: 1px solid var(--line);
+      }
+
+      .hero h1 {
+        margin: 0;
+        font-family: var(--serif);
+        font-size: clamp(2rem, 3vw, 2.8rem);
+        font-weight: 600;
+        letter-spacing: -0.04em;
+      }
+
+      .hero p, .toolbar p {
+        margin: 8px 0 0;
+        color: var(--muted);
+        line-height: 1.5;
+      }
+
+      .search {
+        width: 100%;
+        margin-top: 16px;
+        padding: 12px 14px;
+        border: 1px solid var(--line);
+        border-radius: 999px;
+        background: rgba(255, 255, 255, 0.7);
+        color: var(--ink);
+        font: inherit;
+      }
+
+      .meeting-list {
+        padding: 14px;
+        overflow: auto;
+      }
+
+      .meeting-row {
+        width: 100%;
+        display: grid;
+        gap: 4px;
+        text-align: left;
+        margin: 0 0 10px;
+        padding: 14px 16px;
+        border: 1px solid transparent;
+        border-radius: 18px;
+        background: rgba(255, 255, 255, 0.72);
+        color: inherit;
+        cursor: pointer;
+        transition: transform 140ms ease, border-color 140ms ease, background 140ms ease;
+      }
+
+      .meeting-row:hover,
+      .meeting-row[data-selected="true"] {
+        transform: translateY(-1px);
+        border-color: rgba(13, 106, 109, 0.25);
+        background: var(--panel-strong);
+      }
+
+      .meeting-row__title {
+        font-weight: 600;
+      }
+
+      .meeting-row__meta {
+        color: var(--muted);
+        font-size: 0.92rem;
+      }
+
+      .meeting-empty {
+        padding: 18px;
+        color: var(--muted);
+      }
+
+      .detail {
+        display: grid;
+        grid-template-rows: auto auto 1fr;
+        min-width: 0;
+      }
+
+      .detail-head {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: 18px;
+      }
+
+      .detail-head h2 {
+        margin: 0;
+        font-family: var(--serif);
+        font-size: clamp(1.8rem, 2.4vw, 2.4rem);
+        font-weight: 600;
+      }
+
+      .state-badge {
+        padding: 10px 14px;
+        border-radius: 999px;
+        background: var(--accent-soft);
+        color: var(--accent);
+        font-size: 0.92rem;
+        font-weight: 700;
+      }
+
+      .state-badge[data-tone="busy"] { color: var(--warm); background: rgba(163, 79, 47, 0.12); }
+      .state-badge[data-tone="error"] { color: var(--error); background: rgba(157, 44, 44, 0.12); }
+      .state-badge[data-tone="ok"] { color: var(--ok); background: rgba(36, 107, 79, 0.12); }
+
+      .toolbar {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: center;
+        justify-content: space-between;
+        gap: 14px;
+      }
+
+      .toolbar-actions {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 10px;
+      }
+
+      .button {
+        border: 0;
+        border-radius: 999px;
+        padding: 12px 16px;
+        font: inherit;
+        font-weight: 700;
+        cursor: pointer;
+      }
+
+      .button--primary {
+        background: var(--ink);
+        color: white;
+      }
+
+      .button--secondary {
+        background: rgba(255, 255, 255, 0.72);
+        color: var(--ink);
+        border: 1px solid var(--line);
+      }
+
+      .status-grid {
+        display: grid;
+        grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+        gap: 14px;
+      }
+
+      .status-label {
+        display: block;
+        margin-bottom: 6px;
+        color: var(--muted);
+        font-size: 0.78rem;
+        letter-spacing: 0.08em;
+        text-transform: uppercase;
+      }
+
+      .detail-meta {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 10px;
+        padding: 0 24px 18px;
+      }
+
+      .detail-chip {
+        padding: 10px 12px;
+        border-radius: 999px;
+        background: rgba(255, 255, 255, 0.72);
+        border: 1px solid var(--line);
+        color: var(--muted);
+        font-size: 0.88rem;
+      }
+
+      .detail-body {
+        padding: 0 24px 24px;
+        overflow: auto;
+      }
+
+      .detail-section {
+        margin-bottom: 20px;
+        padding: 20px;
+        background: rgba(255, 255, 255, 0.72);
+        border: 1px solid var(--line);
+        border-radius: 20px;
+      }
+
+      .detail-section h2 {
+        margin: 0 0 14px;
+        font-size: 1rem;
+        letter-spacing: 0.08em;
+        text-transform: uppercase;
+      }
+
+      .detail-pre {
+        margin: 0;
+        white-space: pre-wrap;
+        word-break: break-word;
+        font-family: var(--mono);
+        line-height: 1.55;
+      }
+
+      .empty {
+        margin: 24px;
+        padding: 24px;
+        border-radius: 20px;
+        background: rgba(255, 255, 255, 0.72);
+        border: 1px dashed rgba(36, 39, 44, 0.2);
+        color: var(--muted);
+      }
+
+      @media (max-width: 900px) {
+        .shell {
+          grid-template-columns: 1fr;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <div class="shell">
+      <aside class="pane sidebar">
+        <section class="hero">
+          <h1>Granola Toolkit</h1>
+          <p>Browser workspace for meetings, notes, transcripts, and export flows on top of one local server instance.</p>
+          <input class="search" data-search placeholder="Search meetings, ids, or tags" />
+        </section>
+        <section class="toolbar">
+          <p>Meetings are loaded from the shared server state so this view can later coexist with the terminal UI.</p>
+        </section>
+        <section class="meeting-list" data-meeting-list></section>
+      </aside>
+      <main class="pane detail">
+        <section class="detail-head">
+          <div>
+            <h2>Meeting Workspace</h2>
+            <div data-app-state></div>
+          </div>
+          <div class="state-badge" data-state-badge data-tone="idle">Connecting…</div>
+        </section>
+        <section class="toolbar">
+          <div class="toolbar-actions">
+            <button class="button button--primary" data-refresh>Refresh</button>
+            <button class="button button--secondary" data-export-notes>Export Notes</button>
+            <button class="button button--secondary" data-export-transcripts>Export Transcripts</button>
+          </div>
+          <p>Initial beta web client. It speaks to the same local API that future TUI and attach flows will use.</p>
+        </section>
+        <div class="detail-meta" data-detail-meta></div>
+        <div class="detail-body" data-detail-body>
+          <div class="empty" data-empty>Select a meeting to inspect its notes and transcript.</div>
+        </div>
+      </main>
+    </div>
+    <script type="module">
+${String.raw`
+const state = {
+  meetings: [],
+  selectedMeetingId: null,
+  selectedMeeting: null,
+  appState: null,
+  search: "",
+};
+
+const els = {
+  appState: document.querySelector("[data-app-state]"),
+  detailBody: document.querySelector("[data-detail-body]"),
+  detailMeta: document.querySelector("[data-detail-meta]"),
+  empty: document.querySelector("[data-empty]"),
+  list: document.querySelector("[data-meeting-list]"),
+  noteButton: document.querySelector("[data-export-notes]"),
+  refreshButton: document.querySelector("[data-refresh]"),
+  search: document.querySelector("[data-search]"),
+  stateBadge: document.querySelector("[data-state-badge]"),
+  transcriptButton: document.querySelector("[data-export-transcripts]"),
+};
+
+function escapeHtml(value) {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+function setStatus(label, tone = "idle") {
+  els.stateBadge.textContent = label;
+  els.stateBadge.dataset.tone = tone;
+}
+
+function renderAppState() {
+  if (!state.appState) {
+    els.appState.innerHTML = "<p>Waiting for server state…</p>";
+    return;
+  }
+
+  const appState = state.appState;
+  const authMode = appState.auth.mode === "stored-session" ? "Stored session" : "supabase.json";
+  const docs = appState.documents.loaded ? String(appState.documents.count) : "not loaded";
+  const cache = appState.cache.loaded
+    ? appState.cache.transcriptCount + " transcript sets"
+    : appState.cache.configured
+      ? "configured"
+      : "not configured";
+
+  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">Documents</span><strong>' + escapeHtml(docs) + "</strong></div>",
+    '<div><span class="status-label">Cache</span><strong>' + escapeHtml(cache) + "</strong></div>",
+    "</div>",
+  ].join("");
+}
+
+function renderMeetingList() {
+  if (state.meetings.length === 0) {
+    state.selectedMeetingId = null;
+    state.selectedMeeting = null;
+    els.list.innerHTML = '<div class="meeting-empty">No meetings yet. Try Refresh.</div>';
+    renderMeetingDetail();
+    return;
+  }
+
+  const visibleIds = new Set(state.meetings.map((meeting) => meeting.id));
+  if (!state.selectedMeetingId || !visibleIds.has(state.selectedMeetingId)) {
+    state.selectedMeetingId = state.meetings[0]?.id || null;
+  }
+
+  els.list.innerHTML = state.meetings
+    .map((meeting) => {
+      const selected = meeting.id === state.selectedMeetingId ? ' data-selected="true"' : "";
+      const tags = meeting.tags.length ? meeting.tags.map((tag) => "#" + tag).join(" ") : "untagged";
+      return [
+        '<button class="meeting-row"' + selected + ' data-meeting-id="' + escapeHtml(meeting.id) + '">',
+        '<span class="meeting-row__title">' + escapeHtml(meeting.title || meeting.id) + "</span>",
+        '<span class="meeting-row__meta">' + escapeHtml(tags) + "</span>",
+        '<span class="meeting-row__meta">' + escapeHtml(meeting.updatedAt.slice(0, 10) || "unknown") + "</span>",
+        "</button>",
+      ].join("");
+    })
+    .join("");
+}
+
+function renderMeetingDetail() {
+  const record = state.selectedMeeting;
+  if (!record) {
+    els.empty.hidden = false;
+    els.detailMeta.innerHTML = "";
+    els.detailBody.innerHTML = "";
+    return;
+  }
+
+  els.empty.hidden = true;
+  els.detailMeta.innerHTML = [
+    '<div class="detail-chip">ID: ' + escapeHtml(record.meeting.id) + "</div>",
+    '<div class="detail-chip">Source: ' + escapeHtml(record.meeting.noteContentSource) + "</div>",
+    '<div class="detail-chip">Transcript: ' + escapeHtml(String(record.meeting.transcriptSegmentCount)) + " segments</div>",
+  ].join("");
+
+  els.detailBody.innerHTML = [
+    '<section class="detail-section">',
+    "<h2>Notes</h2>",
+    '<pre class="detail-pre">' + escapeHtml(record.noteMarkdown || "") + "</pre>",
+    "</section>",
+    '<section class="detail-section">',
+    "<h2>Transcript</h2>",
+    '<pre class="detail-pre">' + escapeHtml(record.transcriptText || "(Transcript unavailable)") + "</pre>",
+    "</section>",
+  ].join("");
+}
+
+async function fetchJson(path, init) {
+  const response = await fetch(path, init);
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new Error(payload.error || response.statusText || "Request failed");
+  }
+  return payload;
+}
+
+async function loadMeetings() {
+  const query = state.search ? "?search=" + encodeURIComponent(state.search) + "&limit=50" : "?limit=50";
+  const payload = await fetchJson("/meetings" + query);
+  state.meetings = payload.meetings || [];
+  if (!state.selectedMeetingId && state.meetings[0]) {
+    state.selectedMeetingId = state.meetings[0].id;
+  }
+  renderMeetingList();
+  if (state.selectedMeetingId) {
+    await loadMeeting(state.selectedMeetingId);
+  } else {
+    renderMeetingDetail();
+  }
+}
+
+async function loadMeeting(id) {
+  state.selectedMeetingId = id;
+  renderMeetingList();
+  const payload = await fetchJson("/meetings/" + encodeURIComponent(id));
+  state.selectedMeeting = payload.meeting || null;
+  renderMeetingDetail();
+}
+
+async function refreshAll() {
+  setStatus("Refreshing…", "busy");
+  const [appState] = await Promise.all([fetchJson("/state"), loadMeetings()]);
+  state.appState = appState;
+  renderAppState();
+  setStatus("Connected", "ok");
+}
+
+async function exportNotes() {
+  setStatus("Exporting notes…", "busy");
+  await fetchJson("/exports/notes", {
+    body: JSON.stringify({ format: "markdown" }),
+    headers: { "content-type": "application/json" },
+    method: "POST",
+  });
+  await refreshAll();
+}
+
+async function exportTranscripts() {
+  setStatus("Exporting transcripts…", "busy");
+  await fetchJson("/exports/transcripts", {
+    body: JSON.stringify({ format: "text" }),
+    headers: { "content-type": "application/json" },
+    method: "POST",
+  });
+  await refreshAll();
+}
+
+els.list.addEventListener("click", (event) => {
+  if (!(event.target instanceof Element)) {
+    return;
+  }
+
+  const button = event.target.closest("[data-meeting-id]");
+  if (!button) return;
+  void loadMeeting(button.dataset.meetingId);
+});
+
+els.refreshButton.addEventListener("click", () => {
+  void refreshAll();
+});
+
+els.noteButton.addEventListener("click", () => {
+  void exportNotes();
+});
+
+els.transcriptButton.addEventListener("click", () => {
+  void exportTranscripts();
+});
+
+els.search.addEventListener("input", (event) => {
+  if (!(event.target instanceof HTMLInputElement)) {
+    return;
+  }
+
+  state.search = event.target.value.trim();
+  void loadMeetings();
+});
+
+const events = new EventSource("/events");
+events.addEventListener("state.updated", (event) => {
+  const payload = JSON.parse(event.data);
+  state.appState = payload.state;
+  renderAppState();
+});
+events.addEventListener("error", () => {
+  setStatus("Disconnected", "error");
+});
+
+void refreshAll().catch((error) => {
+  setStatus("Error", "error");
+  els.empty.hidden = false;
+  els.empty.textContent = error.message;
+});
+`}
+    <\/script>
+  </body>
+</html>`;
+}
+//#endregion
+//#region src/server/http.ts
+function parseInteger(value) {
+	if (!value?.trim()) return;
+	if (!/^\d+$/.test(value)) throw new Error("invalid limit: expected a positive integer");
+	const parsed = Number(value);
+	if (!Number.isInteger(parsed) || parsed < 1) throw new Error("invalid limit: expected a positive integer");
+	return parsed;
+}
+function sendJson(response, body, init = {}) {
+	const payload = `${JSON.stringify(body, null, 2)}\n`;
+	response.writeHead(init.status ?? 200, {
+		"content-length": Buffer.byteLength(payload),
+		"content-type": "application/json; charset=utf-8"
+	});
+	response.end(payload);
+}
+function sendText(response, body, status = 200) {
+	response.writeHead(status, {
+		"content-length": Buffer.byteLength(body),
+		"content-type": "text/plain; charset=utf-8"
+	});
+	response.end(body);
+}
+function sendHtml(response, body, status = 200) {
+	response.writeHead(status, {
+		"content-length": Buffer.byteLength(body),
+		"content-type": "text/html; charset=utf-8"
+	});
+	response.end(body);
+}
+async function readJsonBody(request) {
+	const chunks = [];
+	for await (const chunk of request) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+	if (chunks.length === 0) return {};
+	try {
+		const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("request body must be a JSON object");
+		return parsed;
+	} catch (error) {
+		throw new Error(error instanceof Error ? error.message : "failed to parse JSON body");
+	}
+}
+function formatSseEvent(event) {
+	return `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`;
+}
+function noteFormatFromBody(value) {
+	switch (value) {
+		case void 0:
+		case "markdown": return "markdown";
+		case "json":
+		case "raw":
+		case "yaml": return value;
+		default: throw new Error("invalid notes format: expected markdown, json, yaml, or raw");
+	}
+}
+function transcriptFormatFromBody(value) {
+	switch (value) {
+		case void 0:
+		case "text": return "text";
+		case "json":
+		case "raw":
+		case "yaml": return value;
+		default: throw new Error("invalid transcript format: expected text, json, yaml, or raw");
+	}
+}
+async function startGranolaServer(app, options = {}) {
+	const enableWebClient = options.enableWebClient ?? false;
+	const hostname = options.hostname ?? "127.0.0.1";
+	const port = options.port ?? 0;
+	const server = createServer(async (request, response) => {
+		const method = request.method ?? "GET";
+		const url = new URL(request.url ?? "/", `http://${hostname}`);
+		const path = url.pathname;
+		try {
+			if (method === "GET" && path === "/" && enableWebClient) {
+				sendHtml(response, renderGranolaWebPage());
+				return;
+			}
+			if (method === "GET" && path === "/health") {
+				sendJson(response, {
+					ok: true,
+					service: "granola-toolkit",
+					version: app.config ? void 0 : void 0
+				});
+				return;
+			}
+			if (method === "GET" && path === "/state") {
+				sendJson(response, app.getState());
+				return;
+			}
+			if (method === "GET" && path === "/events") {
+				response.writeHead(200, {
+					"cache-control": "no-cache, no-transform",
+					connection: "keep-alive",
+					"content-type": "text/event-stream; charset=utf-8"
+				});
+				response.write(formatSseEvent({
+					state: app.getState(),
+					timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+					type: "state.updated"
+				}));
+				const unsubscribe = app.subscribe((event) => {
+					response.write(formatSseEvent(event));
+				});
+				request.on("close", () => {
+					unsubscribe();
+					response.end();
+				});
+				return;
+			}
+			if (method === "GET" && path === "/meetings") {
+				const limit = parseInteger(url.searchParams.get("limit"));
+				const search = url.searchParams.get("search")?.trim() || void 0;
+				sendJson(response, {
+					meetings: await app.listMeetings({
+						limit,
+						search
+					}),
+					search
+				});
+				return;
+			}
+			if (method === "GET" && path.startsWith("/meetings/")) {
+				const id = decodeURIComponent(path.slice(10));
+				if (!id) throw new Error("meeting id is required");
+				sendJson(response, await app.getMeeting(id, { requireCache: url.searchParams.get("includeTranscript") === "true" }));
+				return;
+			}
+			if (method === "POST" && path === "/exports/notes") {
+				const body = await readJsonBody(request);
+				sendJson(response, await app.exportNotes(noteFormatFromBody(body.format)), { status: 202 });
+				return;
+			}
+			if (method === "POST" && path === "/exports/transcripts") {
+				const body = await readJsonBody(request);
+				sendJson(response, await app.exportTranscripts(transcriptFormatFromBody(body.format)), { status: 202 });
+				return;
+			}
+			sendText(response, "Not found\n", 404);
+		} catch (error) {
+			sendJson(response, { error: error instanceof Error ? error.message : String(error) }, { status: 400 });
+		}
+	});
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(port, hostname, () => {
+			server.off("error", reject);
+			resolve();
+		});
+	});
+	const address = server.address();
+	if (!address || typeof address === "string") throw new Error("failed to resolve server address");
+	const resolved = address;
+	const url = new URL(`http://${hostname}:${resolved.port}`);
+	return {
+		app,
+		async close() {
+			await new Promise((resolve, reject) => {
+				server.close((error) => {
+					if (error) {
+						reject(error);
+						return;
+					}
+					resolve();
+				});
+			});
+		},
+		hostname,
+		port: resolved.port,
+		server,
+		url
+	};
+}
+//#endregion
+//#region src/commands/serve.ts
+function serveHelp() {
+	return `Granola serve
+
+Usage:
+  granola serve [options]
+
+Options:
+  --hostname <value>  Hostname to bind (default: 127.0.0.1)
+  --port <value>      Port to bind (default: 0 for any available port)
+  --cache <path>      Path to Granola cache JSON
+  --timeout <value>   Request timeout, e.g. 2m, 30s, 120000 (default: 2m)
+  --supabase <path>   Path to supabase.json
+  --debug             Enable debug logging
+  --config <path>     Path to .granola.toml
+  -h, --help          Show help
+`;
+}
+const serveCommand = {
+	description: "Start a local Granola API server",
+	flags: {
+		cache: { type: "string" },
+		help: { type: "boolean" },
+		hostname: { type: "string" },
+		port: { type: "string" },
+		timeout: { type: "string" }
+	},
+	help: serveHelp,
+	name: "serve",
+	async run({ commandFlags, globalFlags }) {
+		const config = await loadConfig({
+			globalFlags,
+			subcommandFlags: commandFlags
+		});
+		debug(config.debug, "using config", config.configFileUsed ?? "(none)");
+		debug(config.debug, "supabase", config.supabase);
+		debug(config.debug, "cacheFile", config.transcripts.cacheFile || "(none)");
+		debug(config.debug, "timeoutMs", config.notes.timeoutMs);
+		const server = await startGranolaServer(await createGranolaApp(config, { surface: "server" }), {
+			hostname: pickHostname(commandFlags.hostname),
+			port: parsePort(commandFlags.port)
+		});
+		console.log(`Granola server listening on ${server.url.href}`);
+		console.log("Endpoints:");
+		console.log("  GET  /health");
+		console.log("  GET  /state");
+		console.log("  GET  /events");
+		console.log("  GET  /meetings");
+		console.log("  GET  /meetings/:id");
+		console.log("  POST /exports/notes");
+		console.log("  POST /exports/transcripts");
+		await waitForShutdown(async () => await server.close());
+		return 0;
+	}
+};
+//#endregion
 //#region src/commands/transcripts.ts
 function transcriptsHelp() {
 	return `Granola transcripts
@@ -2065,12 +2894,115 @@ function resolveTranscriptFormat(value) {
 	}
 }
 //#endregion
+//#region src/browser.ts
+const execFileAsync = promisify(execFile);
+function getBrowserOpenCommand(url, platform = process.platform) {
+	const href = String(url);
+	switch (platform) {
+		case "darwin": return {
+			args: [href],
+			file: "open"
+		};
+		case "win32": return {
+			args: [
+				"/c",
+				"start",
+				"",
+				href
+			],
+			file: "cmd"
+		};
+		default: return {
+			args: [href],
+			file: "xdg-open"
+		};
+	}
+}
+async function openExternalUrl(url, options = {}) {
+	const command = getBrowserOpenCommand(url, options.platform);
+	await (options.run ?? (async (file, args) => {
+		await execFileAsync(file, args);
+	}))(command.file, command.args);
+}
+//#endregion
+//#region src/commands/web.ts
+function webHelp() {
+	return `Granola web
+
+Usage:
+  granola web [options]
+
+Options:
+  --hostname <value>      Hostname to bind (default: 127.0.0.1)
+  --port <value>          Port to bind (default: 0 for any available port)
+  --cache <path>          Path to Granola cache JSON
+  --timeout <value>       Request timeout, e.g. 2m, 30s, 120000 (default: 2m)
+  --supabase <path>       Path to supabase.json
+  --open[=true|false]     Open the browser automatically (default: true)
+  --debug                 Enable debug logging
+  --config <path>         Path to .granola.toml
+  -h, --help              Show help
+`;
+}
+//#endregion
 //#region src/commands/index.ts
 const commands = [
 	authCommand,
 	meetingCommand,
 	notesCommand,
-	transcriptsCommand
+	serveCommand,
+	transcriptsCommand,
+	{
+		description: "Start the Granola Toolkit web workspace",
+		flags: {
+			cache: { type: "string" },
+			help: { type: "boolean" },
+			hostname: { type: "string" },
+			open: { type: "boolean" },
+			port: { type: "string" },
+			timeout: { type: "string" }
+		},
+		help: webHelp,
+		name: "web",
+		async run({ commandFlags, globalFlags }) {
+			const config = await loadConfig({
+				globalFlags,
+				subcommandFlags: commandFlags
+			});
+			debug(config.debug, "using config", config.configFileUsed ?? "(none)");
+			debug(config.debug, "supabase", config.supabase);
+			debug(config.debug, "cacheFile", config.transcripts.cacheFile || "(none)");
+			debug(config.debug, "timeoutMs", config.notes.timeoutMs);
+			const app = await createGranolaApp(config, { surface: "web" });
+			const hostname = pickHostname(commandFlags.hostname);
+			const port = parsePort(commandFlags.port);
+			const openBrowser = commandFlags.open !== false;
+			const server = await startGranolaServer(app, {
+				enableWebClient: true,
+				hostname,
+				port
+			});
+			console.log(`Granola Toolkit web workspace listening on ${server.url.href}`);
+			console.log("Routes:");
+			console.log("  GET  /");
+			console.log("  GET  /health");
+			console.log("  GET  /state");
+			console.log("  GET  /events");
+			console.log("  GET  /meetings");
+			console.log("  GET  /meetings/:id");
+			console.log("  POST /exports/notes");
+			console.log("  POST /exports/transcripts");
+			if (openBrowser) try {
+				await openExternalUrl(server.url);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				console.error(`failed to open browser automatically: ${message}`);
+				console.error(`open ${server.url.href} manually`);
+			}
+			await waitForShutdown(async () => await server.close());
+			return 0;
+		}
+	}
 ];
 const commandMap = new Map(commands.map((command) => [command.name, command]));
 //#endregion

package/package.json

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