@vocoder/cli 0.1.3 → 0.1.4

package/README.md

@@ -1,127 +1,130 @@
 # @vocoder/cli
 
-CLI for Vocoder translation workflows.
+Command-line tool for Vocoder. Handles project setup, string extraction from source code, and translation synchronization.
 
-Commands:
-
-- `vocoder init`
-- `vocoder sync`
-- `vocoder wrap`
-
-## Install
+## Installation
 
 ```bash
-pnpm add -D @vocoder/cli
+npm install -g @vocoder/cli
 ```
 
-## `vocoder sync`
-
-Extracts translatable strings, sends them to Vocoder, then generates runtime artifacts for `@vocoder/react`.
+Or use directly with npx:
 
-Generated output:
-
-`node_modules/@vocoder/generated`
+```bash
+npx vocoder <command>
+```
 
-Includes:
+## Commands
 
-- `manifest.mjs`
-- `manifest.cjs`
-- `<locale>.js` files
-- `package.json` exports map
+### `vocoder init`
 
-### Typical usage
+Connect your repository to Vocoder.
 
 ```bash
-pnpm exec vocoder sync
+vocoder init
 ```
 
-Add to build pipeline:
-
-```json
-{
-  "scripts": {
-    "prebuild": "pnpm exec vocoder sync",
-    "build": "next build"
-  }
-}
-```
+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.
 
-### Options
+**Options:**
 
-- `--include <pattern>` (repeatable)
-- `--exclude <pattern>` (repeatable)
-- `--branch <name>`
-- `--force`
-- `--dry-run`
-- `--verbose`
+| 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`) |
 
-## `vocoder wrap`
+### `vocoder sync`
 
-Scans source files and wraps likely user-facing strings with `<T>` / `t()` patterns.
+Extract translatable strings from your source code and push them to Vocoder for translation.
 
 ```bash
-pnpm exec vocoder wrap
+vocoder sync
 ```
 
-Options:
+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)
 
-- `--include <pattern>` (repeatable)
-- `--exclude <pattern>` (repeatable)
-- `--dry-run`
-- `--interactive`
-- `--confidence <high|medium|low>`
-- `--verbose`
+**Options:**
 
-## Configuration
+| 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 |
 
-Config priority:
+#### Sync Modes
 
-1. CLI flags
-2. environment variables
-3. defaults
+- **`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.
 
-### Environment variables
+### `vocoder wrap`
+
+Automatically wrap string literals in your source code with `<T>` and `t()`.
 
 ```bash
-VOCODER_API_KEY=vc_xxx
-VOCODER_API_URL=https://vocoder.app
-VOCODER_EXTRACTION_PATTERN=src/**/*.{tsx,jsx,ts,js}
+vocoder wrap
 ```
 
-`VOCODER_API_KEY` must come from the environment.
+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).
 
-## `vocoder init`
+**Options:**
 
-Bootstraps a project by opening a browser authorization flow, then provisioning
-a workspace/project API key.
+| Flag | Description |
+|---|---|
+| `--include <pattern>` | Glob pattern(s) to include (repeatable) |
+| `--exclude <pattern>` | Glob pattern(s) to exclude (repeatable) |
+| `--dry-run` | Preview changes without modifying files |
+| `--interactive` | Confirm each string interactively |
+| `--confidence <level>` | Minimum confidence: `high`, `medium`, `low` (default: `high`) |
+| `--verbose` | Detailed output |
 
-During browser completion, you can paste a DeepL API key (BYOK) or reuse an
-existing org-level DeepL key.
+## Environment Variables
 
-```bash
-pnpm exec vocoder init
-```
+| 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`) |
 
-## Troubleshooting
+The CLI reads `.env` files in the project root automatically.
 
-### `VOCODER_API_KEY is required`
+## String Extraction
 
-Set `VOCODER_API_KEY` in `.env` or your environment.
+The CLI uses Babel to parse JSX/TSX files and extract strings from:
 
-### No strings found
+- `<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!')`
 
-Use `<T>` (from `@vocoder/react`) around translatable JSX text.
+It tracks imports from `@vocoder/react` to ensure only Vocoder components are extracted (not unrelated components that happen to be named `T`).
 
-### Wrong branch / skipped sync
+Each extracted string includes:
+- The source text (used as the translation key)
+- File path and line number
+- Optional `context` and `formality` props
 
-Use:
+## Git Integration
 
-```bash
-pnpm exec vocoder sync --branch main
-```
+The CLI auto-detects the repository and branch:
 
-or force:
+- **Repository:** Reads the git remote URL and normalizes it to a canonical format (`github:owner/repo`)
+- **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
 
-```bash
-pnpm exec vocoder sync --force
-```
+## License
+
+MIT