granola-toolkit 0.1.0 → 0.2.0

package/README.md

@@ -146,17 +146,9 @@ Supported environment variables:
 - `CACHE_FILE`
 - `TRANSCRIPT_OUTPUT`
 
-## What Changed In The Port
+## Development Checks
 
-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
+Before pushing changes, run:
 
 ```bash
 vp check
@@ -165,54 +157,11 @@ 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:
+What those do:
 
-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`
+- `vp check`: formatting, linting, and type checks
+- `vp test`: unit tests
+- `vp pack`: builds the CLI bundle into `dist/cli.js`
+- `npm pack --dry-run`: shows the exact npm package contents without publishing
 
-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.
+`vp build` is for web apps. This repo is a CLI package, so the build step here is `vp pack`.

package/dist/cli.js

@@ -274,60 +274,6 @@ async function fetchDocuments(options) {
 	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;
@@ -529,6 +475,113 @@ async function writeNotes(documents, outputDir) {
 	return written;
 }
 //#endregion
+//#region src/commands/shared.ts
+function debug(enabled, ...values) {
+	if (enabled) console.error("[debug]", ...values);
+}
+//#endregion
+//#region src/commands/notes.ts
+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
+`;
+}
+const notesCommand = {
+	description: "Export Granola notes to Markdown",
+	flags: {
+		help: { type: "boolean" },
+		output: { type: "string" },
+		timeout: { type: "string" }
+	},
+	help: notesHelp,
+	name: "notes",
+	async run({ commandFlags, globalFlags }) {
+		const config = await loadConfig({
+			globalFlags,
+			subcommandFlags: commandFlags
+		});
+		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;
+	}
+};
+//#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/transcripts.ts
 function formatTranscript(document, segments) {
 	if (segments.length === 0) return "";
@@ -576,7 +629,54 @@ async function writeTranscripts(cacheData, outputDir) {
 	return written;
 }
 //#endregion
-//#region src/cli.ts
+//#region src/commands/transcripts.ts
+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
+`;
+}
+//#endregion
+//#region src/commands/index.ts
+const commands = [notesCommand, {
+	description: "Export Granola transcripts to text files",
+	flags: {
+		cache: { type: "string" },
+		help: { type: "boolean" },
+		output: { type: "string" }
+	},
+	help: transcriptsHelp,
+	name: "transcripts",
+	async run({ commandFlags, globalFlags }) {
+		const config = await loadConfig({
+			globalFlags,
+			subcommandFlags: commandFlags
+		});
+		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;
+	}
+}];
+const commandMap = new Map(commands.map((command) => [command.name, command]));
+//#endregion
+//#region src/flags.ts
 function parseBooleanValue(value) {
 	if (/^(true|1|yes|on)$/i.test(value)) return true;
 	if (/^(false|0|no|off)$/i.test(value)) return false;
@@ -624,13 +724,15 @@ function parseFlags(args, spec) {
 		values
 	};
 }
+//#endregion
+//#region src/cli.ts
 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;
+		const candidate = !token.startsWith("-") ? commandMap.get(token) : void 0;
+		if (!command && candidate) {
+			command = candidate;
 			continue;
 		}
 		rest.push(token);
@@ -641,6 +743,7 @@ function splitCommand(argv) {
 	};
 }
 function rootHelp() {
+	const commandWidth = Math.max(...commands.map((command) => command.name.length));
 	return `Granola CLI
 
 Export your Granola notes and transcripts.
@@ -649,8 +752,7 @@ Usage:
   granola <command> [options]
 
 Commands:
-  notes        Export Granola notes to Markdown
-  transcripts  Export Granola transcripts to text files
+${commands.map((command) => `  ${command.name.padEnd(commandWidth)}  ${command.description}`).join("\n")}
 
 Global options:
   --config <path>     Path to .granola.toml
@@ -663,38 +765,6 @@ Examples:
   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);
@@ -712,68 +782,15 @@ async function runCli(argv) {
 			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;
+		const subcommand = parseFlags(global.rest, command.flags);
+		if (subcommand.values.help || global.values.help) {
+			console.log(command.help());
+			return 0;
 		}
+		return await command.run({
+			commandFlags: subcommand.values,
+			globalFlags: global.values
+		});
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		console.error(message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "granola-toolkit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CLI toolkit for exporting and working with Granola notes and transcripts",
   "keywords": [
     "cli",
@@ -15,7 +15,7 @@
   "author": "Nima Karimi",
   "repository": {
     "type": "git",
-    "url": "git@github.com:kkarimi/granola-toolkit.git"
+    "url": "git+https://github.com/kkarimi/granola-toolkit.git"
   },
   "bin": {
     "granola": "dist/cli.js"