@vocoder/cli 0.10.0 → 0.12.0

package/dist/lib.d.mts

@@ -67,8 +67,6 @@ interface ExtractedString {
     formality?: "formal" | "informal" | "neutral" | "auto";
     /** Detected UI role from JSX parent element or prop. e.g. "button_label", "heading", "input_placeholder" */
     uiRole?: string;
-    /** Feature area inferred from file path. e.g. "checkout", "auth", "settings" */
-    featureArea?: string;
 }
 declare class StringExtractor {
     extractFromProject(pattern: string | string[], projectRoot?: string, excludePattern?: string | string[]): Promise<ExtractedString[]>;
@@ -80,12 +78,22 @@ interface LocaleInfo {
 }
 type LocalesMap = Record<string, LocaleInfo>;
 type EffectiveSyncMode = "required" | "best-effort";
+type RequestedSyncMode = "auto" | EffectiveSyncMode;
 interface SyncPolicyConfig {
     blockingBranches: string[];
     blockingMode: EffectiveSyncMode;
     nonBlockingMode: EffectiveSyncMode;
     defaultMaxWaitMs: number;
 }
+interface RepoIdentityPayload {
+    repoCanonical?: string;
+    repoAppDir?: string;
+    commitSha?: string;
+}
+interface LocalConfig {
+    apiKey: string;
+    apiUrl: string;
+}
 interface APIProjectConfig {
     projectName: string;
     organizationName: string;
@@ -96,6 +104,13 @@ interface APIProjectConfig {
     primaryBranch?: string;
     syncPolicy: SyncPolicyConfig;
 }
+interface TranslationStringEntry {
+    key: string;
+    text: string;
+    context?: string;
+    formality?: "formal" | "informal" | "neutral" | "auto";
+    uiRole?: string;
+}
 interface TranslationBatchResponse {
     batchId: string;
     newStrings: number;
@@ -134,7 +149,7 @@ interface TranslationSnapshotResponse {
 }
 interface LimitErrorResponse {
     errorCode: "LIMIT_EXCEEDED" | "INSUFFICIENT_CREDITS";
-    limitType: "organizations" | "projects" | "git_connections" | "members" | "providers" | "translation_chars" | "source_strings" | "credits";
+    limitType: "organizations" | "projects" | "git_connections" | "members" | "providers" | "translation_chars" | "source_strings" | "target_locales" | "credits";
     planId: string;
     current: number;
     required: number;
@@ -148,6 +163,38 @@ interface SyncPolicyErrorResponse {
     boundRepoLabel?: string | null;
     boundScopePath?: string | null;
 }
+interface InitStartResponse {
+    sessionId: string;
+    deviceCode: string;
+    verificationUrl: string;
+    expiresAt: string;
+    poll: {
+        token: string;
+        intervalSeconds: number;
+    };
+}
+type InitStatusResponse = {
+    status: "pending";
+    pollIntervalSeconds: number;
+    expiresAt: string;
+    message?: string;
+} | {
+    status: "failed";
+    message: string;
+} | {
+    status: "completed";
+    credentials: {
+        apiKey: string;
+        apiUrl: string;
+        organizationId: string;
+        organizationName: string;
+        projectId: string;
+        projectName: string;
+        sourceLocale: string;
+        targetLocales: string[];
+        targetBranches?: string[];
+    };
+};
 
 type PackageManager = "pnpm" | "npm" | "yarn" | "bun";
 type DetectedFramework = "nextjs" | "vite" | "remix" | "nuxt" | "sveltekit" | "gatsby" | "angular" | null;
@@ -185,6 +232,313 @@ declare function getPackagesToInstall(detection: LocalDetectionResult): {
     runtimePackages: string[];
 };
 
+declare class VocoderAPIError extends Error {
+    readonly status: number;
+    readonly payload: unknown;
+    readonly limitError: LimitErrorResponse | null;
+    readonly syncPolicyError: SyncPolicyErrorResponse | null;
+    constructor(params: {
+        message: string;
+        status: number;
+        payload: unknown;
+        limitError?: LimitErrorResponse | null;
+        syncPolicyError?: SyncPolicyErrorResponse | null;
+    });
+}
+declare class VocoderAPI {
+    private apiUrl;
+    private apiKey;
+    constructor(config: LocalConfig);
+    private request;
+    /**
+     * Fetch project configuration from API
+     * Project is determined from the API key
+     */
+    getProjectConfig(): Promise<APIProjectConfig>;
+    /**
+     * Submit strings for translation
+     * Project is determined from the API key
+     */
+    private stableTextKey;
+    private normalizeStringEntries;
+    submitTranslation(branch: string, entries: string[] | TranslationStringEntry[], targetLocales: string[], options?: {
+        requestedMode?: RequestedSyncMode;
+        requestedMaxWaitMs?: number;
+        clientRunId?: string;
+        force?: boolean;
+        /** From vocoder.config.ts — synced to ProjectApp on every push */
+        appIndustry?: string;
+    }, repoIdentity?: RepoIdentityPayload): Promise<TranslationBatchResponse>;
+    /**
+     * Check translation status
+     */
+    getTranslationStatus(batchId: string): Promise<TranslationStatusResponse>;
+    getTranslationSnapshot(params: {
+        branch: string;
+        targetLocales: string[];
+    }): Promise<TranslationSnapshotResponse>;
+    /**
+     * Wait for translation to complete with polling
+     */
+    waitForCompletion(batchId: string, timeout?: number, onProgress?: (progress: number) => void): Promise<{
+        translations: Record<string, Record<string, string>>;
+        localeMetadata?: Record<string, {
+            nativeName: string;
+            dir?: "rtl";
+        }>;
+    }>;
+    startInitSession(input: {
+        projectName?: string;
+        sourceLocale?: string;
+        targetLocales?: string[];
+        repoCanonical?: string;
+        repoAppDir?: string;
+    }): Promise<InitStartResponse>;
+    getInitSessionStatus(params: {
+        sessionId: string;
+        pollToken: string;
+    }): Promise<InitStatusResponse>;
+    /**
+     * Start a CLI auth session. Returns `{ sessionId, verificationUrl, expiresAt }`.
+     * `sessionId` is the raw poll token — keep it secret, used for polling.
+     */
+    startCliAuthSession(callbackPort?: number, repoCanonical?: string): Promise<{
+        sessionId: string;
+        verificationUrl: string;
+        installUrl?: string;
+        expiresAt: string;
+    }>;
+    /**
+     * Poll for CLI auth session completion.
+     * Returns `{ token }` on success, throws on failure/expiry.
+     * The server returns HTTP 202 while still pending.
+     */
+    pollCliAuthSession(pollToken: string): Promise<{
+        status: "pending";
+    } | {
+        status: "complete";
+        token: string;
+        organizationId?: string;
+    } | {
+        status: "failed";
+        reason: string;
+    }>;
+    /**
+     * Validate a CLI user token and return the authenticated user's info.
+     * Used by the CLI to verify stored credentials on startup.
+     */
+    getCliUserInfo(userToken: string): Promise<{
+        userId: string;
+        email: string;
+        name: string | null;
+    }>;
+    /**
+     * Revoke the given CLI user token server-side.
+     */
+    revokeCliToken(userToken: string): Promise<void>;
+    listWorkspaces(userToken: string, params?: {
+        repo?: string;
+    }): Promise<{
+        workspaces: Array<{
+            id: string;
+            name: string;
+            planId: string;
+            maxProjects: number;
+            projectCount: number;
+            hasGitHubConnection: boolean;
+            connectionLabel: string | null;
+            /** null when no `repo` param was provided */
+            coversRepo: boolean | null;
+            installationConfigureUrl: string | null;
+        }>;
+        canCreateWorkspace: boolean;
+    }>;
+    listProjects(userToken: string, organizationId: string): Promise<Array<{
+        id: string;
+        name: string;
+        sourceLocale: string;
+        targetLocales: string[];
+        targetBranches: string[];
+    }>>;
+    regenerateProjectApiKey(userToken: string, projectId: string): Promise<{
+        apiKey: string;
+    }>;
+    startCliGitHubInstall(userToken: string, params: {
+        organizationId?: string;
+        callbackPort?: number;
+    }): Promise<{
+        installUrl: string;
+    }>;
+    /**
+     * Start the "link existing installation" discovery flow.
+     * Unlike startCliGitHubOAuth, this requires no bearer token — the Vocoder
+     * account is created from the OAuth code in the callback.
+     */
+    startCliGitHubLinkSession(sessionId: string, callbackPort?: number): Promise<{
+        oauthUrl: string;
+    }>;
+    startCliGitHubOAuth(userToken: string, params: {
+        organizationId?: string;
+        callbackPort?: number;
+    }): Promise<{
+        oauthUrl: string;
+    }>;
+    getCliGitHubDiscovery(userToken: string): Promise<{
+        installations: Array<{
+            installationId: number;
+            accountLogin: string;
+            accountType: string;
+            isSuspended: boolean;
+            conflictLabel: string | null;
+        }>;
+    }>;
+    claimCliGitHubInstallation(userToken: string, params: {
+        installationId: string;
+        organizationId: string | null;
+    }): Promise<{
+        organizationId: string;
+        organizationName: string;
+        connectionLabel: string;
+        repoCount: number;
+    }>;
+    /**
+     * Add a target locale to the project.
+     * Idempotent: returns the current list unchanged if the locale is already configured.
+     * Project determined from API key.
+     *
+     * @throws {VocoderAPIError} status 422 for invalid/unsupported locale code
+     * @throws {VocoderAPIError} status 403 with limitError.limitType "target_locales" when plan limit reached
+     */
+    addLocale(locale: string, repoCanonical?: string): Promise<{
+        targetLocales: string[];
+    }>;
+    /**
+     * Remove a target locale from the project.
+     * Idempotent: returns the current list unchanged if the locale is not configured.
+     * Project determined from API key.
+     *
+     * @throws {VocoderAPIError} on auth or server errors
+     */
+    removeLocale(locale: string, repoCanonical?: string): Promise<{
+        targetLocales: string[];
+    }>;
+    listLocales(userToken: string): Promise<{
+        sourceLocales: Array<{
+            code: string;
+            name: string;
+            nativeName?: string;
+        }>;
+        targetLocales: Array<{
+            code: string;
+            name: string;
+            nativeName?: string;
+        }>;
+    }>;
+    listCompatibleLocales(userToken: string, sourceLocale: string): Promise<Array<{
+        code: string;
+        name: string;
+        nativeName?: string;
+    }>>;
+    createProject(userToken: string, params: {
+        organizationId: string;
+        name: string;
+        sourceLocale: string;
+        targetLocales: string[];
+        targetBranches: string[];
+        appDirs: string[];
+        repoCanonical?: string;
+    }): Promise<{
+        projectId: string;
+        projectName: string;
+        apiKey: string;
+        sourceLocale: string;
+        targetLocales: string[];
+        targetBranches: string[];
+        repositoryBound: boolean;
+        configureUrl?: string;
+    }>;
+    /**
+     * Look up all project apps for a given repo. Returns info about exact matches,
+     * existing apps in other scopes, and whether a whole-repo app exists.
+     * No auth required.
+     */
+    lookupProjectByRepo(params: {
+        repoCanonical: string;
+        appDir: string;
+    }): Promise<{
+        exactMatch: {
+            projectId: string;
+            projectName: string;
+            organizationName: string;
+            sourceLocale?: string;
+            targetBranches?: string[];
+        } | null;
+        existingApps: Array<{
+            appDir: string;
+            projectId: string;
+            projectName: string;
+            organizationName: string;
+        }>;
+        hasWholeRepoApp: boolean;
+    }>;
+    /**
+     * Add a new ProjectApp to an existing project (monorepo: new app directory).
+     * Does not check plan limits — no new project is created.
+     */
+    createProjectApp(userToken: string, params: {
+        projectId: string;
+        appDir: string;
+        sourceLocale: string;
+        targetLocales: string[];
+        targetBranches: string[];
+        repoCanonical: string;
+    }): Promise<{
+        appId: string;
+        projectId: string;
+        projectName: string;
+        apiKey: string;
+        appDir: string;
+    }>;
+}
+
+interface AuthData {
+    token: string;
+    userId: string;
+    email: string;
+    name: string | null;
+    createdAt: string;
+}
+declare function readAuthData(): AuthData | null;
+declare function writeAuthData(data: AuthData): void;
+/**
+ * Result of checking a stored CLI auth token against the API:
+ * - "valid"   — token is good; user info is returned
+ * - "expired" — token rejected (non-404); user record still exists → reauth,
+ *               do NOT run the GitHub App install flow again
+ * - "gone"    — 404; user record deleted → treat as first-time setup
+ * - "none"    — no token on disk
+ */
+type StoredAuthStatus = {
+    status: "valid";
+    token: string;
+    userId: string;
+    email: string;
+    name: string | null;
+} | {
+    status: "expired";
+} | {
+    status: "gone";
+} | {
+    status: "none";
+};
+/**
+ * Verify the stored CLI auth token. Clears the token on failure.
+ * Shared by the CLI (`commands/init.ts`) and the MCP (`tools/project-init.ts`)
+ * so reauth detection stays in sync.
+ */
+declare function verifyStoredAuth(api: VocoderAPI): Promise<StoredAuthStatus>;
+declare function clearAuthData(): void;
+
 interface SetupSnippets {
     pluginStep: {
         file: string;
@@ -209,4 +563,4 @@ declare function getSetupSnippets(params: {
     targetBranches: string[];
 }): SetupSnippets;
 
-export { type APIProjectConfig, type DetectedEcosystem, type DetectedFramework, type ExtractedString, type LimitErrorResponse, type LocalDetectionResult, type LocaleInfo, type LocalesMap, type PackageManager, type SetupSnippets, StringExtractor, type SyncPolicyConfig, type SyncPolicyErrorResponse, type TranslationBatchResponse, type TranslationSnapshotResponse, type TranslationStatusResponse, type VocoderConfig, buildInstallCommand, defineConfig, detectLocalEcosystem, getPackagesToInstall, getSetupSnippets, loadVocoderConfig };
+export { type APIProjectConfig, type AuthData, type DetectedEcosystem, type DetectedFramework, type ExtractedString, type LimitErrorResponse, type LocalDetectionResult, type LocaleInfo, type LocalesMap, type PackageManager, type SetupSnippets, type StoredAuthStatus, StringExtractor, type SyncPolicyConfig, type SyncPolicyErrorResponse, type TranslationBatchResponse, type TranslationSnapshotResponse, type TranslationStatusResponse, VocoderAPI, VocoderAPIError, type VocoderConfig, buildInstallCommand, clearAuthData, defineConfig, detectLocalEcosystem, getPackagesToInstall, getSetupSnippets, loadVocoderConfig, readAuthData, verifyStoredAuth, writeAuthData };

package/dist/lib.mjs

@@ -1,12 +1,18 @@
 import { createRequire as __createRequire } from 'module'; const require = __createRequire(import.meta.url);
 import {
   StringExtractor,
+  VocoderAPI,
+  VocoderAPIError,
   buildInstallCommand,
+  clearAuthData,
   detectLocalEcosystem,
   getPackagesToInstall,
   getSetupSnippets,
-  loadVocoderConfig
-} from "./chunk-73U4VZYP.mjs";
+  loadVocoderConfig,
+  readAuthData,
+  verifyStoredAuth,
+  writeAuthData
+} from "./chunk-XUCVAFBG.mjs";
 
 // ../config/src/index.ts
 function defineConfig(config) {
@@ -14,11 +20,17 @@ function defineConfig(config) {
 }
 export {
   StringExtractor,
+  VocoderAPI,
+  VocoderAPIError,
   buildInstallCommand,
+  clearAuthData,
   defineConfig,
   detectLocalEcosystem,
   getPackagesToInstall,
   getSetupSnippets,
-  loadVocoderConfig
+  loadVocoderConfig,
+  readAuthData,
+  verifyStoredAuth,
+  writeAuthData
 };
 //# sourceMappingURL=lib.mjs.map

package/dist/lib.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../config/src/index.ts"],"sourcesContent":["/**\n * Supported app industry classifications.\n * Set once in vocoder.config.ts; synced to ProjectApp at extraction time.\n * Cannot be edited from the dashboard — config file is the source of truth.\n *\n * Keep in sync with APP_INDUSTRIES in\n * vocoder-app/lib/vocoder/translation/context-constants.ts.\n */\nexport type AppIndustry =\n\t| \"ecommerce\"\n\t| \"saas\"\n\t| \"healthcare\"\n\t| \"fintech\"\n\t| \"gaming\"\n\t| \"education\"\n\t| \"media\"\n\t| \"productivity\";\n\n/**\n * Translation formality level.\n * Can be set project-wide in vocoder.config.ts or overridden per-string\n * via <T formality=\"formal\"> (requires allowAiTranslations plan).\n */\nexport type Formality = \"formal\" | \"informal\" | \"neutral\";\n\nexport interface VocoderConfig {\n\t/** Glob patterns for files to extract strings from. */\n\tinclude?: string[];\n\t/** Glob patterns to exclude. */\n\texclude?: string[];\n\t/**\n\t * Git branches that trigger string extraction and translation.\n\t * Synced to the Vocoder dashboard on each push — change here to update.\n\t */\n\ttargetBranches?: string[];\n\t/**\n\t * Directory to write translated locale files after sync (optional).\n\t * If set, `vocoder sync` writes {locale}.json files to this path.\n\t */\n\tlocalesPath?: string;\n\t/**\n\t * The industry or domain of this application.\n\t * Used to improve translation quality for domain-specific terminology\n\t * and to isolate cache entries by industry in the global translation cache.\n\t * Synced to ProjectApp at extraction time.\n\t */\n\tappIndustry?: AppIndustry;\n\t/**\n\t * Project-wide default formality level for translations.\n\t * Can be overridden per-string via <T formality=\"...\"> on the AI plan.\n\t * Synced to ProjectApp at extraction time.\n\t */\n\tformality?: Formality;\n}\n\n/** Type helper for vocoder.config.ts — provides autocomplete and type checking. */\nexport function defineConfig(config: VocoderConfig): VocoderConfig {\n\treturn config;\n}\n\n/**\n * Canonical translation bundle format shared by the build plugin and CLI.\n * Both read and write this shape — keeps cache files identical regardless of\n * which tool produced them.\n *\n * translations: locale → sourceKey (hash) → translated text\n * config.locales: locale metadata snapshot for the runtime\n */\nexport interface VocoderTranslationData {\n\tconfig: {\n\t\tsourceLocale: string;\n\t\ttargetLocales: string[];\n\t\tlocales: Record<string, {\n\t\t\tnativeName: string;\n\t\t\tdir?: \"rtl\";\n\t\t\tcurrencyCode?: string;\n\t\t\tordinalForms?: { type: \"suffix\"; suffixes: { zero?: string; one?: string; two?: string; few?: string; many?: string; other: string } } | { type: \"word\"; words: Record<string, Record<number, string>> };\n\t\t}>;\n\t};\n\ttranslations: Record<string, Record<string, string>>;\n\tupdatedAt: string | null;\n}\n"],"mappings":";;;;;;;;;;;AAwDO,SAAS,aAAa,QAAsC;AAClE,SAAO;AACR;","names":[]}
+{"version":3,"sources":["../../config/src/index.ts"],"sourcesContent":["/**\n * Supported app industry classifications.\n * Set once in vocoder.config.ts; synced to ProjectApp at extraction time.\n * Cannot be edited from the dashboard — config file is the source of truth.\n *\n * Keep in sync with APP_INDUSTRIES in\n * vocoder-app/lib/vocoder/translation/context-constants.ts.\n */\nexport type AppIndustry =\n\t| \"ecommerce\"\n\t| \"saas\"\n\t| \"healthcare\"\n\t| \"fintech\"\n\t| \"gaming\"\n\t| \"education\"\n\t| \"media\"\n\t| \"productivity\";\n\n/**\n * Translation formality level.\n * Can be set project-wide in vocoder.config.ts or overridden per-string\n * via <T formality=\"formal\"> (requires allowAiTranslations plan).\n */\nexport type Formality = \"formal\" | \"informal\" | \"neutral\";\n\nexport interface VocoderConfig {\n\t/** Glob patterns for files to extract strings from. */\n\tinclude?: string[];\n\t/** Glob patterns to exclude. */\n\texclude?: string[];\n\t/**\n\t * Git branches that trigger string extraction and translation.\n\t * Synced to the Vocoder dashboard on each push — change here to update.\n\t */\n\ttargetBranches?: string[];\n\t/**\n\t * Directory to write translated locale files after sync (optional).\n\t * If set, `vocoder sync` writes {locale}.json files to this path.\n\t */\n\tlocalesPath?: string;\n\t/**\n\t * The industry or domain of this application.\n\t * Used to improve translation quality for domain-specific terminology\n\t * and to isolate cache entries by industry in the global translation cache.\n\t * Synced to ProjectApp at extraction time.\n\t */\n\tappIndustry?: AppIndustry;\n\t/**\n\t * Project-wide default formality level for translations.\n\t * Can be overridden per-string via <T formality=\"...\"> on the AI plan.\n\t * Synced to ProjectApp at extraction time.\n\t */\n\tformality?: Formality;\n}\n\n/** Type helper for vocoder.config.ts — provides autocomplete and type checking. */\nexport function defineConfig(config: VocoderConfig): VocoderConfig {\n\treturn config;\n}\n\n/**\n * Canonical translation bundle format shared by the build plugin and CLI.\n * Both read and write this shape — keeps cache files identical regardless of\n * which tool produced them.\n *\n * translations: locale → sourceKey (hash) → translated text\n * config.locales: locale metadata snapshot for the runtime\n */\nexport interface VocoderTranslationData {\n\tconfig: {\n\t\tsourceLocale: string;\n\t\ttargetLocales: string[];\n\t\tlocales: Record<string, {\n\t\t\tnativeName: string;\n\t\t\tdir?: \"rtl\";\n\t\t\tcurrencyCode?: string;\n\t\t\tordinalForms?: { type: \"suffix\"; suffixes: { zero?: string; one?: string; two?: string; few?: string; many?: string; other: string } } | { type: \"word\"; words: Record<string, Record<number, string>> };\n\t\t}>;\n\t};\n\ttranslations: Record<string, Record<string, string>>;\n\tupdatedAt: string | null;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAwDO,SAAS,aAAa,QAAsC;AAClE,SAAO;AACR;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vocoder/cli",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "CLI tool for Vocoder translation workflow",
   "files": [
     "dist"
@@ -51,8 +51,8 @@
     "tsup": "^8.0.0",
     "typescript": "^5.4.0",
     "vitest": "^1.0.0",
-    "@vocoder/config": "0.10.0",
-    "@vocoder/extractor": "0.10.0"
+    "@vocoder/extractor": "0.12.0",
+    "@vocoder/config": "0.12.0"
   },
   "engines": {
     "node": ">=18"