@fastagent-sh/voicenote 0.17.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fastagent-sh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,351 @@
+# voicenote
+
+Voice recordings → diarized transcripts → integrated semantic Markdown notes.
+
+CLI command: `vn`
+
+[中文文档 / Chinese documentation](README.zh-CN.md)
+
+Currently tuned for the PHILIPS VTR6500 voice recorder, but the workflow is generic: scan recordings under a mount point → transcribe with speaker diarization → GPT performs the necessary cleanup and process reconstruction inside the notes-generation stage → produce smart notes.
+
+**Two ways to use it:**
+
+- 🖥️ **Desktop app (GUI)** — for non-terminal users, a self-contained `.app`, one-line install:
+  ```bash
+  curl -fsSL https://raw.githubusercontent.com/fastagent-sh/voicenote/main/scripts/install-app.sh | bash
+  ```
+  See [Desktop app](#desktop-app-gui-app) below.
+- ⌨️ **CLI (`vn`)** — for terminal users / developers, see "Install (CLI)" below.
+
+## Install (CLI)
+
+> The CLI installs from the npm package `@fastagent-sh/voicenote`. The install script / `bun add -g` below require the package to be **published to npm** (see "Development" at the end for the release flow).
+
+Recommended: the install script (macOS):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/fastagent-sh/voicenote/main/scripts/install.sh | bash
+```
+
+The install script does **no interactive configuration** by default: it installs/checks `ffmpeg`, Bun, Node/npm, pi, and `vn`, then writes an editable `config.json` template. After installation, open the config file and fill in your keys and name:
+
+```bash
+open ~/.config/voicenote/config.json
+# or open the directory
+vn open config
+```
+
+Advanced users can preseed the template with environment variables:
+
+```bash
+VOICENOTE_NAME="Jane Doe" \
+VOICENOTE_ALIAS="jane" \
+VOICENOTE_WORKSPACE="$HOME/Documents/meetings" \
+VOLCANO_ASR_KEY="..." \
+VOLCANO_TOS_BUCKET="..." \
+VOLCANO_TOS_ACCESS_KEY="..." \
+VOLCANO_TOS_SECRET_KEY="..." \
+bash <(curl -fsSL https://raw.githubusercontent.com/fastagent-sh/voicenote/main/scripts/install.sh)
+```
+
+The first install creates `~/.config/voicenote/config.json`. A legacy `speakers.json` is still read for compatibility and migrated into `config.json.speakers`. Once configured, run `vn doctor` to check the environment, and `vn install-launch-agent` if you want background monitoring.
+
+Manual install:
+
+```bash
+bun add -g @fastagent-sh/voicenote
+mkdir -p ~/.local/bin
+ln -sf ~/.bun/bin/vn ~/.local/bin/vn
+```
+
+An older `git+…#main` install is replaced in place by `bun add -g @fastagent-sh/voicenote`; no uninstall needed.
+
+### Windows (CLI)
+
+The CLI is cross-platform. Prerequisites: Bun, ffmpeg (provides `ffprobe.exe`), Node + pi.
+
+```powershell
+bun add -g @fastagent-sh/voicenote
+# Windows has no /Volumes mount points; set the recorder drive explicitly
+setx VOICENOTE_RECORD_DIR "E:\RECORD"
+```
+
+- Config: `%APPDATA%\voicenote\config.json`; logs/locks: `%LOCALAPPDATA%\voicenote\`
+- Background automation uses the **Windows Task Scheduler**: `vn install-launch-agent` to register / `vn status` to inspect / `vn uninstall-launch-agent` to remove (same command names as macOS; dispatched per platform internally)
+
+## Dependencies
+
+- **Bun >= 1.3 (required at runtime)** — the code uses `Bun.Glob` / `Bun.file`; plain Node cannot run it
+- Node / npm — only used to install the pi CLI (pi-codex backend)
+- ffmpeg / ffprobe (audio duration detection):
+
+```bash
+brew install ffmpeg
+```
+
+The install script only writes `vn` / Bun / Homebrew PATH entries to your shell config; app configuration lives in `~/.config/voicenote/config.json`. A manual setup needs at least:
+
+```json
+{
+  "VOICENOTE_WORKSPACE": "/Users/you/Documents/meetings",
+  "VOLCANO_ASR_KEY": "...",
+  "VOLCANO_ASR_RESOURCE_ID": "volc.seedasr.auc",
+  "VOLCANO_TOS_REGION": "cn-guangzhou",
+  "VOLCANO_TOS_ENDPOINT": "tos-s3-cn-guangzhou.volces.com",
+  "VOLCANO_TOS_BUCKET": "...",
+  "VOLCANO_TOS_ACCESS_KEY": "...",
+  "VOLCANO_TOS_SECRET_KEY": "...",
+  "VOLCANO_TOS_KEEP": "0",
+  "speakers": {
+    "self": { "name": "Your name", "aliases": ["nickname", "alias"] },
+    "known": []
+  }
+}
+```
+
+Optional settings:
+
+```json
+{
+  "VOICENOTE_DEVICE_VOLUME": "VTR6500",
+  "VOICENOTE_RECORD_DIR": "/Volumes/VTR6500/RECORD",
+  "VOICENOTE_MAX_AGE_HOURS": "48",
+  "VOICENOTE_PI_BIN": "pi",
+  "VOICENOTE_PI_PROVIDER": "openai-codex,openai",
+  "VOICENOTE_PI_MODEL": "gpt-5.5",
+  "VOICENOTE_PI_THINKING": "high",
+  "VOICENOTE_PI_SUMMARY_TOOLS": "read,grep",
+  "VOICENOTE_CONTEXT_DIR": "/Users/you/vault"
+}
+```
+
+## Usage
+
+```bash
+vn doctor                       # check environment and config
+vn run                          # default: Volcano ASR + pi-codex notes
+vn run --mode transcript        # transcript only, skip semantic notes
+vn run --latest                 # process only the latest valid recording
+vn run --latest --force         # re-run the latest one
+vn run --pdf                    # additionally render a PDF after notes
+vn run --dry-run                # print the plan only
+vn list                         # list this month's notes
+vn list --month 2026-05         # specific month
+vn last                         # print the latest processing summary
+vn open                         # open the notes directory in Finder
+vn open config                  # open ~/.config/voicenote/
+vn open logs                    # open the logs directory
+vn open <slug>                  # open a note by filename fragment
+vn forget <id|filename>         # let a recording be processed again
+vn log                          # print today's log tail (--lines N / -f follow / --err include launchd.err / --date YYYY-MM-DD)
+vn errors                       # print recent ERROR logs
+vn login                        # sign in to ChatGPT (Codex device-code flow, for the notes backend; no pi TUI needed)
+vn upgrade                      # reinstall latest npm package
+vn install-launch-agent
+vn status
+vn uninstall-launch-agent
+```
+
+## Configuration file
+
+The install script writes an editable template:
+
+```text
+~/.config/voicenote/config.json     # workspace, Volcano ASR/TOS, summary backend, your name/aliases, etc.
+```
+
+`speakers` maps Speaker A/B/C back to real names; `known` lists known contacts:
+
+```json
+{
+  "speakers": {
+    "self": { "name": "Your name", "aliases": ["nickname", "alias"] },
+    "known": []
+  }
+}
+```
+
+Changes take effect on the next `vn run`. A legacy `~/.config/voicenote/speakers.json` is still read as a compatibility fallback.
+
+## Workflow
+
+1. Scan recordings under `/Volumes/VTR6500/RECORD/`
+2. Filter: ignore `._*`, small files (<100KB), short recordings (<60s), and already-processed recordings; if a previous run failed only at the summary stage and the transcript is saved, it is not considered done — processing resumes from there
+3. Copy the original audio into `${VOICENOTE_WORKSPACE}/_audio/YYYY-MM/`
+4. Transcribe with the Volcano Doubao large-model audio-file recognition API: upload local audio to TOS, submit the job, poll for results, and delete the TOS object by default when done
+5. Persist the raw transcript immediately after transcription (no lossy cleanup), so a later-stage failure never wastes the ASR spend
+6. The summary model (default: pi codex via ChatGPT Plus) reads the raw transcript directly, performing necessary cleanup, speaker restoration, and reconstruction of views/debates/consensus inside the notes-generation stage; if the summary fails, the next `vn run` / `vn run --latest` reuses the saved transcript and retries only the notes generation — no `vn forget` needed
+7. Write notes / metadata; the system makes no archiving decisions — files stay in the configured workspace
+
+## Output locations
+
+The installer defaults to `VOICENOTE_WORKSPACE=~/Documents/meetings`.
+
+- Notes entry point: `${VOICENOTE_WORKSPACE}/YYYY-MM/`
+- Original audio: `${VOICENOTE_WORKSPACE}/_audio/YYYY-MM/`
+- Full transcripts: `${VOICENOTE_WORKSPACE}/_transcripts/YYYY-MM/`
+- Metadata: `${VOICENOTE_WORKSPACE}/_metadata/YYYY-MM/`
+- State: `${VOICENOTE_WORKSPACE}/_state/processed.json`
+- Index: `${VOICENOTE_WORKSPACE}/_index/notes.jsonl`
+
+## Automation
+
+The install script can set this up automatically. Manual setup:
+
+```bash
+vn install-launch-agent
+launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/sh.fastagent.voicenote.plist 2>/dev/null || true
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/sh.fastagent.voicenote.plist
+launchctl enable gui/$(id -u)/sh.fastagent.voicenote
+vn status
+```
+
+The LaunchAgent invokes `vn run` every 60 seconds. It skips safely when no recorder is plugged in; once the VTR6500 is connected, new recordings are processed automatically.
+
+> Config changes (`config.json` or `~/.zshrc`) are picked up automatically by the background agent on its next run — no reinstall needed. The plist only snapshots real environment variables and pi's absolute path: **after changing `VOICENOTE_PI_BIN`, re-run `vn install-launch-agent` and reload** (`vn upgrade` regenerates the plist automatically). If pi is not signed in or ASR is not configured, the agent skips processing instead of burning ASR spend.
+>
+> Exception: if you `export http_proxy=...` directly in your shell (instead of using `LOCAL_PROXY_HOST`) and then run `vn install-launch-agent`, that real env value is snapshotted into the plist and keeps overriding later `LOCAL_PROXY_HOST` changes; re-run `vn install-launch-agent` to clear it. Prefer `LOCAL_PROXY_HOST`/`LOCAL_PROXY_PORT` for proxy configuration.
+
+Logs:
+
+```text
+~/.local/state/voicenote/logs/launchd.out.log
+~/.local/state/voicenote/logs/launchd.err.log
+```
+
+## Development
+
+```bash
+git clone https://github.com/fastagent-sh/voicenote.git
+cd voicenote
+bun install
+bun run typecheck
+bun src/cli.ts doctor
+```
+
+Distribution: vn ships as **source** with no build step — it only runs on bun (shebang + `bun:ffi` + `engines.bun`), and bun runs TypeScript natively, so `bin` points straight at `src/cli.ts` and the npm tarball only contains `src/{cli,envConfig,runLock}.ts`. The install script / `vn upgrade` install from the published npm package (`bun add -g @fastagent-sh/voicenote`); a `git+https` install also works directly (the git tree carries the source; no build or install script needed).
+
+Routine release (tag triggers CI):
+
+```bash
+npm version patch
+git push --follow-tags
+```
+
+The workflow lives at `.github/workflows/release.yml`: CI explicitly runs typecheck/test/build + an artifact smoke test, then `npm publish --ignore-scripts` (deterministic publishing, no lifecycle dependence). Publishing uses **npm trusted publishing (OIDC)**: no long-lived token (`id-token: write` + a Trusted Publisher configured on npmjs.com), with provenance attached automatically. A bare local `npm publish` is still guarded by `prepublishOnly` (typecheck+test+build).
+
+> **First-release exception**: npm has no pending-publisher, so trusted publishing cannot publish a package's very first version. Publish once manually with `npm login` + `npm publish --ignore-scripts`, then add a Trusted Publisher on the package settings page at npmjs.com (repo `fastagent-sh/voicenote`, workflow `release.yml`); CI takes over afterwards (the npm account needs 2FA).
+
+## Desktop app (GUI, `app/`)
+
+A self-contained macOS `.app` (Tauri v2) for **non-terminal users**: the target machine needs no pre-installed bun / pi / ffprobe / global `vn`.
+
+**Positioning**: the GUI is only a "status dashboard + quick access to output" — it does **not** drive processing. The full pipeline runs autonomously every 60s via the background LaunchAgent using the bundled engine (it keeps running with the GUI closed).
+
+- First run: setup wizard (identity / Volcano keys / proxy) → ChatGPT sign-in (no terminal on the device; uses `vn login`'s browser-callback flow)
+- After that: the main view shows agent activity + recent notes (open note / open folder)
+
+### What's bundled
+
+`bun build --compile` compiles the `vn` engine (bun runtime + pi-ai included) into a single-file sidecar; pi cannot be compiled (it reads data files from disk at runtime), so the whole package ships alongside and runs with a bundled `bun`:
+
+| Component | Form | Purpose |
+|------|------|------|
+| `vn` (compiled) | externalBin | pipeline + ChatGPT sign-in |
+| `bun` | externalBin | runs pi |
+| `ffprobe` (native arm64 static) | externalBin | audio duration (pi only needs ffprobe, not all of ffmpeg) |
+| `pi` + node_modules | resource | notes backend (ChatGPT Codex agent) |
+
+At runtime, Rust generates a wrapper (`exec <bundled bun> <bundled pi/cli.js> "$@"`) and injects `VOICENOTE_PI_BIN` / `VOICENOTE_FFPROBE_BIN` into `vn`. Release builds are **universal** (x86_64 + arm64; vn/bun/ffprobe each merged with `lipo`; pi is JS and needs none).
+
+### Build
+
+Prerequisites: Rust + cargo, bun, node/npm, Xcode CLT, and **pi installed globally on the build machine** (`npm i -g @earendil-works/pi-coding-agent`; the build script stages pi from there).
+
+```bash
+cd app
+bun install
+bun run tauri build
+# Output: src-tauri/target/release/bundle/macos/VoiceNote.app
+```
+
+**Windows** (build on Windows with Rust + MSVC C++ build tools; WebView2 is preinstalled on Win10/11, NSIS is downloaded by Tauri automatically):
+
+```powershell
+cd app
+bun install
+bun run tauri build --config src-tauri/tauri.windows.conf.json
+# Output: app\src-tauri\target\release\bundle\nsis\VoiceNote_<version>_x64-setup.exe
+```
+
+Windows uses `scripts/build-vn-sidecar.ps1` to stage `vn.exe` (`--windows-hide-console`, no console window) / `bun.exe` / `ffprobe.exe` + pi; `tauri.windows.conf.json` produces the NSIS installer (currentUser, no admin).
+
+`beforeBuildCommand` first runs `scripts/build-vn-sidecar.sh` to stage vn/bun/ffprobe/pi (`binaries/` and `resources/` are gitignored; pi/ffprobe copying is idempotent). For development use `bun run tauri dev` (dev mode runs `../src/cli.ts` directly, no bundling, no background agent install).
+
+### How users install (one line, recommended)
+
+> This is separate from the CLI `install.sh` above: the CLI script targets developers (installs bun/pi/vn); this one targets **non-technical users** (download .app → /Applications).
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/fastagent-sh/voicenote/main/scripts/install-app.sh | bash
+```
+
+**Windows** (one line, no admin):
+
+```powershell
+irm https://raw.githubusercontent.com/fastagent-sh/voicenote/main/scripts/install-app.ps1 | iex
+```
+
+`install-app.ps1` downloads the NSIS installer from the GitHub Release (self-contained vn/bun/ffprobe/pi) → silent install into `%LOCALAPPDATA%` (no admin) → launches it.
+
+`install-app.sh` downloads the packaged `.app` from GitHub Releases → installs to `/Applications` → **removes the quarantine flag for the user** (Gatekeeper bypass for un-notarized builds) → opens it. The target machine needs no bun/pi/ffprobe/global vn (all bundled).
+
+**First launch**: the app lands on Settings → fill in identity + your own Volcano ASR/TOS keys + proxy (BYOK) → save → click "Sign in to ChatGPT" in the Status panel (one-time browser authorization). The GUI then installs and loads the background LaunchAgent (pointing at the bundled engine); plug in the recorder and transcription + notes happen automatically.
+
+> The background agent label is `sh.fastagent.voicenote` (same as the CLI version; only one exists per machine). If the `.app` is moved, open it once to recalibrate the plist.
+
+**Upgrades**: since 0.1.9 the app has a built-in updater — open the app → "Settings → Software update" → "Check for updates"; when a new version appears, click "Download & install"; the app restarts automatically with config/notes preserved. For first installs, or upgrades from 0.1.8 and earlier (which had no updater), re-run the one-line install script above.
+
+### Maintainers: packaging + release
+
+**Automatic (recommended)**: push an `app-v*` tag to trigger `.github/workflows/release-app.yml`:
+
+```bash
+git tag app-v0.1.0 && git push --tags
+```
+
+**One `app-v*` tag = one Release covering mac + Windows.** `release-app.yml` is a single workflow: mac (universal + ad-hoc deep signing) and Windows (NSIS) build in parallel, then the `release` job publishes. Each Release carries:
+
+- **First-install packages** `VoiceNote.zip` (mac) / `VoiceNote-setup.exe` (win) — fetched by `install-app.*` from `releases/latest/download/...`;
+- **Updater artifacts** `VoiceNote.app.tar.gz` + `latest.json` — used by the in-app Tauri updater (Settings → Software update).
+
+> The updater needs signing secrets `TAURI_SIGNING_PRIVATE_KEY` / `TAURI_SIGNING_PRIVATE_KEY_PASSWORD` (generated with `tauri signer generate`; the public key goes in `tauri.conf.json`); the `preflight` job blocks the release while the pubkey is still a placeholder.
+
+> Use `app-v*` (distinct from the CLI's `v*` npm release tags). Artifacts are **universal** (x86_64 + arm64), working on both Intel and Apple Silicon.
+
+**Manual**:
+
+```bash
+cd app
+bash scripts/package.sh          # → app/release/VoiceNote-<version>.zip (~110MB)
+gh release create app-v0.1.0 app/release/VoiceNote-<version>.zip#VoiceNote.zip -t "VoiceNote 0.1.0" -n "Desktop app"
+```
+
+The asset name must be **`VoiceNote.zip`** (`install-app.sh` fetches `releases/latest/download/VoiceNote.zip`). For local testing bypass the Release with: `VOICENOTE_APP_URL=file:///path/to/VoiceNote.zip bash scripts/install-app.sh`.
+
+### Signing / notarization (no `xattr`, double-click to run)
+
+JIT entitlements are in place (`src-tauri/entitlements.plist`: `allow-jit` etc. for bun/vn; referenced from `tauri.conf.json`). `scripts/sign-macos.sh` performs inside-out deep signing (hardened runtime + entitlements):
+
+```bash
+# Internal ad-hoc (JIT verified to survive under hardened runtime)
+bash scripts/sign-macos.sh /Applications/VoiceNote.app
+
+# Official distribution (requires a Developer ID certificate, Apple Developer Program $99/yr)
+bash scripts/sign-macos.sh VoiceNote.app "Developer ID Application: NAME (TEAMID)"
+xcrun notarytool submit ... && xcrun stapler staple VoiceNote.app
+```
+
+## License
+
+MIT