feat: add standalone Granola CLI

[goncalossilva]

Summary

• add a standalone TypeScript Granola CLI with the same overall repo shape as outline-cli
• implement official-API auth, global cache sync, and cache-backed list, folders, search, and show commands
• add agent skills, self-update/changelog commands, CI/release scaffolding, colocated tests, and project docs

Testing

• npm run type-check
• npm test
• npm run build
• npm run lint:check
• npm run format:check
• npm run check:skill-sync
• smoke tested auth, sync, list, folders, and show against a real Granola account

[Copilot]

Pull request overview

Adds a standalone, TypeScript-based Granola CLI with official-API auth, a local cache + sync model, and agent-friendly output modes, along with skills and update/changelog tooling.

Changes:

• Implement Granola API client + auth resolution/storage, cache syncing/indexing, and local search/folder aggregation.
• Add CLI commands (auth, sync, list, folders, search, show, skill, update, changelog) with human + JSON/NDJSON output.
• Add skill generation/installation + CI checks, plus docs and initial test coverage.

Reviewed changes

Copilot reviewed 55 out of 55 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/transport/http-dispatcher.ts	Proxy-aware Undici dispatcher singleton + test reset hook.
src/transport/fetch-with-retry.ts	Fetch wrapper adding retry + timeout support and dispatcher injection.
src/smoke.test.ts	Minimal Vitest scaffold test.
src/postinstall.ts	Postinstall entrypoint to auto-update installed skills.
src/lib/update-config.ts	Read/write update channel in CLI config.
src/lib/types.ts	Shared domain/types for API, cache, search, and auth payloads.
src/lib/transcript.ts	Transcript normalization, flattening, and formatting helpers.
src/lib/transcript.test.ts	Tests for transcript parsing/formatting helpers.
src/lib/spinner.ts	CLI spinner wrapper + helper to run operations with spinner.
src/lib/skills/update-installed.ts	Updates installed agent skills across all registered installers.
src/lib/skills/types.ts	Skill installer interface definition.
src/lib/skills/index.ts	Skill installer registry + helpers to list/get installers.
src/lib/skills/create-installer.ts	Factory for agent skill installers (install/update/uninstall).
src/lib/skills/create-installer.test.ts	Tests for skill registry and installer behavior.
src/lib/skills/content.ts	Source-of-truth skill content used to generate SKILL.md.
src/lib/search.ts	Local filtering, scoring, excerpts, and folder aggregation utilities.
src/lib/search.test.ts	Tests for filtering/scoring/folder aggregation utilities.
src/lib/output.ts	Output helpers for human/JSON/NDJSON modes + formatting utilities.
src/lib/output.test.ts	Tests for output helpers and formatting utilities.
src/lib/errors.ts	Custom GranolaError with code/details.
src/lib/config.ts	Read/write CLI config file with restrictive permissions.
src/lib/cache.ts	Cache layout, state handling, sync orchestration, and note summarization.
src/lib/cache.test.ts	Tests for cache note summarization behavior.
src/lib/cache.sync.test.ts	Tests for cache filesystem permissions and sync timestamp behavior.
src/lib/auth.ts	API key resolution + secure-store/config storage + login/logout helpers.
src/lib/api.ts	Granola public API client with rate limiting + error normalization.
src/index.ts	CLI entrypoint wiring all commands and global options/help.
src/commands/update/switch.ts	granola update switch command implementation.
src/commands/update/index.ts	Registers update command tree.
src/commands/update/action.ts	Update command logic (registry check + global install).
src/commands/update/action.test.ts	Tests for update version parsing/comparison helpers.
src/commands/sync.ts	granola sync command implementation.
src/commands/skill.ts	granola skill install/uninstall/list command implementation.
src/commands/show.ts	granola show command implementation (optionally transcript).
src/commands/show.test.ts	Tests for show command output and error path.
src/commands/shared.ts	Shared Commander option definitions + option parsing.
src/commands/shared.test.ts	Tests for parsing of Commander --no-sync flag behavior.
src/commands/search.ts	granola search command implementation (cache-based).
src/commands/search.test.ts	Tests for JSON search output behavior.
src/commands/runtime.ts	Runtime helper for implicit sync unless --no-sync.
src/commands/list.ts	granola list command implementation.
src/commands/folders.ts	granola folders command implementation (cache-derived).
src/commands/changelog.ts	granola changelog command implementation (renders local CHANGELOG).
src/commands/auth.ts	granola auth command implementation + masked key prompt.
src/commands/auth.test.ts	Tests for auth command behavior and masked input.
skills/granola-cli/SKILL.md	Generated agent skill markdown artifact.
scripts/sync-skill.js	Script to regenerate SKILL.md from built output.
scripts/postinstall.js	Postinstall wrapper importing built postinstall entrypoint.
scripts/check-skill-sync.js	CI script verifying generated skill content is in sync.
README.md	Project documentation (install, auth, cache model, commands).
PLAN.md	Detailed implementation plan and repo structure reference.
CONTRIBUTING.md	Contributing guidelines and release workflow notes.
CLAUDE.md	Agent/developer guidance for working in the repo.
CHANGELOG.md	Initial changelog entries for the standalone CLI.
.github/workflows/check-skill-sync.yml	CI job ensuring SKILL.md is kept in sync.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[doistbot]

This PR introduces a fully featured standalone TypeScript Granola CLI complete with core cache-backed commands, authentication, and agent skills. The implementation provides a robust, well-tested foundation that closely mirrors existing CLI tooling patterns. A few refinements are noted regarding local timezone handling for date filters, removing the command-line token flag to prevent exposing secrets in shell history, and safely slicing strings to properly support multi-byte Unicode characters.

_{Share Feedback • Review Logs}

[doist-release-bot]

🎉 This PR is included in version 1.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀