@vocoder/cli 0.1.4 → 0.1.7

package/README.md

@@ -1,6 +1,6 @@
 # @vocoder/cli
 
-Command-line tool for Vocoder. Handles project setup, string extraction from source code, and translation synchronization.
+Command-line tool for Vocoder. Handles project setup, string extraction, and translation sync.
 
 ## Installation
 
@@ -18,59 +18,169 @@ npx vocoder <command>
 
 ### `vocoder init`
 
-Connect your repository to Vocoder.
+Connect your repository to Vocoder. Runs a full TUI-based onboarding flow — authentication, workspace selection, GitHub connection, and project configuration all happen in the terminal. A browser is opened only for steps that require OAuth (sign-in, GitHub App install).
 
 ```bash
 vocoder init
 ```
 
-The command detects your git remote and checks if a Vocoder project already exists for the repository. If found, it confirms the connection and prints next steps. If not, it opens a browser-based setup flow to create a new project.
+**Fast path:** If the current repository's remote is already linked to a Vocoder project, `init` detects it and prints the scaffold instructions immediately — no prompts, no browser.
+
+**Full flow:**
+
+```
+◆  Vocoder Setup
+
+●  Open the link below to sign in or create your account:
+◇  Authentication URL ──────────────────────────────────────╮
+│                                                            │
+│  https://vocoder.app/auth/cli?session=<token>             │
+│                                                            │
+├────────────────────────────────────────────────────────────
+
+◆  Open in your browser? › Yes
+
+◒  Waiting for authentication...
+◇  Authenticated as eric@example.com
+
+◒  Loading workspaces...
+◆  Select workspace
+│  ● My Workspace  (2 projects)
+│  ○ Create new workspace
+└
+
+◇  Workspace: My Workspace
+
+◆  Project name › my-app
+◆  Source language (type to search) › en → English — en
+◆  Target languages (type to search) › es → Spanish — es
+◆  Target branches (comma-separated) › main
+
+◒  Creating project...
+
+◆  Step 1: Add the plugin to vite.config.ts
+│  ...
+◆  Step 2: Add the provider to App.tsx
+│  ...
+◆  Step 3: Wrap translatable strings
+
+◆  Use Vocoder with Claude Code
+│  claude mcp add --scope project --transport stdio \
+│    --env VOCODER_API_KEY=vc_xxxx \
+│    vocoder -- npx -y @vocoder/mcp
+
+◆  You're all set.
+```
+
+**Returning user (stored token, existing workspace):**
+
+No browser opens. The stored auth token is verified, workspaces are listed, and the flow continues directly in the terminal.
+
+```
+◆  Vocoder Setup
+
+◒  Checking authentication...
+◇  Authenticated as eric@example.com
+
+◒  Loading workspaces...
+◆  Select workspace
+│  ● My Workspace  (2 projects)
+│  ○ Create new workspace
+└
+```
+
+**New workspace (GitHub App install):**
+
+If creating a new workspace, a second browser step installs the GitHub App. The CLI opens the install URL and waits for the browser to redirect back to a local callback server.
+
+```
+◆  Connect your new workspace to GitHub
+│  ● Install the Vocoder GitHub App
+│  ○ Link an existing installation
+└
+
+○  Opening GitHub to install the Vocoder App...
+   Complete the installation in your browser.
+
+◇  Connected to GitHub as itsmoops
+```
 
 **Options:**
 
 | Flag | Description |
 |---|---|
-| `--api-url <url>` | Override Vocoder API URL |
-| `--yes` | Skip confirmation prompts |
-| `--project-name <name>` | Pre-fill project name |
-| `--source-locale <locale>` | Pre-fill source locale |
-| `--target-locales <list>` | Comma-separated target locales (e.g., `es,fr,de`) |
+| `--yes` | Skip "Open in your browser?" confirmation |
+| `--ci` | Non-interactive mode. Prints the auth URL as `VOCODER_AUTH_URL: <url>` on its own line to stdout — no browser opens, no interactive prompts, no local callback server. The CLI polls `GET /api/cli/auth/session` every 2 seconds until the browser completes authentication. Intended for automated test harnesses that drive the browser step externally. |
+
+**Auth storage:**
+
+After sign-in, the CLI stores a persistent auth token at `~/.config/vocoder/auth.json` (mode `0600`). The file contains:
+
+```json
+{
+  "token": "vcu_...",
+  "apiUrl": "https://vocoder.app",
+  "userId": "...",
+  "email": "user@example.com",
+  "name": "User Name",
+  "createdAt": "2026-04-25T12:00:00.000Z"
+}
+```
+
+Tokens never expire. Use `vocoder logout` to revoke.
+
+**Token priority:**
+
+| Command | Token source |
+|---|---|
+| `vocoder init` | `VOCODER_AUTH_TOKEN` env var → `~/.config/vocoder/auth.json` |
+| `vocoder sync` | `VOCODER_API_KEY` env var → `.env` file |
+| MCP tools | `VOCODER_API_KEY` env var |
+
+---
 
 ### `vocoder sync`
 
-Extract translatable strings from your source code and push them to Vocoder for translation.
+Submit extracted strings for translation and retrieve results.
 
 ```bash
 vocoder sync
 ```
 
-This command:
-
-1. Detects the current git branch and repository
-2. Scans your source files for `<T>` components and `t()` calls
-3. Extracts the source text, file location, and any context/formality hints
-4. Sends the extracted strings to the Vocoder API
-5. Optionally waits for translations to complete (based on sync mode)
+Reads `VOCODER_API_KEY` from environment or `.env`. Extracts `<T>` and `t()` usages from source files, submits them to Vocoder, and polls until translations are returned. Writes locale JSON files to the configured output path.
 
 **Options:**
 
 | Flag | Description |
 |---|---|
-| `--branch <name>` | Override branch detection |
-| `--include <pattern>` | Glob pattern(s) to include (repeatable) |
-| `--exclude <pattern>` | Glob pattern(s) to exclude (repeatable) |
-| `--force` | Sync even if not on a target branch |
-| `--mode <mode>` | Sync mode: `auto`, `required`, or `best-effort` |
-| `--max-wait-ms <ms>` | Max wait time before fallback (milliseconds) |
-| `--no-fallback` | Fail instead of falling back to cached translations |
-| `--dry-run` | Show what would be synced without sending |
-| `--verbose` | Show detailed progress |
+| `--locale <code>` | Sync only this target locale |
+| `--dry-run` | Show what would be synced without submitting |
+| `--verbose` | Show extraction and sync details |
+
+---
+
+### `vocoder logout`
+
+Revoke the stored auth token and clear `~/.config/vocoder/auth.json`.
+
+```bash
+vocoder logout
+```
+
+Also revokes the token server-side so it can no longer be used for API calls.
+
+---
+
+### `vocoder whoami`
 
-#### Sync Modes
+Print the currently authenticated user.
 
-- **`auto`** (default) -- Checks the project's sync policy. Blocking branches (e.g., `main`, `production`) use `required` mode; other branches use `best-effort`.
-- **`required`** -- Waits for translations to complete before finishing. Fails if translations can't be completed within the timeout.
-- **`best-effort`** -- Sends strings for translation but doesn't wait. Falls back to the latest available translations.
+```bash
+vocoder whoami
+# Authenticated as eric@example.com (My Workspace)
+```
+
+---
 
 ### `vocoder wrap`
 
@@ -80,7 +190,7 @@ Automatically wrap string literals in your source code with `<T>` and `t()`.
 vocoder wrap
 ```
 
-Scans your JSX/TSX files for user-facing string literals and wraps them with the appropriate Vocoder translation markers. Uses AST analysis to detect strings that are likely user-facing (not keys, classnames, or internal identifiers).
+Scans JSX/TSX files for user-facing string literals and wraps them with the appropriate translation markers. Uses AST analysis to detect strings that are likely user-facing (not keys, classnames, or internal identifiers).
 
 **Options:**
 
@@ -93,29 +203,35 @@ Scans your JSX/TSX files for user-facing string literals and wraps them with the
 | `--confidence <level>` | Minimum confidence: `high`, `medium`, `low` (default: `high`) |
 | `--verbose` | Detailed output |
 
-## Environment Variables
+---
 
-| Variable | Required | Description |
-|---|---|---|
-| `VOCODER_API_KEY` | Yes (for `sync`) | API key for authenticating with the Vocoder API |
-| `VOCODER_API_URL` | No | Override API URL (default: `https://vocoder.app`) |
+## How `init` interacts with the browser
+
+The CLI never redirects the terminal to a URL or relies on the browser to complete setup. Instead:
+
+1. The CLI starts a local HTTP server on a random available port.
+2. It requests an auth session from Vocoder, passing the local port as the callback destination.
+3. The terminal displays the verification URL and (optionally) opens it in the system browser.
+4. After the user signs in, `vocoder.app/auth/cli` silently pings `localhost:<port>/callback?token=...` in the background.
+5. The CLI's local server receives the token instantly and the TUI continues — no polling delay.
+
+If the local server fails to bind (port conflict, firewall), the CLI falls back to polling `GET /api/cli/auth/session` every 2 seconds until the token is available.
 
-The CLI reads `.env` files in the project root automatically.
+The same local server pattern is used for the GitHub App install callback.
+
+---
 
 ## String Extraction
 
-The CLI uses Babel to parse JSX/TSX files and extract strings from:
+The `wrap` command uses Babel to parse JSX/TSX files and detect strings that are likely user-facing:
 
-- `<T>` component children: `<T>Hello, world!</T>`
-- `<T>` component `msg` prop: `<T msg="{count, plural, one {# item} other {# items}}" />`
-- `t()` function calls: `t('Hello, world!')`
+- JSX text content is wrapped with `<T>`
+- String props like `placeholder`, `title`, `aria-label` are wrapped with `t()`
+- Non-translatable strings (class names, keys, URLs) are left alone
 
-It tracks imports from `@vocoder/react` to ensure only Vocoder components are extracted (not unrelated components that happen to be named `T`).
+It tracks imports from `@vocoder/react` to avoid double-wrapping strings already marked for translation.
 
-Each extracted string includes:
-- The source text (used as the translation key)
-- File path and line number
-- Optional `context` and `formality` props
+---
 
 ## Git Integration
 
@@ -125,6 +241,18 @@ The CLI auto-detects the repository and branch:
 - **Branch:** Checks CI environment variables first (GitHub Actions, Vercel, Netlify, etc.), then falls back to reading `.git/HEAD`
 - **Scope path:** For monorepos, computes the relative path from the git root to the working directory
 
+---
+
+## Environment Variables
+
+| Variable | Used by | Purpose |
+|---|---|---|
+| `VOCODER_API_KEY` | `sync`, MCP | Project API key (`vc_` prefix) |
+| `VOCODER_AUTH_TOKEN` | `init` | Override stored user auth token (`vcu_` prefix) |
+| `VOCODER_API_URL` | All commands | Override API base URL (default: `https://vocoder.app`) |
+
+---
+
 ## License
 
 MIT