granola-toolkit 0.1.0

package/README.md

@@ -0,0 +1,218 @@
+# granola-toolkit
+
+General toolkit to do more with Granola notes and transcripts.
+
+## Install
+
+From npm:
+
+```bash
+npm install -g granola-toolkit
+granola --help
+```
+
+Without a global install:
+
+```bash
+npx granola-toolkit --help
+```
+
+For local development:
+
+```bash
+curl -fsSL https://vite.plus | bash
+vp help
+vp install
+```
+
+## Run
+
+Installed CLI:
+
+```bash
+granola --help
+granola notes --help
+granola transcripts --help
+```
+
+Local build:
+
+```bash
+vp pack
+node dist/cli.js --help
+node dist/cli.js notes --help
+node dist/cli.js transcripts --help
+```
+
+You can also use the package scripts:
+
+```bash
+npm run build
+npm run notes -- --help
+npm run transcripts -- --help
+```
+
+## Examples
+
+Export notes:
+
+```bash
+node dist/cli.js notes --supabase "$HOME/Library/Application Support/Granola/supabase.json"
+```
+
+Export transcripts:
+
+```bash
+node dist/cli.js transcripts --cache "$HOME/Library/Application Support/Granola/cache-v3.json"
+```
+
+## How It Works
+
+### Notes
+
+`notes` exports Granola's generated meeting notes, not the raw transcript.
+
+The flow is:
+
+1. read your local `supabase.json`
+2. extract the WorkOS access token from it
+3. call Granola's paginated documents API
+4. choose the best available note content for each document
+5. convert ProseMirror content into Markdown
+6. write one Markdown file per document into the output directory
+
+Content is chosen in this order:
+
+1. `notes`
+2. `last_viewed_panel.content`
+3. `last_viewed_panel.original_content`
+4. raw `content`
+
+Each note file includes:
+
+- YAML frontmatter with the document id, created timestamp, updated timestamp, and tags
+- a top-level heading from the note title
+- converted note body content
+
+### Transcripts
+
+`transcripts` exports Granola's locally cached transcript segments.
+
+The flow is:
+
+1. read Granola's cache JSON from disk
+2. parse the cache payload, whether it is double-encoded or already an object
+3. match transcript segments to documents by document id
+4. format segments as `[HH:MM:SS] Speaker: Text`
+5. write one `.txt` file per document into the output directory
+
+Speaker labels are currently normalised to:
+
+- `You` for `microphone`
+- `System` for everything else
+
+### Incremental Writes
+
+Both commands are incremental. They only rewrite an export file when the source document appears newer than the file already on disk.
+
+That means repeated runs are cheap, and you can safely point the CLI at the same output directory over time.
+
+## Config
+
+The CLI reads configuration in this order:
+
+1. command-line flags
+2. environment variables
+3. `.granola.toml`
+4. platform defaults
+
+Supported config keys:
+
+```toml
+debug = true
+supabase = "/Users/yourname/Library/Application Support/Granola/supabase.json"
+output = "./notes"
+timeout = "2m"
+cache-file = "/Users/yourname/Library/Application Support/Granola/cache-v3.json"
+transcript-output = "./transcripts"
+```
+
+Supported environment variables:
+
+- `DEBUG_MODE`
+- `SUPABASE_FILE`
+- `OUTPUT`
+- `TIMEOUT`
+- `CACHE_FILE`
+- `TRANSCRIPT_OUTPUT`
+
+## What Changed In The Port
+
+This port deliberately preserves the Go repo's architecture, but it also fixes a few obvious rough edges instead of copying them blindly:
+
+- deterministic export ordering, so duplicate-title suffixes are stable across runs
+- shared filename sanitisation between notes and transcripts
+- cross-platform default path discovery for both `supabase.json` and cache files
+- HTML fallback for note export is converted into readable Markdown-ish text instead of being dumped raw
+- transcript timestamps preserve the original clock time instead of being normalised to UTC
+
+## Verify
+
+```bash
+vp check
+vp test
+vp pack
+npm pack --dry-run
+```
+
+`vp build` is for web apps. This repo publishes a CLI bundle, so the correct build step here is `vp pack`.
+
+## Publishing
+
+Any push to `main` with a package version that is not already on npm becomes a publish candidate automatically. The workflow verifies the build, checks whether `package.json` contains an unpublished version, and then pauses in the `production` environment until someone approves the deployment review in GitHub.
+
+That means you can use either flow:
+
+- merge a PR that already includes the version bump
+- run the local release helper on `main`
+
+Local release helper:
+
+```bash
+npm run release
+```
+
+That script:
+
+1. verifies the git working tree is clean
+2. verifies you are on `main`
+3. bumps the package version with `npm version --no-git-tag-version`
+4. commits and pushes the release commit
+5. lets the push-to-`main` workflow create a publish candidate automatically
+
+You can also choose the bump type explicitly:
+
+```bash
+npm run release patch
+npm run release minor
+npm run release major
+```
+
+The GitHub Actions release job then:
+
+- installs dependencies with Vite+ via `setup-vp`
+- runs `vp check`, `vp test`, `vp pack`, and `npm pack --dry-run`
+- checks npm first and skips the publish job if that exact version already exists
+- waits for approval on the `production` environment before npm credentials are exposed
+- publishes to npm using `NPM_TOKEN`
+- tags the published version as `v<version>`
+
+### GitHub Setup
+
+To get the review dialog you showed in the screenshots, configure this once in GitHub:
+
+1. create a `production` environment in repository Settings -> Environments
+2. add required reviewers to that environment
+3. add `NPM_TOKEN` as an environment secret on `production`
+
+After that, merges to `main` that contain a new unpublished version will stop at "Review deployments". Approving that deployment is what allows the npm publish step to run.

package/dist/cli.js

@@ -0,0 +1,788 @@
+#!/usr/bin/env node
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+//#region src/utils.ts
+const INVALID_FILENAME_CHARS = /[<>:"/\\|?*]/g;
+const CONTROL_CHARACTERS = /\p{Cc}/gu;
+const MULTIPLE_UNDERSCORES = /_+/g;
+const MULTIPLE_BLANK_LINES = /\n{3,}/g;
+function normaliseNewlines(value) {
+	return value.replace(/\r\n?/g, "\n");
+}
+function quoteYamlString(value) {
+	return JSON.stringify(value);
+}
+function sanitiseFilename(name, fallback = "untitled") {
+	return (name.trim().replace(INVALID_FILENAME_CHARS, "_").replace(CONTROL_CHARACTERS, "_").replace(MULTIPLE_UNDERSCORES, "_").replace(/^_+|_+$/g, "") || fallback).slice(0, 100);
+}
+function makeUniqueFilename(filename, used) {
+	const currentCount = used.get(filename) ?? 0;
+	if (currentCount === 0) {
+		used.set(filename, 1);
+		return filename;
+	}
+	const unique = `${filename}_${currentCount + 1}`;
+	used.set(filename, currentCount + 1);
+	used.set(unique, 1);
+	return unique;
+}
+function compareStrings(left, right) {
+	return left.localeCompare(right, void 0, {
+		numeric: true,
+		sensitivity: "base"
+	});
+}
+function firstExistingPath(candidates) {
+	for (const candidate of candidates) if (existsSync(candidate)) return candidate;
+	return candidates[0];
+}
+function granolaSupabaseCandidates() {
+	const home = homedir();
+	const appData = process.env.APPDATA;
+	switch (process.platform) {
+		case "darwin": return [join(home, "Library", "Application Support", "Granola", "supabase.json")];
+		case "win32": return appData ? [join(appData, "Granola", "supabase.json")] : [];
+		default: return [join(home, ".config", "Granola", "supabase.json"), join(home, ".local", "share", "Granola", "supabase.json")];
+	}
+}
+function granolaCacheCandidates() {
+	const home = homedir();
+	const appData = process.env.APPDATA;
+	switch (process.platform) {
+		case "darwin": return [
+			join(home, "Library", "Application Support", "Granola", "cache-v3.json"),
+			join(home, "Library", "Application Support", "Granola", "cache-v6.json"),
+			join(home, "Library", "Application Support", "Granola", "cache.json")
+		];
+		case "win32": return appData ? [
+			join(appData, "Granola", "cache-v3.json"),
+			join(appData, "Granola", "cache-v6.json"),
+			join(appData, "Granola", "cache.json")
+		] : [];
+		default: return [
+			join(home, ".config", "Granola", "cache-v3.json"),
+			join(home, ".config", "Granola", "cache-v6.json"),
+			join(home, ".config", "Granola", "cache.json"),
+			join(home, ".local", "share", "Granola", "cache-v3.json"),
+			join(home, ".local", "share", "Granola", "cache-v6.json"),
+			join(home, ".local", "share", "Granola", "cache.json")
+		];
+	}
+}
+function parseDuration(value) {
+	const trimmed = value.trim();
+	if (/^\d+$/.test(trimmed)) return Number(trimmed);
+	const parts = [...trimmed.matchAll(/(\d+(?:\.\d+)?)(ms|s|m|h|d)/g)];
+	if (parts.length === 0) throw new Error(`invalid duration: ${value}`);
+	if (parts.reduce((total, match) => total + match[0].length, 0) !== trimmed.length) throw new Error(`invalid duration: ${value}`);
+	const units = {
+		d: 1440 * 60 * 1e3,
+		h: 3600 * 1e3,
+		m: 60 * 1e3,
+		ms: 1,
+		s: 1e3
+	};
+	return parts.reduce((total, match) => {
+		const amount = Number(match[1]);
+		const multiplier = units[match[2]];
+		if (multiplier == null) throw new Error(`invalid duration: ${value}`);
+		return total + amount * multiplier;
+	}, 0);
+}
+function asRecord(value) {
+	if (value && typeof value === "object" && !Array.isArray(value)) return value;
+}
+function stringValue(value) {
+	return typeof value === "string" ? value : "";
+}
+function stringArray(value) {
+	if (!Array.isArray(value)) return [];
+	return value.filter((item) => typeof item === "string");
+}
+function parseJsonString(value) {
+	try {
+		return JSON.parse(value);
+	} catch {
+		return;
+	}
+}
+function formatTimestampForTranscript(timestamp) {
+	const inlineMatch = timestamp.match(/T(\d{2}:\d{2}:\d{2})/);
+	if (inlineMatch?.[1]) return inlineMatch[1];
+	const parsed = new Date(timestamp);
+	if (Number.isNaN(parsed.getTime())) return timestamp;
+	return parsed.toISOString().slice(11, 19);
+}
+function decodeHtmlEntities(value) {
+	return value.replaceAll("&nbsp;", " ").replaceAll("&amp;", "&").replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&quot;", "\"").replaceAll("&#39;", "'");
+}
+function htmlToMarkdownFallback(value) {
+	let output = normaliseNewlines(decodeHtmlEntities(value));
+	output = output.replace(/<br\s*\/?>/gi, "\n");
+	output = output.replace(/<li\b[^>]*>/gi, "- ");
+	output = output.replace(/<\/li>/gi, "\n");
+	output = output.replace(/<h1\b[^>]*>/gi, "# ");
+	output = output.replace(/<h2\b[^>]*>/gi, "## ");
+	output = output.replace(/<h3\b[^>]*>/gi, "### ");
+	output = output.replace(/<h4\b[^>]*>/gi, "#### ");
+	output = output.replace(/<h5\b[^>]*>/gi, "##### ");
+	output = output.replace(/<h6\b[^>]*>/gi, "###### ");
+	output = output.replace(/<\/(p|div|section|article|ul|ol|blockquote|h[1-6])>/gi, "\n\n");
+	output = output.replace(/<[^>]+>/g, "");
+	output = output.replace(/[ \t]+\n/g, "\n");
+	output = output.replace(MULTIPLE_BLANK_LINES, "\n\n");
+	return output.trim();
+}
+function latestDocumentTimestamp(document) {
+	const candidates = [
+		document.updatedAt,
+		document.lastViewedPanel?.updatedAt,
+		document.lastViewedPanel?.contentUpdatedAt
+	].filter((value) => Boolean(value));
+	candidates.sort((left, right) => {
+		const leftTime = new Date(left).getTime();
+		return new Date(right).getTime() - leftTime;
+	});
+	return candidates[0] ?? document.updatedAt;
+}
+async function shouldWriteFile(filePath, updatedAt) {
+	try {
+		const existing = await stat(filePath);
+		const updatedTime = new Date(updatedAt);
+		if (Number.isNaN(updatedTime.getTime())) return true;
+		return updatedTime.getTime() > existing.mtime.getTime();
+	} catch {
+		return true;
+	}
+}
+async function writeTextFile(filePath, content) {
+	await mkdir(dirname(filePath), { recursive: true });
+	await writeFile(filePath, content, "utf8");
+}
+async function ensureDirectory(pathname) {
+	await mkdir(pathname, { recursive: true });
+}
+async function readUtf8(pathname) {
+	return await readFile(pathname, "utf8");
+}
+function transcriptSpeakerLabel(segment) {
+	return segment.source === "microphone" ? "You" : "System";
+}
+//#endregion
+//#region src/api.ts
+const USER_AGENT = "Granola/5.354.0";
+const CLIENT_VERSION = "5.354.0";
+const DOCUMENTS_URL = "https://api.granola.ai/v2/get-documents";
+function parseProseMirrorDoc(value, options = {}) {
+	if (value == null) return;
+	if (typeof value === "string") {
+		const trimmed = value.trim();
+		if (!trimmed) return;
+		if (options.skipHtmlStrings && trimmed.startsWith("<")) return;
+		const parsed = parseJsonString(trimmed);
+		if (!parsed) return;
+		return parseProseMirrorDoc(parsed, options);
+	}
+	const record = asRecord(value);
+	if (!record || record.type !== "doc") return;
+	return record;
+}
+function parseLastViewedPanel(value) {
+	const panel = asRecord(value);
+	if (!panel) return;
+	return {
+		affinityNoteId: stringValue(panel.affinity_note_id),
+		content: parseProseMirrorDoc(panel.content, { skipHtmlStrings: true }),
+		contentUpdatedAt: stringValue(panel.content_updated_at),
+		createdAt: stringValue(panel.created_at),
+		deletedAt: stringValue(panel.deleted_at),
+		documentId: stringValue(panel.document_id),
+		generatedLines: Array.isArray(panel.generated_lines) ? panel.generated_lines : [],
+		id: stringValue(panel.id),
+		lastViewedAt: stringValue(panel.last_viewed_at),
+		originalContent: stringValue(panel.original_content),
+		suggestedQuestions: panel.suggested_questions,
+		templateSlug: stringValue(panel.template_slug),
+		title: stringValue(panel.title),
+		updatedAt: stringValue(panel.updated_at)
+	};
+}
+function getAccessToken(supabaseContents) {
+	const wrapper = parseJsonString(supabaseContents);
+	if (!wrapper) throw new Error("failed to parse supabase.json");
+	const workosTokens = wrapper.workos_tokens;
+	let tokenPayload;
+	if (typeof workosTokens === "string") tokenPayload = parseJsonString(workosTokens);
+	else tokenPayload = asRecord(workosTokens);
+	const accessToken = tokenPayload ? stringValue(tokenPayload.access_token) : "";
+	if (!accessToken.trim()) throw new Error("access token not found in supabase.json");
+	return accessToken;
+}
+function parseDocument(value) {
+	const record = asRecord(value);
+	if (!record) throw new Error("document payload is not an object");
+	return {
+		content: stringValue(record.content),
+		createdAt: stringValue(record.created_at),
+		id: stringValue(record.id),
+		lastViewedPanel: parseLastViewedPanel(record.last_viewed_panel),
+		notes: parseProseMirrorDoc(record.notes),
+		notesPlain: stringValue(record.notes_plain),
+		tags: stringArray(record.tags),
+		title: stringValue(record.title),
+		updatedAt: stringValue(record.updated_at)
+	};
+}
+async function fetchDocuments(options) {
+	const fetchImpl = options.fetchImpl ?? fetch;
+	const accessToken = getAccessToken(options.supabaseContents);
+	const documents = [];
+	const url = options.url ?? DOCUMENTS_URL;
+	const limit = 100;
+	let offset = 0;
+	for (;;) {
+		const signal = AbortSignal.timeout(options.timeoutMs);
+		const response = await fetchImpl(url, {
+			body: JSON.stringify({
+				include_last_viewed_panel: true,
+				limit,
+				offset
+			}),
+			headers: {
+				Accept: "*/*",
+				Authorization: `Bearer ${accessToken}`,
+				"Content-Type": "application/json",
+				"User-Agent": USER_AGENT,
+				"X-Client-Version": CLIENT_VERSION
+			},
+			method: "POST",
+			signal
+		});
+		if (!response.ok) {
+			const body = (await response.text()).slice(0, 500);
+			throw new Error(`failed to get documents: ${response.status} ${response.statusText}${body ? `: ${body}` : ""}`);
+		}
+		const payload = await response.json();
+		if (!Array.isArray(payload.docs)) throw new Error("failed to parse documents response");
+		const page = payload.docs.map(parseDocument);
+		documents.push(...page);
+		if (page.length < limit) break;
+		offset += limit;
+	}
+	return documents;
+}
+//#endregion
+//#region src/cache.ts
+function parseCacheDocument(id, value) {
+	const record = asRecord(value);
+	if (!record) return;
+	return {
+		createdAt: stringValue(record.created_at),
+		id,
+		title: stringValue(record.title),
+		updatedAt: stringValue(record.updated_at)
+	};
+}
+function parseTranscriptSegments(value) {
+	if (!Array.isArray(value)) return;
+	return value.flatMap((segment) => {
+		const record = asRecord(segment);
+		if (!record) return [];
+		return [{
+			documentId: stringValue(record.document_id),
+			endTimestamp: stringValue(record.end_timestamp),
+			id: stringValue(record.id),
+			isFinal: Boolean(record.is_final),
+			source: stringValue(record.source),
+			startTimestamp: stringValue(record.start_timestamp),
+			text: stringValue(record.text)
+		}];
+	});
+}
+function parseCacheContents(contents) {
+	const outer = parseJsonString(contents);
+	if (!outer) throw new Error("failed to parse cache JSON");
+	const rawCache = outer.cache;
+	let cachePayload;
+	if (typeof rawCache === "string") cachePayload = parseJsonString(rawCache);
+	else cachePayload = asRecord(rawCache);
+	const state = cachePayload ? asRecord(cachePayload.state) : void 0;
+	if (!state) throw new Error("failed to parse cache state");
+	const rawDocuments = asRecord(state.documents) ?? {};
+	const rawTranscripts = asRecord(state.transcripts) ?? {};
+	const documents = {};
+	for (const [id, rawDocument] of Object.entries(rawDocuments)) {
+		const document = parseCacheDocument(id, rawDocument);
+		if (document) documents[id] = document;
+	}
+	const transcripts = {};
+	for (const [id, rawTranscript] of Object.entries(rawTranscripts)) {
+		const segments = parseTranscriptSegments(rawTranscript);
+		if (segments) transcripts[id] = segments;
+	}
+	return {
+		documents,
+		transcripts
+	};
+}
+//#endregion
+//#region src/config.ts
+function pickString(value) {
+	return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function pickBoolean(value) {
+	return typeof value === "boolean" ? value : void 0;
+}
+function parseTomlScalar(rawValue) {
+	const value = rawValue.trim();
+	if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) {
+		if (value.startsWith("\"")) try {
+			return JSON.parse(value);
+		} catch {
+			return value.slice(1, -1);
+		}
+		return value.slice(1, -1);
+	}
+	if (/^(true|false)$/i.test(value)) return value.toLowerCase() === "true";
+	if (/^-?\d+(?:\.\d+)?$/.test(value)) return Number(value);
+	return value;
+}
+function parseSimpleToml(contents) {
+	const values = {};
+	for (const rawLine of contents.split(/\r?\n/)) {
+		const line = rawLine.trim();
+		if (!line || line.startsWith("#")) continue;
+		const match = /^([A-Za-z0-9_-]+)\s*=\s*(.+)$/.exec(line);
+		if (!match) continue;
+		const [, key = "", rawValue = ""] = match;
+		values[key] = parseTomlScalar(rawValue);
+	}
+	return values;
+}
+async function loadTomlConfig(configPath) {
+	if (configPath) return {
+		path: configPath,
+		values: parseSimpleToml(await readUtf8(configPath))
+	};
+	const candidates = [join(process.cwd(), ".granola.toml"), join(homedir(), ".granola.toml")];
+	for (const candidate of candidates) if (existsSync(candidate)) return {
+		path: candidate,
+		values: parseSimpleToml(await readUtf8(candidate))
+	};
+	return { values: {} };
+}
+function envFlag(value) {
+	if (value == null) return;
+	if (/^(1|true|yes|on)$/i.test(value)) return true;
+	if (/^(0|false|no|off)$/i.test(value)) return false;
+}
+async function loadConfig(options) {
+	const env = options.env ?? process.env;
+	const config = await loadTomlConfig(pickString(options.globalFlags.config));
+	const configValues = config.values;
+	const defaultSupabase = firstExistingPath(granolaSupabaseCandidates());
+	const defaultCache = firstExistingPath(granolaCacheCandidates());
+	const timeoutValue = pickString(options.subcommandFlags.timeout) ?? pickString(env.TIMEOUT) ?? pickString(configValues.timeout) ?? "2m";
+	return {
+		configFileUsed: config.path,
+		debug: pickBoolean(options.globalFlags.debug) ?? envFlag(env.DEBUG_MODE) ?? pickBoolean(configValues.debug) ?? false,
+		notes: {
+			output: pickString(options.subcommandFlags.output) ?? pickString(env.OUTPUT) ?? pickString(configValues.output) ?? "./notes",
+			timeoutMs: parseDuration(timeoutValue)
+		},
+		supabase: pickString(options.globalFlags.supabase) ?? pickString(env.SUPABASE_FILE) ?? pickString(configValues.supabase) ?? defaultSupabase,
+		transcripts: {
+			cacheFile: pickString(options.subcommandFlags.cache) ?? pickString(env.CACHE_FILE) ?? pickString(configValues["cache-file"]) ?? pickString(configValues.cacheFile) ?? defaultCache ?? "",
+			output: pickString(options.subcommandFlags.output) ?? pickString(env.TRANSCRIPT_OUTPUT) ?? pickString(configValues["transcript-output"]) ?? pickString(configValues.transcriptOutput) ?? "./transcripts"
+		}
+	};
+}
+//#endregion
+//#region src/prosemirror.ts
+function repeatIndent(level) {
+	return "  ".repeat(level);
+}
+function renderInline(nodes = []) {
+	return nodes.map((node) => renderInlineNode(node)).join("");
+}
+function applyMarks(text, marks = []) {
+	return marks.reduce((current, mark) => {
+		switch (mark.type) {
+			case "strong": return `**${current}**`;
+			case "em": return `*${current}*`;
+			case "code": return `\`${current}\``;
+			case "strike": return `~~${current}~~`;
+			case "link": {
+				const href = typeof mark.attrs?.href === "string" ? mark.attrs.href : void 0;
+				return href ? `[${current}](${href})` : current;
+			}
+			default: return current;
+		}
+	}, text);
+}
+function renderInlineNode(node) {
+	switch (node.type) {
+		case "text": return applyMarks(node.text ?? "", node.marks);
+		case "hardBreak": return "  \n";
+		default: return applyMarks(renderInline(node.content), node.marks);
+	}
+}
+function indentLines(value, level) {
+	const indent = repeatIndent(level);
+	return value.split("\n").map((line) => line.length === 0 ? line : `${indent}${line}`).join("\n");
+}
+function renderList(items, ordered, indentLevel) {
+	return items.map((item, index) => renderListItem(item, ordered ? `${index + 1}.` : "-", indentLevel)).join("\n");
+}
+function renderListItem(node, marker, indentLevel) {
+	const children = node.content ?? [];
+	const blockChildren = children.filter((child) => child.type !== "bulletList" && child.type !== "orderedList");
+	const nestedLists = children.filter((child) => child.type === "bulletList" || child.type === "orderedList");
+	const mainText = blockChildren.map((child) => renderBlock(child, indentLevel + 1)).filter(Boolean).join("\n").trim();
+	let output = `${`${repeatIndent(indentLevel)}${marker} `}${mainText || ""}`.trimEnd();
+	if (nestedLists.length > 0) {
+		const nestedText = nestedLists.map((child) => renderBlock(child, indentLevel + 1)).filter(Boolean).map((value) => indentLines(value, 0)).join("\n");
+		output = `${output}\n${nestedText}`;
+	}
+	return output;
+}
+function renderBlock(node, indentLevel) {
+	switch (node.type) {
+		case "heading": {
+			const level = typeof node.attrs?.level === "number" ? node.attrs.level : 1;
+			return `${"#".repeat(level)} ${renderInline(node.content).trim()}`.trim();
+		}
+		case "paragraph": return renderInline(node.content).trim();
+		case "bulletList": return renderList(node.content ?? [], false, indentLevel);
+		case "orderedList": return renderList(node.content ?? [], true, indentLevel);
+		case "listItem": return renderListItem(node, "-", indentLevel);
+		case "blockquote": return renderBlocks(node.content ?? [], indentLevel).split("\n").map((line) => line ? `> ${line}` : ">").join("\n").trim();
+		case "codeBlock": return `\`\`\`\n${extractPlainText(node).trimEnd()}\n\`\`\``;
+		case "horizontalRule": return "---";
+		case "hardBreak": return "";
+		case "text": return renderInlineNode(node);
+		default:
+			if (node.content?.length) return renderBlocks(node.content, indentLevel);
+			return renderInlineNode(node).trim();
+	}
+}
+function renderBlocks(nodes, indentLevel = 0) {
+	return nodes.map((node) => renderBlock(node, indentLevel)).filter((value) => value.length > 0).join("\n\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+function extractPlainTextNode(node) {
+	switch (node.type) {
+		case "hardBreak": return "\n";
+		case "text": return node.text ?? "";
+		default: return extractPlainText({
+			type: "doc",
+			content: node.content
+		});
+	}
+}
+function convertProseMirrorToMarkdown(doc) {
+	if (!doc || doc.type !== "doc" || !doc.content?.length) return "";
+	const rendered = renderBlocks(doc.content);
+	return rendered ? `${rendered}\n` : "";
+}
+function extractPlainText(doc) {
+	if (!doc || doc.type !== "doc" || !doc.content?.length) return "";
+	return doc.content.map((node) => {
+		if (node.type === "bulletList" || node.type === "orderedList") return (node.content ?? []).map((child) => extractPlainTextNode(child)).filter(Boolean).join("\n");
+		return extractPlainTextNode(node);
+	}).filter(Boolean).join("\n\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+//#endregion
+//#region src/notes.ts
+function documentToMarkdown(document) {
+	const lines = [
+		"---",
+		`id: ${quoteYamlString(document.id)}`,
+		`created: ${quoteYamlString(document.createdAt)}`,
+		`updated: ${quoteYamlString(document.updatedAt)}`
+	];
+	if (document.tags.length > 0) {
+		lines.push("tags:");
+		for (const tag of document.tags) lines.push(`  - ${quoteYamlString(tag)}`);
+	}
+	lines.push("---", "");
+	if (document.title.trim()) lines.push(`# ${document.title.trim()}`, "");
+	const content = convertProseMirrorToMarkdown(document.notes).trim() || convertProseMirrorToMarkdown(document.lastViewedPanel?.content).trim() || htmlToMarkdownFallback(document.lastViewedPanel?.originalContent ?? "").trim() || document.content.trim();
+	if (content) lines.push(content);
+	return `${lines.join("\n").trimEnd()}\n`;
+}
+function documentFilename(document) {
+	return sanitiseFilename(document.title || document.id, "untitled");
+}
+async function writeNotes(documents, outputDir) {
+	await ensureDirectory(outputDir);
+	const sorted = [...documents].sort((left, right) => compareStrings(left.title || left.id, right.title || right.id) || compareStrings(left.id, right.id));
+	const used = /* @__PURE__ */ new Map();
+	let written = 0;
+	for (const document of sorted) {
+		const filePath = join(outputDir, `${makeUniqueFilename(documentFilename(document), used)}.md`);
+		if (!await shouldWriteFile(filePath, latestDocumentTimestamp(document))) continue;
+		await writeTextFile(filePath, documentToMarkdown(document));
+		written += 1;
+	}
+	return written;
+}
+//#endregion
+//#region src/transcripts.ts
+function formatTranscript(document, segments) {
+	if (segments.length === 0) return "";
+	const header = [
+		"=".repeat(80),
+		document.title || document.id,
+		`ID: ${document.id}`,
+		document.createdAt ? `Created: ${document.createdAt}` : "",
+		document.updatedAt ? `Updated: ${document.updatedAt}` : "",
+		`Segments: ${segments.length}`,
+		"=".repeat(80),
+		""
+	].filter(Boolean);
+	const body = segments.map((segment) => {
+		return `[${formatTimestampForTranscript(segment.startTimestamp)}] ${transcriptSpeakerLabel(segment)}: ${segment.text}`;
+	});
+	return `${[...header, ...body].join("\n").trimEnd()}\n`;
+}
+function transcriptFilename(document) {
+	return sanitiseFilename(document.title || document.id, "untitled");
+}
+async function writeTranscripts(cacheData, outputDir) {
+	await ensureDirectory(outputDir);
+	const entries = Object.entries(cacheData.transcripts).filter(([, segments]) => segments.length > 0).sort(([leftId], [rightId]) => {
+		const leftDocument = cacheData.documents[leftId];
+		const rightDocument = cacheData.documents[rightId];
+		return compareStrings(leftDocument?.title || leftId, rightDocument?.title || rightId) || compareStrings(leftId, rightId);
+	});
+	const used = /* @__PURE__ */ new Map();
+	let written = 0;
+	for (const [documentId, segments] of entries) {
+		const document = cacheData.documents[documentId] ?? {
+			createdAt: "",
+			id: documentId,
+			title: documentId,
+			updatedAt: ""
+		};
+		const filePath = join(outputDir, `${makeUniqueFilename(transcriptFilename(document), used)}.txt`);
+		if (!await shouldWriteFile(filePath, document.updatedAt)) continue;
+		const content = formatTranscript(document, segments);
+		if (!content) continue;
+		await writeTextFile(filePath, content);
+		written += 1;
+	}
+	return written;
+}
+//#endregion
+//#region src/cli.ts
+function parseBooleanValue(value) {
+	if (/^(true|1|yes|on)$/i.test(value)) return true;
+	if (/^(false|0|no|off)$/i.test(value)) return false;
+	throw new Error(`invalid boolean value: ${value}`);
+}
+function parseFlags(args, spec) {
+	const values = {};
+	const rest = [];
+	for (let index = 0; index < args.length; index += 1) {
+		const token = args[index];
+		if (token === "--") {
+			rest.push(...args.slice(index + 1));
+			break;
+		}
+		if (token === "-h") {
+			values.help = true;
+			continue;
+		}
+		if (!token.startsWith("--")) {
+			rest.push(token);
+			continue;
+		}
+		const [rawName = "", inlineValue] = token.slice(2).split("=", 2);
+		const name = rawName;
+		const definition = spec[name];
+		if (!definition) {
+			rest.push(token);
+			continue;
+		}
+		if (definition.type === "boolean") {
+			values[name] = inlineValue == null ? true : parseBooleanValue(inlineValue);
+			continue;
+		}
+		if (inlineValue != null) {
+			values[name] = inlineValue;
+			continue;
+		}
+		const next = args[index + 1];
+		if (next == null || next.startsWith("--")) throw new Error(`missing value for --${name}`);
+		values[name] = next;
+		index += 1;
+	}
+	return {
+		rest,
+		values
+	};
+}
+function splitCommand(argv) {
+	const commands = new Set(["notes", "transcripts"]);
+	const rest = [];
+	let command;
+	for (const token of argv) {
+		if (!command && !token.startsWith("-") && commands.has(token)) {
+			command = token;
+			continue;
+		}
+		rest.push(token);
+	}
+	return {
+		command,
+		rest
+	};
+}
+function rootHelp() {
+	return `Granola CLI
+
+Export your Granola notes and transcripts.
+
+Usage:
+  granola <command> [options]
+
+Commands:
+  notes        Export Granola notes to Markdown
+  transcripts  Export Granola transcripts to text files
+
+Global options:
+  --config <path>     Path to .granola.toml
+  --debug             Enable debug logging
+  --supabase <path>   Path to supabase.json
+  -h, --help          Show help
+
+Examples:
+  granola notes --supabase "${granolaSupabaseCandidates()[0] ?? "/path/to/supabase.json"}"
+  granola transcripts --cache "${granolaCacheCandidates()[0] ?? "/path/to/cache-v3.json"}"
+`;
+}
+function notesHelp() {
+	return `Granola notes
+
+Usage:
+  granola notes [options]
+
+Options:
+  --output <path>     Output directory for Markdown files (default: ./notes)
+  --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
+`;
+}
+function transcriptsHelp() {
+	return `Granola transcripts
+
+Usage:
+  granola transcripts [options]
+
+Options:
+  --cache <path>      Path to Granola cache JSON
+  --output <path>     Output directory for transcript files (default: ./transcripts)
+  --debug             Enable debug logging
+  --config <path>     Path to .granola.toml
+  -h, --help          Show help
+`;
+}
+function debug(enabled, ...values) {
+	if (enabled) console.error("[debug]", ...values);
+}
+async function runCli(argv) {
+	try {
+		const { command, rest } = splitCommand(argv);
+		const global = parseFlags(rest, {
+			config: { type: "string" },
+			debug: { type: "boolean" },
+			help: { type: "boolean" },
+			supabase: { type: "string" }
+		});
+		if (global.values.help && !command) {
+			console.log(rootHelp());
+			return 0;
+		}
+		if (!command) {
+			console.log(rootHelp());
+			return 1;
+		}
+		switch (command) {
+			case "notes": {
+				const subcommand = parseFlags(global.rest, {
+					help: { type: "boolean" },
+					output: { type: "string" },
+					timeout: { type: "string" }
+				});
+				if (subcommand.values.help || global.values.help) {
+					console.log(notesHelp());
+					return 0;
+				}
+				const config = await loadConfig({
+					globalFlags: global.values,
+					subcommandFlags: subcommand.values
+				});
+				if (!config.supabase) throw new Error(`supabase.json not found. Pass --supabase or create .granola.toml. Expected locations include: ${granolaSupabaseCandidates().join(", ")}`);
+				debug(config.debug, "using config", config.configFileUsed ?? "(none)");
+				debug(config.debug, "supabase", config.supabase);
+				debug(config.debug, "timeoutMs", config.notes.timeoutMs);
+				debug(config.debug, "output", config.notes.output);
+				console.log("Fetching documents from Granola API...");
+				const documents = await fetchDocuments({
+					supabaseContents: await readFile(config.supabase, "utf8"),
+					timeoutMs: config.notes.timeoutMs
+				});
+				console.log(`Exporting ${documents.length} notes to ${config.notes.output}...`);
+				const written = await writeNotes(documents, config.notes.output);
+				console.log("✓ Export completed successfully");
+				debug(config.debug, "notes written", written);
+				return 0;
+			}
+			case "transcripts": {
+				const subcommand = parseFlags(global.rest, {
+					cache: { type: "string" },
+					help: { type: "boolean" },
+					output: { type: "string" }
+				});
+				if (subcommand.values.help || global.values.help) {
+					console.log(transcriptsHelp());
+					return 0;
+				}
+				const config = await loadConfig({
+					globalFlags: global.values,
+					subcommandFlags: subcommand.values
+				});
+				if (!config.transcripts.cacheFile) throw new Error(`Granola cache file not found. Pass --cache or create .granola.toml. Expected locations include: ${granolaCacheCandidates().join(", ")}`);
+				debug(config.debug, "using config", config.configFileUsed ?? "(none)");
+				debug(config.debug, "cacheFile", config.transcripts.cacheFile);
+				debug(config.debug, "output", config.transcripts.output);
+				console.log("Reading Granola cache file...");
+				const cacheData = parseCacheContents(await readFile(config.transcripts.cacheFile, "utf8"));
+				const transcriptCount = Object.values(cacheData.transcripts).filter((segments) => segments.length > 0).length;
+				console.log(`Exporting ${transcriptCount} transcripts to ${config.transcripts.output}...`);
+				const written = await writeTranscripts(cacheData, config.transcripts.output);
+				console.log("✓ Export completed successfully");
+				debug(config.debug, "transcripts written", written);
+				return 0;
+			}
+			default:
+				console.log(rootHelp());
+				return 1;
+		}
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		console.error(message);
+		return 1;
+	}
+}
+//#endregion
+//#region index.ts
+const exitCode = await runCli(process.argv.slice(2));
+process.exit(exitCode);
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "granola-toolkit",
+  "version": "0.1.0",
+  "description": "CLI toolkit for exporting and working with Granola notes and transcripts",
+  "keywords": [
+    "cli",
+    "granola",
+    "notes",
+    "transcripts"
+  ],
+  "homepage": "https://github.com/kkarimi/granola-toolkit#readme",
+  "bugs": {
+    "url": "https://github.com/kkarimi/granola-toolkit/issues"
+  },
+  "author": "Nima Karimi",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:kkarimi/granola-toolkit.git"
+  },
+  "bin": {
+    "granola": "dist/cli.js"
+  },
+  "files": [
+    "README.md",
+    "dist/cli.js"
+  ],
+  "type": "module",
+  "main": "dist/cli.js",
+  "module": "dist/cli.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "check": "vp check",
+    "dev": "vp pack --watch",
+    "fmt": "vp fmt",
+    "lint": "vp lint",
+    "pack:dry-run": "npm pack --dry-run",
+    "prepublishOnly": "vp pack",
+    "release": "node scripts/release.mjs",
+    "start": "node dist/cli.js",
+    "notes": "node dist/cli.js notes",
+    "transcripts": "node dist/cli.js transcripts",
+    "test": "vp test",
+    "typecheck": "vp exec tsc --noEmit",
+    "prepare": "vp config"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "typescript": "^5.9.3",
+    "vite-plus": "0.1.15"
+  },
+  "overrides": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@latest",
+    "vitest": "npm:@voidzero-dev/vite-plus-test@latest"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "packageManager": "npm@11.7.0"
+}