onenote-cli 0.1.0

package/docs/local-search-architecture.md

@@ -0,0 +1,132 @@
+# Local Page-Level Search Architecture
+
+## Problem
+
+The Microsoft Graph OneNote API has a hard limit: when a OneDrive for Business document library contains more than 5,000 OneNote items, the API returns error 10008 and blocks all section/page listing endpoints. This affects accounts with many notebooks.
+
+The Graph Search API (`/search/query`) only returns section-level (.one file) results — it cannot identify individual pages within a section.
+
+## Solution: Local Cache + Binary Text Extraction
+
+### How it works
+
+1. **Sync** (`onenote sync`): Downloads all `.one` section files from OneDrive to a local cache directory (`.onenote/cache/`)
+2. **Extract**: Parses the MS-ONESTORE binary format to extract readable text blocks, then segments them into pages based on binary gaps
+3. **Search** (`onenote search <query>`): Searches the local cache for matching text at the page level
+
+### Cache Structure
+
+```
+.onenote/
+  cache/
+    {Notebook Name}/
+      {Section Name}.json    # Extracted pages with text
+```
+
+Each `.json` file contains:
+```json
+{
+  "section": "Section Name",
+  "notebook": "Notebook Name",
+  "webUrl": "https://...Doc.aspx?sourcedoc={GUID}&...",
+  "pages": [
+    { "title": "Page Title", "body": "Full text content..." },
+    ...
+  ],
+  "cachedAt": "2025-01-01T00:00:00.000Z"
+}
+```
+
+### Binary-Based Position Search
+
+For accurate page attribution, the cache stores the original `.one` binary alongside extracted metadata. Search works by:
+
+1. Searching the binary directly for the query string (both UTF-8 and UTF-16LE encodings)
+2. For each match position, finding the nearest preceding page GUID anchor
+3. Returning that page as the result
+
+This bypasses the imperfect text-block-to-page heuristics and gives accurate page attribution because the binary positions are ground truth — the matched text is physically located near the page anchor it belongs to.
+
+### .one Binary Text Extraction
+
+The MS-ONESTORE format (`.one` files) stores text as UTF-8 and UTF-16LE encoded strings interspersed with binary data. The extraction algorithm:
+
+1. Read the file twice — once as UTF-8 (ASCII content) and once as UTF-16LE (CJK and other Unicode)
+2. Find contiguous runs of printable characters
+3. Filter runs that don't contain enough "common" characters (ratio threshold)
+4. Use the page GUID anchors (see below) to assign each text block to the correct page
+
+### Page GUID Extraction
+
+Page-level URLs require knowing each page's UUID. We extract these from the binary using a pattern observed in MS-ONESTORE files:
+
+```
+[UTF-16LE title text] 00 00 [10 00 00 00] [16-byte page GUID]
+```
+
+The `10 00 00 00` is a uint32-LE size marker meaning "16 bytes follow", and the next 16 bytes are a UUIDv4 (version=4, variant=8-B). The text immediately preceding (UTF-16LE encoded) is the page title.
+
+For each page GUID found, all text blocks at later offsets up to the next anchor are assigned to that page. This anchor-based grouping correctly maps content (including text in non-Latin scripts) to the right page even when the file structure is fragmented.
+
+### Page-Level URL Format
+
+OneNote Online supports deep linking to specific pages via:
+
+```
+{sectionUrl}&wd=target({pageTitle}|{pageGuid}/)
+```
+
+Where:
+- `{sectionUrl}` is the SharePoint Doc.aspx URL with the section's `sourcedoc` GUID
+- `{pageTitle}` is the page title with `)` and `|` characters escaped as `\)` and `\|`
+- `{pageGuid}` is the page's UUIDv4
+- Trailing `/` is required
+
+The full `wd=` parameter is then URL-encoded with strict encoding (parens encoded as `%28`/`%29`).
+
+### Search Output
+
+Each result shows:
+- **Page title** — extracted from the page anchor
+- **Section and notebook** — which section/notebook contains the match
+- **Context snippet** — text surrounding the match with keyword highlighted in `**bold**`
+- **URL** — page-level OneNote Online deep link
+
+### Page-Level URL Resolution (Official URLs)
+
+We use the OneNote Graph API endpoint `GET /me/onenote/sections/0-{guid}/pages` to fetch the official `links.oneNoteWebUrl.href` for each page. This endpoint works even when the 5,000-item document library limit blocks `/me/onenote/pages` and `/me/onenote/sections` listing — because the `0-{guid}` ID prefix targets the section directly via its sourcedoc GUID (extracted from the OneDrive driveItem webUrl).
+
+Official OneNote URLs use the format:
+```
+{driveRootPath}/{notebook}?wd=target({sectionFile}|{sectionGroupGuid}/{pageTitle}|{pageGuid}/)
+```
+
+Unlike the simpler `Doc.aspx?sourcedoc=...&wd=target(...)` format, this URL **bypasses OneNote Online's session caching** and navigates directly to the specified page on first load. Verified working via browser automation testing.
+
+The page navigation GUID (used in `wd=target`) is extracted from the `oneNoteWebUrl` URL itself (the last UUID in the URL), since the API's page `id` field uses a different identifier format (`1-{32hexchars}!{counter}-{sectionGuid}`) that doesn't match the navigation GUID.
+
+### Limitations
+
+- **Page coverage**: Our binary parser detects ~50% of pages in some sections (those whose GUID-title binary pattern matches our heuristic). The other pages exist in the cache but without a precise GUID, so search results for them fall back to section-level URLs.
+- **Cache freshness**: Cache is valid for 1 hour by default. Run `onenote sync` to refresh.
+- **Binary parsing heuristic**: The UTF-8 text extraction may miss some content or include some binary noise. Page boundary detection is approximate.
+- **Large sections**: Sections with thousands of pages (e.g., 5000+ extracted "pages") may have over-segmented results due to the binary gap heuristic.
+
+### Alternative Approaches Investigated
+
+| Approach | Result |
+|---|---|
+| OneNote API `/me/onenote/pages` | Blocked by 5000 item limit (error 10008) |
+| Graph Search API `driveItem` | Section-level only, no page granularity |
+| Graph Search API `listItem` | Section-level only (pages not individually indexed) |
+| OneDrive HTML conversion (`?format=html`) | Not supported for .one files (406) |
+| SharePoint REST search | Requires separate OAuth scope, returns section-level |
+| Site-specific OneNote API | Same 5000 limit applies |
+| Beta Graph API endpoints | Same limitations |
+
+### Future Improvements
+
+- Implement proper MS-ONESTORE parser for accurate page extraction with page GUIDs
+- Use page GUIDs to construct page-level deep links: `Doc.aspx?sourcedoc={guid}&wd=target(section|/pageTitle)`
+- Incremental sync (only download changed sections based on `lastModifiedDateTime`)
+- SQLite or full-text search index for faster queries on large caches

package/docs/onen0te-cli-analysis.md

@@ -0,0 +1,130 @@
+# onen0te-cli UX Analysis
+
+Analysis of [fatihdumanli/onen0te-cli](https://github.com/fatihdumanli/onen0te-cli) — a Go-based OneNote CLI tool. Key takeaways for informing our `onenote-cli` design.
+
+## Command Structure
+
+```
+nnote new [-i "text" | -f file] [-a alias] [-t title]   Create a note
+nnote browse                                              Interactive notebook/section/page navigation
+nnote search <phrase>                                     Search across all notebooks
+nnote alias new [name]                                    Create a section alias
+nnote alias list                                          List all aliases
+nnote alias remove <name>                                 Delete an alias
+```
+
+## Auth Flow
+
+- Uses **OAuth 2.0 Authorization Code Flow** (not device code)
+- Starts a local HTTP server on `localhost:5992` for the redirect callback
+- Opens system browser for login
+- Tokens stored in Bitcask DB at `/tmp/nnote`
+- Auto-refreshes expired tokens silently before each API call
+- On first run, prompts: "You haven't setup a Onenote account yet, would you like to setup one now?"
+
+Comparison with our approach:
+- We use **device code flow** which works better in SSH/headless environments
+- They use browser redirect which is more seamless on desktop
+- Both auto-refresh tokens
+
+## Key UX Patterns Worth Adopting
+
+### 1. Interactive Selection Prompts
+
+When creating a note without an alias, the user is prompted to select a notebook, then a section via interactive dropdown (uses `survey` library). This is much better than requiring users to copy-paste IDs.
+
+### 2. Alias System
+
+Maps a short name to a notebook+section pair. Avoids repeated interactive selection for frequently-used sections. Example:
+```
+nnote new -a work -i "Meeting notes"
+```
+After saving, if no alias exists for the section, suggests creating one.
+
+### 3. Browse Mode (Interactive Navigation Loop)
+
+`nnote browse` creates an interactive loop:
+1. Select notebook
+2. Select section
+3. Select page
+4. View content (HTML rendered to text)
+5. Menu: back to sections / notebooks / open in browser / open in OneNote client / exit
+
+Uses emoji indicators in menus for visual scanning.
+
+### 4. Multiple Note Input Methods
+
+- `-i "text"` — Inline text
+- `-f /path/to/file` — Import from file
+- No flags — Opens `$EDITOR` for composing
+
+### 5. Spinner Animations
+
+Shows spinners during API calls (GetNotebooks, GetSections, SaveNote, etc.) with success/fail status on completion.
+
+### 6. Styled Output
+
+- Color-coded messages: green=success, red=error, yellow=warning
+- Table rendering for structured data (aliases, notebooks)
+- Breadcrumb display with metadata when viewing pages
+
+## Architecture Decisions
+
+### Storage
+
+- Uses **Bitcask** (embedded key-value store) at `/tmp/nnote`
+- Stores both OAuth tokens and aliases in the same DB
+- No config files — minimal setup burden
+- Concern: `/tmp` is volatile on some systems; better to use `~/.config/` or `~/.local/`
+
+### API Layer
+
+- Custom REST client wrapper over `net/http`
+- Endpoints used:
+  - `GET /me/onenote/notebooks` — list notebooks
+  - `GET /me/onenote/notebooks/{id}/sections` — list sections
+  - `GET /me/onenote/sections/{id}/pages` — list pages
+  - `GET /me/onenote/pages/{id}/content` — get page HTML
+  - `POST /me/onenote/sections/{id}/pages` — create page
+  - `GET /me/onenote/pages?search=...` — search (undocumented/deprecated?)
+- Uses `html2text` library to convert page HTML to terminal-readable text
+
+### Error Handling
+
+- All errors wrapped with context via `pkg/errors`
+- Exit codes for different failure modes (0-7)
+- Styled error messages (not raw stack traces)
+
+### Dependencies (Go)
+
+| Library | Purpose |
+|---------|---------|
+| spf13/cobra | CLI framework |
+| AlecAivazis/survey | Interactive prompts |
+| pterm/pterm | Tables, spinners, styled output |
+| k3a/html2text | HTML to text rendering |
+| prologic/bitcask | Key-value storage |
+| pkg/errors | Error wrapping |
+
+## Notable Gaps
+
+- No pagination for large result sets
+- No retry logic for HTTP 503/504 (marked as TODO)
+- No handling of the 5000-item SharePoint limit (would fail silently)
+- Search uses an older/undocumented Graph API pattern
+- Hardcoded OAuth client ID — not configurable
+- Storage path `/tmp/nnote` is volatile
+- No `--json` output option for scripting
+
+## Ideas for onenote-cli
+
+Based on this analysis, features worth considering for our CLI:
+
+1. **Interactive prompts** — Use `@inquirer/prompts` or similar for notebook/section selection instead of requiring raw IDs
+2. **Alias system** — Map short names to notebook+section pairs for quick note creation
+3. **Browse mode** — Interactive navigation loop through notebooks → sections → pages
+4. **HTML to text rendering** — Use `html-to-text` or `turndown` for terminal display of page content
+5. **Spinner/progress indicators** — Show progress during API calls
+6. **Open in browser/client** — Use the `links.oneNoteWebUrl` and `oneNoteClientUrl` from notebook metadata
+7. **$EDITOR integration** — Launch editor for composing notes
+8. **--json flag** — Output JSON for scripting/piping (improvement over onen0te-cli)

package/docs/setup.md

@@ -0,0 +1,141 @@
+# onenote-cli Authentication Setup Guide
+
+This guide walks you through setting up Azure AD authentication for `onenote-cli` to access Microsoft OneNote via the Graph API.
+
+## Prerequisites
+
+- A Microsoft account (personal or organizational)
+- An Azure account with an active subscription — [create one for free](https://azure.microsoft.com/pricing/purchase-options/azure-account)
+- [Bun](https://bun.sh) runtime installed
+
+## Step 1: Register an Azure AD Application
+
+1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com)
+2. Navigate to **Entra ID** > **App registrations** > **New registration**
+3. Fill in the registration form:
+   - **Name**: `onenote-cli`
+   - **Supported account types**: Select **"Accounts in any organizational directory and personal Microsoft accounts"**
+     (This allows both work/school and personal Microsoft accounts)
+   - **Redirect URI**: Leave blank for now
+4. Click **Register**
+5. On the Overview page, copy the **Application (client) ID** — you will need this
+
+## Step 2: Configure Platform for Device Code Flow
+
+1. In your app registration, go to **Authentication** > **Add a platform**
+2. Select **Mobile and desktop applications**
+3. Check the box for `https://login.microsoftonline.com/common/oauth2/nativeclient`
+4. Click **Configure**
+5. Scroll down and set **Allow public client flows** to **Yes**
+6. Click **Save**
+
+> Device code flow requires "Allow public client flows" to be enabled. Without this, authentication will fail.
+
+## Step 3: Configure API Permissions
+
+1. In your app registration, go to **API permissions** > **Add a permission**
+2. Select **Microsoft Graph** > **Delegated permissions**
+3. Search and add the following permissions:
+   - `Notes.Read` — Read user OneNote notebooks
+   - `Notes.ReadWrite` — Read and write user OneNote notebooks
+   - `Notes.Read.All` — Read all notebooks the user can access
+   - `Notes.ReadWrite.All` — Read and write all notebooks the user can access
+4. Click **Add permissions**
+
+> For organizational accounts, an admin may need to **Grant admin consent** for these permissions.
+
+## Step 4: Configure onenote-cli
+
+You have two options to provide credentials:
+
+### Option A: Environment variables (recommended)
+
+Copy `.env.example` to `.env.local` and fill in your client ID:
+
+```bash
+cp .env.example .env.local
+```
+
+Edit `.env.local`:
+
+```env
+ONENOTE_CLIENT_ID=your-actual-client-id-here
+ONENOTE_AUTHORITY=https://login.microsoftonline.com/common
+```
+
+### Option B: Config file
+
+The CLI also reads from `~/.onenote-cli/config.json`. This file is auto-created on first run:
+
+```json
+{
+  "clientId": "your-actual-client-id-here",
+  "authority": "https://login.microsoftonline.com/common"
+}
+```
+
+> Environment variables take priority over the config file.
+
+## Step 5: Login
+
+```bash
+bun run src/index.ts login
+```
+
+This initiates the **device code flow**:
+
+1. The CLI prints a URL and a code
+2. Open the URL in your browser
+3. Enter the code and sign in with your Microsoft account
+4. Grant the requested permissions
+5. Return to the terminal — you should see "Login successful!"
+
+Tokens are cached at `~/.onenote-cli/msal-cache.json` so you don't need to login every time.
+
+## Step 6: Verify
+
+```bash
+# List your notebooks
+bun run src/index.ts notebooks list
+
+# List all sections
+bun run src/index.ts sections list
+
+# List pages
+bun run src/index.ts pages list
+```
+
+## Authority URL Reference
+
+| Scenario | Authority URL |
+|---|---|
+| Multi-tenant + personal accounts | `https://login.microsoftonline.com/common` |
+| Organizational accounts only (any tenant) | `https://login.microsoftonline.com/organizations` |
+| Personal Microsoft accounts only | `https://login.microsoftonline.com/consumers` |
+| Single tenant only | `https://login.microsoftonline.com/{tenant-id}` |
+
+## Logout
+
+To clear cached tokens:
+
+```bash
+bun run src/index.ts logout
+```
+
+## Troubleshooting
+
+### "AADSTS7000218: The request body must contain the following parameter: 'client_assertion' or 'client_secret'"
+
+→ Make sure **Allow public client flows** is set to **Yes** in your app's Authentication settings.
+
+### "AADSTS65001: The user or administrator has not consented to use the application"
+
+→ An admin needs to grant consent for the API permissions, or the user needs to consent during login.
+
+### "AADSTS700016: Application with identifier '...' was not found"
+
+→ Double-check that your `ONENOTE_CLIENT_ID` matches the Application (client) ID from Azure portal.
+
+### Token expired
+
+Tokens are automatically refreshed using the cached refresh token. If refresh fails, run `onenote login` again.

package/docs/zhihu-intro.md

@@ -0,0 +1,92 @@
+# onenote-cli: 让你的 OneNote 笔记在 AI 时代存活下来
+
+你的 OneNote 笔记本里藏着多少年的记忆？工作笔记、学习资料、日记、灵感碎片……这些内容，AI 能帮你搜索吗？
+
+答案是：现在可以了。
+
+onenote-cli 是一个用 Bun + TypeScript 构建的命令行工具，通过 Microsoft Graph API 直接操作你的 OneNote 笔记本。最关键的功能：**全文搜索，精确到页面级别，点击 URL 直接跳转到匹配的那一页。**
+
+## 为什么需要这个？
+
+OneNote 的搜索功能只能在桌面端或网页端使用，无法被 AI 工具调用。当你想让 AI 帮你找一条几年前的笔记时，它做不到——因为 OneNote 没有暴露搜索 API 给第三方。
+
+更糟的是，如果你的 OneDrive 里有超过 5000 个 OneNote 项目（笔记本+分区+分区组），微软的 Graph API 会直接返回 403 错误，连列出分区都做不到。
+
+onenote-cli 解决了这两个问题。
+
+## 它能做什么？
+
+### 全文搜索（精确到页面）
+
+```bash
+$ onenote search "项目计划"
+
+# (20240315) Q2 项目计划
+  Section: Work Notes | Notebook: My Notebook
+  ...下季度**项目计划**：1. 完成用户认证模块重构 2. 上线新的推荐算法...
+  https://onenote.com/...?wd=target(...)
+
+3 page-level results found.
+```
+
+搜索结果直接给出 OneNote Online 的页面级 URL，点击即可跳转到对应页面。不是打开整个分区，而是精确到那一页。
+
+### 笔记本管理
+
+```bash
+$ onenote notebooks list
+$ onenote sections list -n <notebook-id>
+$ onenote pages create -s <section-id> -t "Meeting Notes" -b "<p>内容</p>"
+```
+
+### 5000 项目限制的解决方案
+
+当 Graph API 因为 SharePoint 文档库超过 5000 项而返回 403 时，onenote-cli 会：
+
+1. 通过 OneDrive API 直接下载 `.one` 二进制文件
+2. 从二进制中提取页面内容（支持 UTF-8 和 UTF-16LE，中日韩文字都能搜到）
+3. 提取页面 GUID，通过 OneNote API 获取官方页面 URL
+4. 构建本地缓存索引
+
+### AI 集成
+
+作为 Claude Code Skill 一键安装：
+
+```bash
+$ npx skills add snomiao/onenote-cli
+```
+
+安装后，AI 可以直接搜索你的 OneNote 笔记，输出 Markdown 格式的结果：
+
+```markdown
+[Q2 项目计划](https://onenote.com/...?wd=target(...))
+  Work Notes | My Notebook
+  ...下季度**项目计划**：1. 完成用户认证模块重构...
+```
+
+## 技术亮点
+
+- **设备代码流认证**：支持 SSH / 无头环境
+- **.one 二进制解析**：从 MS-ONESTORE 格式中提取页面文本和 GUID
+- **官方页面 URL**：通过 `/me/onenote/sections/0-{guid}/pages` 端点获取，绕过 OneNote Online 的会话缓存
+- **跨目录运行**：`.env.local` 和缓存从包目录自动加载
+
+## 开始使用
+
+```bash
+git clone https://github.com/snomiao/onenote-cli.git
+cd onenote-cli
+bun install
+cp .env.example .env.local  # 填入你的 Azure AD Client ID
+bun run src/index.ts auth login
+bun run src/index.ts sync
+bun run src/index.ts search "你想找的内容"
+```
+
+详细的 Azure AD 配置步骤见 GitHub 仓库的 [docs/setup.md](https://github.com/snomiao/onenote-cli/blob/main/docs/setup.md)。
+
+---
+
+**GitHub**: https://github.com/snomiao/onenote-cli
+
+MIT License | by snomiao

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "onenote-cli",
+  "version": "0.1.0",
+  "description": "CLI tool to operate Microsoft OneNote via Graph API",
+  "type": "module",
+  "bin": {
+    "onenote-cli": "./src/index.ts",
+    "onenote": "./src/index.ts"
+  },
+  "scripts": {
+    "start": "bun run src/index.ts"
+  },
+  "dependencies": {
+    "@azure/msal-node": "^2.16.0",
+    "yargs": "^17.7.2"
+  },
+  "devDependencies": {
+    "@types/yargs": "^17.0.33",
+    "typescript": "^5.7.0"
+  },
+  "license": "MIT"
+}