granola-toolkit 0.33.0 → 0.34.1

package/README.md

@@ -79,6 +79,7 @@ Export notes:
 ```bash
 granola auth login
 granola notes
+granola notes --folder Team
 
 node dist/cli.js notes --supabase "$HOME/Library/Application Support/Granola/supabase.json"
 node dist/cli.js notes --format json --output ./notes-json
@@ -91,6 +92,7 @@ Export transcripts:
 ```bash
 node dist/cli.js transcripts --cache "$HOME/Library/Application Support/Granola/cache-v3.json"
 node dist/cli.js transcripts --format yaml --output ./transcripts-yaml
+granola transcripts --folder Team
 ```
 
 Inspect individual meetings:
@@ -143,6 +145,8 @@ The flow is:
 6. render that export as Markdown, JSON, YAML, or raw JSON
 7. write one file per document into the output directory
 
+When you pass `--folder <id|name>`, the export is filtered to that folder and, by default, written into a stable per-folder subdirectory under the notes output root.
+
 Content is chosen in this order:
 
 1. `notes`
@@ -169,6 +173,8 @@ The flow is:
 5. render each export as text, JSON, YAML, or raw JSON
 6. write one file per document into the output directory
 
+When you pass `--folder <id|name>`, the export is filtered to that folder and, by default, written into a stable per-folder subdirectory under the transcripts output root.
+
 Speaker labels are currently normalised to:
 
 - `You` for `microphone`
@@ -223,6 +229,8 @@ The current CLI surface includes:
 - `folder list`
 - `folder view <id|name>`
 - `meeting list --folder <id|name>`
+- `notes --folder <id|name>`
+- `transcripts --folder <id|name>`
 
 ### Server
 
@@ -250,9 +258,9 @@ The initial server API includes:
 - `POST /auth/logout`
 - `POST /auth/mode`
 - `POST /auth/refresh`
-- `POST /exports/notes`
+- `POST /exports/notes` with optional `folderId`
 - `POST /exports/jobs/:id/rerun`
-- `POST /exports/transcripts`
+- `POST /exports/transcripts` with optional `folderId`
 
 This is the shared runtime for `granola web` and `granola attach`.
 
@@ -287,6 +295,7 @@ The initial browser client includes:
 - app-state status from the shared core
 - an auth session panel for login, refresh, source switching, and sign-out
 - note and transcript export actions backed by the same local API
+- folder-scoped export actions that follow the currently selected folder
 - a recent export-jobs panel with rerun actions
 - stronger empty and error states for list/detail failures
 - a server-access panel that can unlock or lock a password-protected local server
@@ -354,6 +363,7 @@ The web client uses the index as a fast path and upgrades to live data automatic
 Exports are now tracked as jobs with:
 
 - persistent local history across CLI and web runs
+- explicit scope metadata for all-meetings and folder-scoped runs
 - running, completed, and failed status
 - per-export progress counters
 - rerun support from `granola exports rerun <job-id>` or the web client
@@ -439,6 +449,7 @@ Before pushing changes, run:
 ```bash
 vp check
 vp test
+npm run coverage
 vp pack
 npm pack --dry-run
 ```
@@ -447,6 +458,7 @@ What those do:
 
 - `vp check`: formatting, linting, and type checks
 - `vp test`: unit tests
+- `npm run coverage`: unit tests plus a local coverage report in `coverage/coverage-summary.json`
 - `vp pack`: builds the CLI bundle into `dist/cli.js`
 - `npm pack --dry-run`: shows the exact npm package contents without publishing
 

package/dist/cli.js

@@ -218,16 +218,22 @@ var GranolaServerClient = class GranolaServerClient {
 	async listExportJobs(options = {}) {
 		return await this.requestJson(granolaExportJobsPath(options));
 	}
-	async exportNotes(format = "markdown") {
+	async exportNotes(format = "markdown", options = {}) {
 		return await this.requestJson(granolaTransportPaths.exportNotes, {
-			body: JSON.stringify({ format }),
+			body: JSON.stringify({
+				folderId: options.folderId,
+				format
+			}),
 			headers: { "content-type": "application/json" },
 			method: "POST"
 		});
 	}
-	async exportTranscripts(format = "text") {
+	async exportTranscripts(format = "text", options = {}) {
 		return await this.requestJson(granolaTransportPaths.exportTranscripts, {
-			body: JSON.stringify({ format }),
+			body: JSON.stringify({
+				folderId: options.folderId,
+				format
+			}),
 			headers: { "content-type": "application/json" },
 			method: "POST"
 		});
@@ -2974,6 +2980,42 @@ async function loadOptionalGranolaCache(cacheFile) {
 	return parseCacheContents(await readFile(cacheFile, "utf8"));
 }
 //#endregion
+//#region src/export-scope.ts
+const FOLDER_EXPORT_DIRECTORY = "_folders";
+function allExportScope() {
+	return { mode: "all" };
+}
+function folderExportScope(folder) {
+	return {
+		folderId: folder.id,
+		folderName: folder.name || folder.id,
+		mode: "folder"
+	};
+}
+function cloneExportScope(scope) {
+	return scope.mode === "folder" ? { ...scope } : { mode: "all" };
+}
+function normaliseExportScope(value) {
+	const record = asRecord(value);
+	if (!record) return allExportScope();
+	if (record.mode !== "folder") return allExportScope();
+	const folderId = stringValue(record.folderId);
+	const folderName = stringValue(record.folderName) || folderId;
+	if (!folderId) return allExportScope();
+	return {
+		folderId,
+		folderName,
+		mode: "folder"
+	};
+}
+function renderExportScopeLabel(scope) {
+	return scope.mode === "folder" ? `folder ${scope.folderName}` : "all meetings";
+}
+function resolveExportOutputDir(outputDir, scope, options = {}) {
+	if (scope.mode !== "folder" || options.scopedDirectory === false) return outputDir;
+	return join(outputDir, FOLDER_EXPORT_DIRECTORY, sanitiseFilename(scope.folderId, "folder"));
+}
+//#endregion
 //#region src/export-jobs.ts
 const EXPORT_JOBS_VERSION = 1;
 const MAX_EXPORT_JOBS = 100;
@@ -2999,6 +3041,7 @@ function normaliseJob(value) {
 		itemCount,
 		kind,
 		outputDir,
+		scope: normaliseExportScope(record.scope),
 		startedAt,
 		status,
 		written
@@ -3209,10 +3252,16 @@ function transcriptCount(cacheData) {
 	return Object.values(cacheData.transcripts).filter((segments) => segments.length > 0).length;
 }
 function cloneExportState(state) {
-	return state ? { ...state } : void 0;
+	return state ? {
+		...state,
+		scope: cloneExportScope(state.scope)
+	} : void 0;
 }
 function cloneExportJob(job) {
-	return { ...job };
+	return {
+		...job,
+		scope: cloneExportScope(job.scope)
+	};
 }
 function cloneFolderSummary(folder) {
 	return { ...folder };
@@ -3463,7 +3512,7 @@ var GranolaApp = class {
 		this.emitStateUpdate();
 		return cloneExportJob(job);
 	}
-	async startExportJob(kind, format, itemCount, outputDir) {
+	async startExportJob(kind, format, itemCount, outputDir, scope) {
 		return await this.updateExportJob({
 			completedCount: 0,
 			format,
@@ -3471,6 +3520,7 @@ var GranolaApp = class {
 			itemCount,
 			kind,
 			outputDir,
+			scope: cloneExportScope(scope),
 			startedAt: this.nowIso(),
 			status: "running",
 			written: 0
@@ -3740,25 +3790,29 @@ var GranolaApp = class {
 		this.setUiState({ view: "exports-history" });
 		return { jobs };
 	}
-	async exportNotes(format = "markdown") {
+	async exportNotes(format = "markdown", options = {}) {
+		const documents = await this.listDocuments();
+		const exportContext = await this.resolveExportContext(options.folderId);
+		const filteredDocuments = exportContext.documentIds ? documents.filter((document) => exportContext.documentIds.has(document.id)) : documents;
 		return await this.runNotesExport({
+			documents: filteredDocuments,
 			format,
-			outputDir: this.config.notes.output
+			outputDir: resolveExportOutputDir(options.outputDir ?? this.config.notes.output, exportContext.scope, { scopedDirectory: options.scopedOutput }),
+			scope: exportContext.scope
 		});
 	}
 	async runNotesExport(options) {
-		const documents = await this.listDocuments();
-		let job = await this.startExportJob("notes", options.format, documents.length, options.outputDir);
+		let job = await this.startExportJob("notes", options.format, options.documents.length, options.outputDir, options.scope);
 		let written = 0;
 		try {
-			written = await writeNotes(documents, options.outputDir, options.format, { onProgress: async (progress) => {
+			written = await writeNotes(options.documents, options.outputDir, options.format, { onProgress: async (progress) => {
 				job = await this.setExportJobProgress(job, {
 					completedCount: progress.completed,
 					written: progress.written
 				});
 			} });
 			job = await this.completeExportJob(job, {
-				completedCount: documents.length,
+				completedCount: options.documents.length,
 				written
 			});
 		} catch (error) {
@@ -3767,37 +3821,49 @@ var GranolaApp = class {
 		}
 		this.#state.exports.notes = {
 			format: options.format,
-			itemCount: documents.length,
+			itemCount: options.documents.length,
 			jobId: job.id,
 			outputDir: options.outputDir,
 			ranAt: this.nowIso(),
+			scope: cloneExportScope(options.scope),
 			written
 		};
 		this.emitStateUpdate();
-		this.setUiState({ view: "notes-export" });
+		this.setUiState({
+			selectedFolderId: options.scope.mode === "folder" ? options.scope.folderId : void 0,
+			view: "notes-export"
+		});
 		return {
-			documentCount: documents.length,
-			documents,
+			documentCount: options.documents.length,
+			documents: options.documents,
 			format: options.format,
 			job,
 			outputDir: options.outputDir,
+			scope: cloneExportScope(options.scope),
 			written
 		};
 	}
-	async exportTranscripts(format = "text") {
+	async exportTranscripts(format = "text", options = {}) {
+		const cacheData = await this.loadCache({ required: true });
+		if (!cacheData) throw this.missingCacheError();
+		const exportContext = await this.resolveExportContext(options.folderId);
+		const scopedCacheData = exportContext.documentIds ? {
+			documents: Object.fromEntries(Object.entries(cacheData.documents).filter(([id]) => exportContext.documentIds.has(id))),
+			transcripts: Object.fromEntries(Object.entries(cacheData.transcripts).filter(([id]) => exportContext.documentIds.has(id)))
+		} : cacheData;
 		return await this.runTranscriptsExport({
+			cacheData: scopedCacheData,
 			format,
-			outputDir: this.config.transcripts.output
+			outputDir: resolveExportOutputDir(options.outputDir ?? this.config.transcripts.output, exportContext.scope, { scopedDirectory: options.scopedOutput }),
+			scope: exportContext.scope
 		});
 	}
 	async runTranscriptsExport(options) {
-		const cacheData = await this.loadCache({ required: true });
-		if (!cacheData) throw this.missingCacheError();
-		const count = transcriptCount(cacheData);
-		let job = await this.startExportJob("transcripts", options.format, count, options.outputDir);
+		const count = transcriptCount(options.cacheData);
+		let job = await this.startExportJob("transcripts", options.format, count, options.outputDir, options.scope);
 		let written = 0;
 		try {
-			written = await writeTranscripts(cacheData, options.outputDir, options.format, { onProgress: async (progress) => {
+			written = await writeTranscripts(options.cacheData, options.outputDir, options.format, { onProgress: async (progress) => {
 				job = await this.setExportJobProgress(job, {
 					completedCount: progress.completed,
 					written: progress.written
@@ -3817,15 +3883,20 @@ var GranolaApp = class {
 			jobId: job.id,
 			outputDir: options.outputDir,
 			ranAt: this.nowIso(),
+			scope: cloneExportScope(options.scope),
 			written
 		};
 		this.emitStateUpdate();
-		this.setUiState({ view: "transcripts-export" });
+		this.setUiState({
+			selectedFolderId: options.scope.mode === "folder" ? options.scope.folderId : void 0,
+			view: "transcripts-export"
+		});
 		return {
-			cacheData,
+			cacheData: options.cacheData,
 			format: options.format,
 			job,
 			outputDir: options.outputDir,
+			scope: cloneExportScope(options.scope),
 			transcriptCount: count,
 			written
 		};
@@ -3833,15 +3904,28 @@ var GranolaApp = class {
 	async rerunExportJob(id) {
 		const job = this.#state.exports.jobs.find((candidate) => candidate.id === id);
 		if (!job) throw new Error(`export job not found: ${id}`);
-		if (job.kind === "notes") return await this.runNotesExport({
-			format: job.format,
-			outputDir: job.outputDir
+		if (job.kind === "notes") return await this.exportNotes(job.format, {
+			folderId: job.scope.mode === "folder" ? job.scope.folderId : void 0,
+			outputDir: job.outputDir,
+			scopedOutput: false
 		});
-		return await this.runTranscriptsExport({
-			format: job.format,
-			outputDir: job.outputDir
+		return await this.exportTranscripts(job.format, {
+			folderId: job.scope.mode === "folder" ? job.scope.folderId : void 0,
+			outputDir: job.outputDir,
+			scopedOutput: false
 		});
 	}
+	async resolveExportContext(folderId) {
+		if (!folderId) return { scope: allExportScope() };
+		const folders = await this.loadFolders({ required: true });
+		const summary = resolveFolder((folders ?? []).map((folder) => buildFolderSummary(folder)), folderId);
+		const rawFolder = (folders ?? []).find((candidate) => candidate.id === summary.id);
+		if (!rawFolder) throw new Error(`folder not found: ${folderId}`);
+		return {
+			documentIds: new Set(rawFolder.documentIds),
+			scope: folderExportScope(summary)
+		};
+	}
 };
 async function createGranolaApp(config, options = {}) {
 	const auth = await inspectDefaultGranolaAuth(config);
@@ -4132,8 +4216,8 @@ function renderExportJobs(jobs, format) {
 	if (format === "json") return toJson({ jobs });
 	if (format === "yaml") return toYaml({ jobs });
 	if (jobs.length === 0) return "No export jobs\n";
-	return `${["ID                           KIND         STATUS      FORMAT      ITEMS   WRITTEN  STARTED", ...jobs.map((job) => {
-		return `${job.id.padEnd(28).slice(0, 28)} ${job.kind.padEnd(12)} ${job.status.padEnd(11)} ${job.format.padEnd(11)} ${String(job.itemCount).padEnd(7)} ${String(job.written).padEnd(8)} ${job.startedAt.slice(0, 19)}`;
+	return `${["ID                           KIND         STATUS      FORMAT      SCOPE                ITEMS   WRITTEN  STARTED", ...jobs.map((job) => {
+		return `${job.id.padEnd(28).slice(0, 28)} ${job.kind.padEnd(12)} ${job.status.padEnd(11)} ${job.format.padEnd(11)} ${renderExportScopeLabel(job.scope).padEnd(20).slice(0, 20)} ${String(job.itemCount).padEnd(7)} ${String(job.written).padEnd(8)} ${job.startedAt.slice(0, 19)}`;
 	})].join("\n")}\n`;
 }
 const exportsCommand = {
@@ -4183,10 +4267,10 @@ async function rerun(id, commandFlags, globalFlags) {
 	debug(config.debug, "cacheFile", config.transcripts.cacheFile || "(none)");
 	const result = await (await createGranolaApp(config)).rerunExportJob(id);
 	if ("documentCount" in result) {
-		console.log(`✓ Reran notes export job ${result.job.id} to ${result.outputDir} (${result.written}/${result.documentCount} written)`);
+		console.log(`✓ Reran notes export job ${result.job.id} from ${renderExportScopeLabel(result.scope)} to ${result.outputDir} (${result.written}/${result.documentCount} written)`);
 		return 0;
 	}
-	console.log(`✓ Reran transcripts export job ${result.job.id} to ${result.outputDir} (${result.written}/${result.transcriptCount} written)`);
+	console.log(`✓ Reran transcripts export job ${result.job.id} from ${renderExportScopeLabel(result.scope)} to ${result.outputDir} (${result.written}/${result.transcriptCount} written)`);
 	return 0;
 }
 //#endregion
@@ -4426,6 +4510,12 @@ function escapeHtml(value) {
     .replaceAll('"', """);
 }
 
+function exportScopeLabel(scope) {
+  return scope && scope.mode === "folder"
+    ? "Folder: " + (scope.folderName || scope.folderId)
+    : "Scope: All meetings";
+}
+
 function setStatus(label, tone = "idle") {
   els.stateBadge.textContent = label;
   els.stateBadge.dataset.tone = tone;
@@ -4764,8 +4854,9 @@ function renderExportJobs() {
         "</div>",
         '<div class="job-card__status" data-status="' + escapeHtml(job.status) + '">' + escapeHtml(job.status) + "</div>",
         "</div>",
-        '<div class="job-card__meta">Format: ' + escapeHtml(job.format) + " • " + escapeHtml(progress) + " • Written: " + escapeHtml(String(job.written)) + "</div>",
+        '<div class="job-card__meta">Format: ' + escapeHtml(job.format) + " • " + escapeHtml(exportScopeLabel(job.scope)) + " • " + escapeHtml(progress) + " • Written: " + escapeHtml(String(job.written)) + "</div>",
         '<div class="job-card__meta">Started: ' + escapeHtml(job.startedAt.slice(0, 19)) + "</div>",
+        '<div class="job-card__meta">Output: ' + escapeHtml(job.outputDir) + "</div>",
         error,
         '<div class="job-card__actions">' + rerunButton + "</div>",
         "</article>",
@@ -4965,9 +5056,12 @@ async function syncAuthState() {
 }
 
 async function exportNotes() {
-  setStatus("Exporting notes…", "busy");
+  setStatus(state.selectedFolderId ? "Exporting folder notes…" : "Exporting notes…", "busy");
   await fetchJson("/exports/notes", {
-    body: JSON.stringify({ format: "markdown" }),
+    body: JSON.stringify({
+      folderId: state.selectedFolderId || undefined,
+      format: "markdown",
+    }),
     headers: { "content-type": "application/json" },
     method: "POST",
   });
@@ -4975,9 +5069,15 @@ async function exportNotes() {
 }
 
 async function exportTranscripts() {
-  setStatus("Exporting transcripts…", "busy");
+  setStatus(
+    state.selectedFolderId ? "Exporting folder transcripts…" : "Exporting transcripts…",
+    "busy",
+  );
   await fetchJson("/exports/transcripts", {
-    body: JSON.stringify({ format: "text" }),
+    body: JSON.stringify({
+      folderId: state.selectedFolderId || undefined,
+      format: "text",
+    }),
     headers: { "content-type": "application/json" },
     method: "POST",
   });
@@ -6059,6 +6159,9 @@ function parseAuthMode(value) {
 		default: throw new Error("invalid auth mode: expected stored-session or supabase-file");
 	}
 }
+function folderIdFromBody(value) {
+	return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
 function sendJson(response, body, init = {}) {
 	const payload = `${JSON.stringify(body, null, 2)}\n`;
 	response.writeHead(init.status ?? 200, {
@@ -6404,7 +6507,7 @@ async function startGranolaServer(app, options = {}) {
 			}
 			if (method === "POST" && path === granolaTransportPaths.exportNotes) {
 				const body = await readJsonBody(request);
-				sendJson(response, await app.exportNotes(noteFormatFromBody(body.format)), {
+				sendJson(response, await app.exportNotes(noteFormatFromBody(body.format), { folderId: folderIdFromBody(body.folderId) }), {
 					headers: originHeaders,
 					status: 202
 				});
@@ -6426,7 +6529,7 @@ async function startGranolaServer(app, options = {}) {
 			}
 			if (method === "POST" && path === granolaTransportPaths.exportTranscripts) {
 				const body = await readJsonBody(request);
-				sendJson(response, await app.exportTranscripts(transcriptFormatFromBody(body.format)), {
+				sendJson(response, await app.exportTranscripts(transcriptFormatFromBody(body.format), { folderId: folderIdFromBody(body.folderId) }), {
 					headers: originHeaders,
 					status: 202
 				});
@@ -6806,6 +6909,7 @@ Usage:
   granola notes [options]
 
 Options:
+  --folder <query>    Export only meetings inside one folder id or name
   --format <value>    Output format: markdown, json, yaml, raw (default: markdown)
   --output <path>     Output directory for note files (default: ./notes)
   --timeout <value>   Request timeout, e.g. 2m, 30s, 120000 (default: 2m)
@@ -6818,6 +6922,7 @@ Options:
 const notesCommand = {
 	description: "Export Granola notes",
 	flags: {
+		folder: { type: "string" },
 		format: { type: "string" },
 		help: { type: "boolean" },
 		output: { type: "string" },
@@ -6838,8 +6943,14 @@ const notesCommand = {
 		debug(config.debug, "format", format);
 		const app = await createGranolaApp(config);
 		debug(config.debug, "authMode", app.getState().auth.mode);
-		const result = await app.exportNotes(format);
-		console.log(`✓ Exported ${result.documentCount} notes to ${result.outputDir} (job ${result.job.id})`);
+		const folderQuery = typeof commandFlags.folder === "string" ? commandFlags.folder : void 0;
+		const folder = folderQuery ? await app.findFolder(folderQuery) : void 0;
+		debug(config.debug, "folder", folder?.id ?? "(all)");
+		const result = await app.exportNotes(format, {
+			folderId: folder?.id,
+			scopedOutput: typeof commandFlags.output !== "string"
+		});
+		console.log(`✓ Exported ${result.documentCount} notes from ${renderExportScopeLabel(result.scope)} to ${result.outputDir} (job ${result.job.id})`);
 		debug(config.debug, "notes written", result.written);
 		return 0;
 	}
@@ -6992,6 +7103,7 @@ Usage:
 
 Options:
   --cache <path>      Path to Granola cache JSON
+  --folder <query>    Export only meetings inside one folder id or name
   --format <value>    Output format: text, json, yaml, raw (default: text)
   --output <path>     Output directory for transcript files (default: ./transcripts)
   --debug             Enable debug logging
@@ -7003,6 +7115,7 @@ const transcriptsCommand = {
 	description: "Export Granola transcripts",
 	flags: {
 		cache: { type: "string" },
+		folder: { type: "string" },
 		format: { type: "string" },
 		help: { type: "boolean" },
 		output: { type: "string" }
@@ -7021,8 +7134,14 @@ const transcriptsCommand = {
 		debug(config.debug, "format", format);
 		const app = await createGranolaApp(config);
 		debug(config.debug, "authMode", app.getState().auth.mode);
-		const result = await app.exportTranscripts(format);
-		console.log(`✓ Exported ${result.transcriptCount} transcripts to ${result.outputDir} (job ${result.job.id})`);
+		const folderQuery = typeof commandFlags.folder === "string" ? commandFlags.folder : void 0;
+		const folder = folderQuery ? await app.findFolder(folderQuery) : void 0;
+		debug(config.debug, "folder", folder?.id ?? "(all)");
+		const result = await app.exportTranscripts(format, {
+			folderId: folder?.id,
+			scopedOutput: typeof commandFlags.output !== "string"
+		});
+		console.log(`✓ Exported ${result.transcriptCount} transcripts from ${renderExportScopeLabel(result.scope)} to ${result.outputDir} (job ${result.job.id})`);
 		debug(config.debug, "transcripts written", result.written);
 		return 0;
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "granola-toolkit",
-  "version": "0.33.0",
+  "version": "0.34.1",
   "description": "Toolkit for exporting and working with Granola meetings, notes, and transcripts",
   "keywords": [
     "cli",
@@ -34,6 +34,7 @@
   "scripts": {
     "build": "vp pack",
     "check": "vp check",
+    "coverage": "vp test --coverage",
     "dev": "vp pack --watch",
     "fmt": "vp fmt",
     "lint": "vp lint",
@@ -57,6 +58,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.5.2",
+    "@vitest/coverage-v8": "4.1.2",
     "typescript": "^5.9.3",
     "vite-plus": "0.1.15"
   },