@vocoder/cli 0.1.7 → 0.1.9

package/README.md

@@ -8,7 +8,7 @@ Command-line tool for Vocoder. Handles project setup, string extraction, and tra
 npm install -g @vocoder/cli
 ```
 
-Or use directly with npx:
+Or use without installing:
 
 ```bash
 npx vocoder <command>
@@ -18,120 +18,88 @@ npx vocoder <command>
 
 ### `vocoder init`
 
-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).
+Connect your repository to Vocoder. Runs an interactive TUI that handles authentication, workspace setup, and project configuration — all in the terminal. Only one browser step is required (GitHub authorization), and only on first run.
 
 ```bash
 vocoder init
 ```
 
-**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.
+**First-time setup:**
 
-**Full flow:**
+The CLI opens the Vocoder GitHub App installation page. Authorizing the App creates your account and workspace in one step — no separate sign-up required.
 
 ```
-◆  Vocoder Setup
-
-●  Open the link below to sign in or create your account:
-◇  Authentication URL ──────────────────────────────────────╮
-│                                                            │
-│  https://vocoder.app/auth/cli?session=<token>             │
-│                                                            │
-├────────────────────────────────────────────────────────────
+┌  Vocoder Setup
 
+◆  Opening GitHub to connect your account...
+│  Authorize Vocoder and install the GitHub App in one step.
+│
+│  https://github.com/apps/vocoder/installations/new?state=...
+│
 ◆  Open in your browser? › Yes
 
-◒  Waiting for authentication...
-◇  Authenticated as eric@example.com
+◒  Waiting for GitHub authorization...
 
-◒  Loading workspaces...
-◆  Select workspace
-│  ● My Workspace  (2 projects)
-│  ○ Create new workspace
-└
+◇  Connected as @username — workspace: username
+
+◆  App Directory (Optional)
+│  Leave blank to cover the entire repository (or enter a subdirectory for monorepos)
+
+◆  Source language (type to search)
+│  English — en
 
-◇  Workspace: My Workspace
+◆  Target languages (type to search, space to select)
+│  ◼ Spanish — es
 
-◆  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
+◆  Target branches
+│  ◼ 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
+◆  Step 2: Wrap your app with VocoderProvider
+◆  Step 3: Mark strings for translation with <T>
 
 ◆  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.
+◇  You're all set.
 ```
 
-**Returning user (stored token, existing workspace):**
+**Returning user (stored credentials):**
 
-No browser opens. The stored auth token is verified, workspaces are listed, and the flow continues directly in the terminal.
+No browser opens. The stored token is verified and the flow continues in the terminal.
 
 ```
-◆  Vocoder Setup
+┌  Vocoder Setup
 
-◒  Checking authentication...
-◇  Authenticated as eric@example.com
+◇  Authenticated as user@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.
-
+│  ● my-workspace  (3 projects)
+│  ○ + Create new workspace
 ```
-◆  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.
+**Monorepo support:**
 
-◇  Connected to GitHub as itsmoops
-```
+When running `vocoder init` from a subdirectory of a git repository, the CLI automatically suggests that subdirectory as the app directory. Each app in a monorepo should be set up as a separate Vocoder project.
 
 **Options:**
 
 | Flag | Description |
 |---|---|
-| `--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"
-}
-```
+| `--yes` | Skip the "Open in your browser?" confirmation |
+| `--ci` | Non-interactive mode. Prints `VOCODER_AUTH_URL: <url>` to stdout instead of opening a browser. Intended for CI environments where the browser step is driven externally. |
 
-Tokens never expire. Use `vocoder logout` to revoke.
+**Stored credentials:**
 
-**Token priority:**
+After first sign-in, the CLI stores credentials at `~/.config/vocoder/auth.json` (mode `0600`). Tokens do not expire. Use `vocoder logout` to revoke.
 
-| Command | Token source |
+**Token resolution:**
+
+| Command | Source |
 |---|---|
 | `vocoder init` | `VOCODER_AUTH_TOKEN` env var → `~/.config/vocoder/auth.json` |
 | `vocoder sync` | `VOCODER_API_KEY` env var → `.env` file |
@@ -141,13 +109,13 @@ Tokens never expire. Use `vocoder logout` to revoke.
 
 ### `vocoder sync`
 
-Submit extracted strings for translation and retrieve results.
+Extract translatable strings from your source code and submit them for translation.
 
 ```bash
 vocoder sync
 ```
 
-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.
+Reads `VOCODER_API_KEY` from environment or `.env`. Detects `<T>` and `t()` usages, submits them to Vocoder, and polls until translations are returned. Writes locale JSON files to the configured output path.
 
 **Options:**
 
@@ -161,13 +129,13 @@ Reads `VOCODER_API_KEY` from environment or `.env`. Extracts `<T>` and `t()` usa
 
 ### `vocoder logout`
 
-Revoke the stored auth token and clear `~/.config/vocoder/auth.json`.
+Revoke the stored credentials 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.
+The token is also revoked server-side.
 
 ---
 
@@ -177,69 +145,28 @@ Print the currently authenticated user.
 
 ```bash
 vocoder whoami
-# Authenticated as eric@example.com (My Workspace)
+# Authenticated as user@example.com (my-workspace)
 ```
 
 ---
 
-### `vocoder wrap`
-
-Automatically wrap string literals in your source code with `<T>` and `t()`.
-
-```bash
-vocoder wrap
-```
-
-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:**
-
-| 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 |
-
----
-
 ## 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 same local server pattern is used for the GitHub App install callback.
-
----
-
-## String Extraction
-
-The `wrap` command uses Babel to parse JSX/TSX files and detect strings that are likely user-facing:
+`vocoder init` opens exactly one browser window, and only on first run. The browser is used to authorize the Vocoder GitHub App — this simultaneously authenticates you and connects your GitHub account, so no separate sign-up is needed.
 
-- 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
+Once the GitHub authorization is complete, the browser redirects back and the CLI receives your credentials automatically via a local callback server. The rest of setup happens in the terminal.
 
-It tracks imports from `@vocoder/react` to avoid double-wrapping strings already marked for translation.
+On subsequent runs, the stored token is used directly and no browser is needed.
 
 ---
 
 ## Git Integration
 
-The CLI auto-detects the repository and branch:
+The CLI auto-detects repository context from the working directory:
 
-- **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
+- **Repository:** Reads the git remote URL and normalizes it to `github:owner/repo`
+- **Branch:** Checks CI environment variables first (GitHub Actions, Vercel, Netlify, etc.), then falls back to `.git/HEAD`
+- **App directory:** For monorepos, computes the relative path from the git root to `process.cwd()`
 
 ---
 
@@ -248,7 +175,7 @@ The CLI auto-detects the repository and branch:
 | 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_AUTH_TOKEN` | `init` | Override stored user token (`vcu_` prefix) |
 | `VOCODER_API_URL` | All commands | Override API base URL (default: `https://vocoder.app`) |
 
 ---

package/dist/bin.mjs

@@ -348,6 +348,10 @@ function parsePayload(raw) {
   if (raw.length === 0) {
     return null;
   }
+  const trimmed = raw.trimStart();
+  if (trimmed.startsWith("<!DOCTYPE") || trimmed.startsWith("<html")) {
+    return { message: "Unexpected response from server (received HTML). Check your network connection or try again." };
+  }
   try {
     return JSON.parse(raw);
   } catch {
@@ -426,10 +430,10 @@ var VocoderAPI = class {
    * Submit strings for translation
    * Project is determined from the API key
    */
-  stableTextKey(text) {
+  stableTextKey(text2) {
     let hash = 2166136261;
-    for (let i = 0; i < text.length; i++) {
-      hash ^= text.charCodeAt(i);
+    for (let i = 0; i < text2.length; i++) {
+      hash ^= text2.charCodeAt(i);
       hash = Math.imul(hash, 16777619);
     }
     return `SK_TEXT_${(hash >>> 0).toString(16).toUpperCase().padStart(8, "0")}`;
@@ -440,9 +444,9 @@ var VocoderAPI = class {
     }
     const first = entries[0];
     if (typeof first === "string") {
-      return entries.map((text) => ({
-        key: this.stableTextKey(text),
-        text
+      return entries.map((text2) => ({
+        key: this.stableTextKey(text2),
+        text: text2
       }));
     }
     return entries.map((entry, index) => ({
@@ -1384,6 +1388,19 @@ async function runProjectCreate(params) {
   }
   const languageOptions = buildLanguageOptions(rawLocales);
   const localeOptions = buildLocaleOptions(rawLocales);
+  const rawScope = await p3.text({
+    message: "App directory (leave blank for the entire repo)",
+    placeholder: "e.g. apps/web",
+    initialValue: params.defaultScopePath ?? "",
+    validate(value) {
+      const v = value.trim();
+      if (!v) return;
+      if (v.startsWith("/")) return "Use a relative path, not an absolute path";
+      if (v.includes("..")) return 'Path must not contain ".."';
+    }
+  });
+  if (p3.isCancel(rawScope)) return null;
+  const scopePath = rawScope.trim();
   const sourceLocale = await searchSelectLocale(
     languageOptions,
     "Source language (the language your code is written in)",
@@ -1428,7 +1445,7 @@ async function runProjectCreate(params) {
       targetLocales,
       targetBranches,
       translationTriggers: ["push"],
-      scopePaths: [],
+      scopePaths: scopePath ? [scopePath] : [],
       repoCanonical
     });
     p3.log.success(`Project ${chalk4.bold(result.projectName)} created!`);
@@ -2019,7 +2036,8 @@ async function init(options = {}) {
       defaultName: identity?.repoCanonical ? identity.repoCanonical.split("/").pop() : void 0,
       defaultSourceLocale: "en",
       repoCanonical: identity?.repoCanonical,
-      defaultBranches: ["main"]
+      defaultBranches: ["main"],
+      defaultScopePath: identity?.repoScopePath
     });
     if (!projectResult) {
       p5.log.error("Project creation failed. Run `vocoder init` again.");