@localheroai/cli 0.0.2 → 0.0.3

package/README

@@ -0,0 +1,98 @@
+# LocalHero.ai CLI 🌍✨
+
+> Automatic translations for teams that ship
+
+LocalHero.ai is an AI-powered I18n translation service that seamlessly integrates with your development workflow. It automatically detects and translates I18n keys with missing translations, then saving any new translations directly to your repository. [Learn more at localhero.ai](https://localhero.ai/)
+
+## Features 🚀
+
+- 🤖 AI-powered translations that preserve your brand voice
+- 🔌 Seamless integration with Rails, React and other frameworks coming soon
+- 🚀 Automated workflow with GitHub Actions support
+- 📦 Works with YAML and JSON translation files
+
+## Getting Started 🏁
+
+1. Sign up for a free trial at [localhero.ai](https://localhero.ai/) (currently closed beta, get in touch if you are interested in trying it out)
+2. Get your API key from [localhero.ai/api-keys](https://localhero.ai/api-keys)
+3. Run the init command in your project:
+   ```bash
+   npx @localheroai/cli init
+   ```
+
+## Commands 👏
+
+### Initialize a Project
+
+```bash
+npx @localheroai/cli init
+```
+
+The init command helps you set up your project with LocalHero.ai. It will:
+- Detect your project type (Rails, React, or generic)
+- Link to an existing LocalHero.ai project
+- Configure translation paths and file patterns
+- Set up GitHub Actions (optional)
+- Import existing translations (optional)
+
+This creates a `localhero.json` configuration file in your project root that stores your project settings:
+- Project identifier
+- Source and target languages for translation
+- Translation file paths and patterns
+- Ignore patterns for files to exclude
+
+The configuration file is used by the tool to interact with your translations and the API.
+
+### Login
+
+```bash
+npx @localheroai/cli login
+```
+
+Authenticate with your LocalHero.ai account. Use this when:
+- Setting up a new development environment
+- Updating your API key
+- Verifying your authentication status
+
+### Translate
+
+```bash
+npx @localheroai/cli translate
+```
+
+Translating your missing keys:
+- Automatically detects missing translations and sends them to the Localhero.ai translation API for translation
+- Updates translation files with any new or update translations
+- It's run manually or by GitHub Actions
+
+## Environment Variables ⚙️
+
+Configure the CLI behavior with these environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `LOCALHERO_API_KEY` | Your LocalHero API key (get it at [localhero.ai/api-keys](https://localhero.ai/api-keys)) | Required |
+| `LOCALHERO_API_HOST` | API host for LocalHero (you typically don't need to change this) | https://api.localhero.ai |
+
+## GitHub Actions Integration 🤖
+
+LocalHero.ai automatically translate your I18n files when you push changes. During the `init` command, you'll be prompted to set up GitHub Actions.
+
+1. Add your API key to your repository secrets:
+   - Go to Settings > Secrets > Actions
+   - Create a new secret named `LOCALHERO_API_KEY`
+   - Add your API key as the value
+
+2. The workflow will:
+   - Run on push to your main branch
+   - Check for missing translations
+   - Create a pull request with new translations
+
+## Support 💬
+
+- Documentation: [localhero.ai/docs](https://docs.localhero.ai/docs)
+- Email: support@localhero.ai
+
+## License 📄
+
+MIT License - see LICENSE file for details

package/package.json

@@ -1,62 +1,62 @@
 {
-    "name": "@localheroai/cli",
-    "version": "0.0.2",
-    "description": "CLI tool for managing translations with LocalHero.ai",
-    "type": "module",
-    "main": "src/index.js",
-    "bin": {
-        "localheroai": "./src/cli.js"
+  "name": "@localheroai/cli",
+  "version": "0.0.3",
+  "description": "CLI tool for managing translations with LocalHero.ai",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "localheroai": "./src/cli.js"
+  },
+  "scripts": {
+    "start": "node src/cli.js",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "lint": "eslint .",
+    "postinstall": "chmod +x src/cli.js"
+  },
+  "keywords": [
+    "i18n",
+    "translation",
+    "cli",
+    "localization"
+  ],
+  "author": "LocalHero.ai",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "glob": "^10.3.10",
+    "inquirer": "^12.0.1",
+    "yaml": "^2.3.4"
+  },
+  "devDependencies": {
+    "@babel/preset-env": "^7.24.0",
+    "@inquirer/testing": "^2.1.36",
+    "@jest/globals": "^29.7.0",
+    "eslint": "^9.19.0",
+    "globals": "^15.14.0",
+    "jest": "^29.7.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "jest": {
+    "testEnvironment": "node",
+    "transform": {},
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.js$": "$1"
     },
-    "scripts": {
-        "start": "node src/cli.js",
-        "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
-        "lint": "eslint .",
-        "postinstall": "chmod +x src/cli.js"
-    },
-    "keywords": [
-        "i18n",
-        "translation",
-        "cli",
-        "localization"
-    ],
-    "author": "LocalHero.ai",
-    "license": "MIT",
-    "dependencies": {
-        "chalk": "^5.3.0",
-        "commander": "^12.0.0",
-        "dotenv": "^16.4.5",
-        "glob": "^10.3.10",
-        "inquirer": "^12.0.1",
-        "yaml": "^2.3.4"
-    },
-    "devDependencies": {
-        "@inquirer/testing": "^2.1.36",
-        "@jest/globals": "^29.7.0",
-        "eslint": "^9.14.0",
-        "jest": "^29.7.0",
-        "@babel/preset-env": "^7.24.0"
-    },
-    "engines": {
-        "node": ">=22.11.0"
-    },
-    "files": [
-        "src",
-        "README.md",
-        "LICENSE"
+    "testMatch": [
+      "**/tests/**/*.test.js"
     ],
-    "jest": {
-        "testEnvironment": "node",
-        "transform": {},
-        "moduleNameMapper": {
-            "^(\\.{1,2}/.*)\\.js$": "$1"
-        },
-        "testMatch": [
-            "**/tests/**/*.test.js"
-        ],
-        "testEnvironmentOptions": {
-            "extensionsToTreatAsEsm": [
-                ".js"
-            ]
-        }
+    "testEnvironmentOptions": {
+      "extensionsToTreatAsEsm": [
+        ".js"
+      ]
     }
+  }
 }

package/src/api/auth.js

@@ -1,15 +1,24 @@
 import { apiRequest } from './client.js';
 
 export async function verifyApiKey(apiKey) {
-    try {
-        return await apiRequest('/api/v1/auth/verify', {
-            apiKey
-        });
-    } catch (error) {
-        return {
-            error: {
-                message: error.message || 'Failed to verify API key'
-            }
-        };
+  try {
+    return await apiRequest('/api/v1/auth/verify', {
+      apiKey
+    });
+  } catch (error) {
+    if (error.code === 'invalid_api_key') {
+      return {
+        error: {
+          code: 'invalid_api_key',
+          message: error.message
+        }
+      };
     }
-} 
+    return {
+      error: {
+        code: 'verification_failed',
+        message: error.message || 'Failed to verify API key'
+      }
+    };
+  }
+}

package/src/api/client.js

@@ -1,41 +1,83 @@
 const DEFAULT_API_HOST = 'https://api.localhero.ai';
 
 export function getApiHost() {
-    return process.env.LOCALHERO_API_HOST || DEFAULT_API_HOST;
+  return process.env.LOCALHERO_API_HOST || DEFAULT_API_HOST;
+}
+
+function getNetworkErrorMessage(error) {
+  if (error.code === 'ECONNREFUSED') {
+    return `Unable to connect to ${getApiHost()}. Please check your internet connection and try again.`;
+  }
+  if (error.cause?.code === 'ENOTFOUND') {
+    return `Could not resolve host ${getApiHost()}. Please check your internet connection and try again.`;
+  }
+  if (error.cause?.code === 'ETIMEDOUT') {
+    return `Connection to ${getApiHost()} timed out. Please try again later.`;
+  }
+  return `Network error while connecting to ${getApiHost()}. Please check your internet connection and try again.`;
 }
 
 export async function apiRequest(endpoint, options = {}) {
-    const apiHost = getApiHost();
-    const url = `${apiHost}${endpoint}`;
-    const apiKey = process.env.LOCALHERO_API_KEY || options.apiKey;
+  const apiHost = getApiHost();
+  const url = `${apiHost}${endpoint}`;
+  const apiKey = process.env.LOCALHERO_API_KEY || options.apiKey;
 
-    const headers = {
-        'Content-Type': 'application/json',
-        ...options.headers
-    };
+  const headers = {
+    'Content-Type': 'application/json',
+    ...options.headers
+  };
 
-    if (apiKey) {
-        headers['Authorization'] = `Bearer ${apiKey}`;
-    }
+  if (apiKey) {
+    headers['Authorization'] = `Bearer ${apiKey}`;
+  }
 
-    const response = await fetch(url, {
-        ...options,
-        headers,
-    });
+  const fetchOptions = {
+    method: options.method || 'GET',
+    headers,
+  };
 
-    let data;
-    try {
-        data = await response.json();
-    } catch (error) {
-        throw new Error('Failed to parse API response', { cause: error });
-    }
+  if (options.body) {
+    fetchOptions.body = options.body;
+  }
+
+  let response;
+  try {
+    response = await fetch(url, fetchOptions);
+  } catch (error) {
+    const message = getNetworkErrorMessage(error);
+    error.message = message;
+    error.cliErrorMessage = message;
+    throw error;
+  }
+
+  let data;
+  try {
+    data = await response.json();
+  } catch (error) {
+    const message = 'Failed to parse API response';
+    error.message = message;
+    error.cliErrorMessage = message;
+    throw error;
+  }
 
-    if (!response.ok) {
-        const errorMessage = Array.isArray(data?.errors)
-            ? data.errors.map(err => typeof err === 'string' ? err : err.message).join(', ')
-            : 'API request failed';
-        throw new Error(errorMessage);
+  if (!response.ok) {
+    if (response.status === 401 && data?.error?.code === 'invalid_api_key') {
+      const message = 'Your API key is invalid or has been revoked. Please run `npx @localheroai/cli login` to update your API key.';
+      const error = new Error(message);
+      error.cliErrorMessage = message;
+      error.code = 'invalid_api_key';
+      error.data = data;
+      throw error;
     }
+    const message = Array.isArray(data?.errors)
+      ? data.errors.map(err => typeof err === 'string' ? err : err.message).join(', ')
+      : data?.error?.message || 'API request failed';
+    const error = new Error(message);
+    error.cliErrorMessage = message;
+    error.code = data?.error?.code || 'API_ERROR';
+    error.data = data;
+    throw error;
+  }
 
-    return data;
-} 
+  return data;
+}

package/src/api/imports.js

@@ -2,19 +2,21 @@ import { getApiKey } from '../utils/auth.js';
 import { apiRequest } from './client.js';
 
 export async function createImport({ projectId, translations }) {
-    const apiKey = await getApiKey();
-    const response = await apiRequest(`/api/v1/projects/${projectId}/imports`, {
-        method: 'POST',
-        body: JSON.stringify({ translations }),
-        apiKey
-    });
-    return response.import;
+  const apiKey = await getApiKey();
+  const response = await apiRequest(`/api/v1/projects/${projectId}/imports`, {
+    method: 'POST',
+    body: JSON.stringify({
+      translations
+    }),
+    apiKey
+  });
+  return response;
 }
 
 export async function checkImportStatus(projectId, importId) {
-    const apiKey = await getApiKey();
-    const response = await apiRequest(`/api/v1/projects/${projectId}/imports/${importId}`, {
-        apiKey
-    });
-    return response.import;
-} 
+  const apiKey = await getApiKey();
+  const response = await apiRequest(`/api/v1/projects/${projectId}/imports/${importId}`, {
+    apiKey
+  });
+  return response.import;
+}

package/src/api/projects.js

@@ -2,23 +2,23 @@ import { getApiKey } from '../utils/auth.js';
 import { apiRequest } from './client.js';
 
 export async function listProjects() {
-    const apiKey = await getApiKey();
-    const response = await apiRequest('/api/v1/projects', { apiKey });
-    return response.projects;
+  const apiKey = await getApiKey();
+  const response = await apiRequest('/api/v1/projects', { apiKey });
+  return response.projects;
 }
 
 export async function createProject(data) {
-    const apiKey = await getApiKey();
-    const response = await apiRequest('/api/v1/projects', {
-        method: 'POST',
-        body: JSON.stringify({
-            project: {
-                name: data.name,
-                source_language: data.sourceLocale,
-                target_languages: data.targetLocales
-            }
-        }),
-        apiKey
-    });
-    return response.project;
-} 
+  const apiKey = await getApiKey();
+  const response = await apiRequest('/api/v1/projects', {
+    method: 'POST',
+    body: JSON.stringify({
+      project: {
+        name: data.name,
+        source_language: data.sourceLocale,
+        target_languages: data.targetLocales
+      }
+    }),
+    apiKey
+  });
+  return response.project;
+}

package/src/api/translations.js

@@ -1,37 +1,58 @@
 import { getApiKey } from '../utils/auth.js';
 import { apiRequest } from './client.js';
-export async function createTranslationJob({ sourceFiles, targetLocales, projectId }) {
-    const apiKey = await getApiKey();
-    const response = await apiRequest(`/api/v1/projects/${projectId}/translation_jobs`, {
-        method: 'POST',
-        body: JSON.stringify({
-            target_languages: targetLocales,
-            files: sourceFiles.map(file => ({
-                path: file.path,
-                content: file.content,
-                format: file.format
-            }))
-        }),
-        apiKey
-    });
-
-    if (!response.jobs || !response.jobs.length) {
-        throw new Error('No translation jobs were created');
-    }
-
-    return {
-        jobs: response.jobs,
-        totalJobs: response.jobs.length
-    };
+import { getCurrentBranch } from '../utils/git.js';
+
+export async function createTranslationJob({ sourceFiles, targetLocales, projectId, targetPaths }) {
+  const apiKey = await getApiKey();
+  const branch = await getCurrentBranch();
+
+  const response = await apiRequest(`/api/v1/projects/${projectId}/translation_jobs`, {
+    method: 'POST',
+    body: JSON.stringify({
+      target_languages: targetLocales,
+      files: sourceFiles.map(file => ({
+        path: file.path,
+        content: file.content,
+        format: file.format,
+        target_paths: targetPaths
+      })),
+      ...(branch && { branch })
+    }),
+    apiKey
+  });
+
+  if (!response.jobs || !response.jobs.length) {
+    throw new Error('No translation jobs were created');
+  }
+
+  return {
+    jobs: response.jobs,
+    totalJobs: response.jobs.length
+  };
 }
 
 export async function checkJobStatus(jobId, includeTranslations = false) {
-    const apiKey = await getApiKey();
-    const endpoint = `/api/v1/translation_jobs/${jobId}${includeTranslations ? '?include_translations=true' : ''}`;
-    return apiRequest(endpoint, { apiKey });
+  const apiKey = await getApiKey();
+  const endpoint = `/api/v1/translation_jobs/${jobId}${includeTranslations ? '?include_translations=true' : ''}`;
+  return apiRequest(endpoint, { apiKey });
 }
 
 export async function getTranslations(jobId) {
-    const apiKey = await getApiKey();
-    return apiRequest(`/api/v1/translation_jobs/${jobId}/translations`, { apiKey });
-} 
+  const apiKey = await getApiKey();
+  return apiRequest(`/api/v1/translation_jobs/${jobId}/translations`, { apiKey });
+}
+
+export async function getUpdates(projectId, { since, page = 1 }) {
+  const apiKey = await getApiKey();
+
+  if (!since) {
+    throw new Error('Missing required parameter: since (ISO 8601 timestamp)');
+  }
+
+  const queryParams = new URLSearchParams({
+    since,
+    page: page.toString()
+  });
+
+  return apiRequest(`/api/v1/projects/${projectId}/updates?${queryParams}`, { apiKey });
+}

package/src/cli.js

@@ -5,67 +5,74 @@ import chalk from 'chalk';
 import { readFileSync } from 'fs';
 import { login } from './commands/login.js';
 import { init } from './commands/init.js';
-import { defaultDependencies } from './utils/defaults.js';
 import { translate } from './commands/translate.js';
+import { sync } from './commands/sync.js';
 
 const program = new Command();
 
-function displayBanner() {
-    console.log(chalk.blue(`
-  ===============================================
-    
-                   LocalHero.ai CLI 
-                   
-  ===============================================
-    `));
-}
-
 function getVersion() {
-    const packageJson = JSON.parse(
-        readFileSync(new URL('../package.json', import.meta.url))
-    );
-    return packageJson.version;
+  const packageJson = JSON.parse(
+    readFileSync(new URL('../package.json', import.meta.url))
+  );
+  return packageJson.version;
 }
 
 function handleApiError(error) {
-    console.error(chalk.red(`❌ ${error.message}`));
-    process.exit(1);
+  console.error(chalk.red(`❌ ${error.cliErrorMessage || error.message}`));
+
+  if (program.opts().debug) {
+    console.error(chalk.dim(error.stack || error));
+
+    if (error.cause) {
+      console.error(chalk.dim(error.cause.stack || error.cause));
+    }
+  } else {
+    console.error(chalk.dim('\nRun with --debug for more information'));
+  }
+
+  process.exit(1);
 }
 
 function wrapCommandAction(action) {
-    return function (...args) {
-        return Promise.resolve(action(...args)).catch(handleApiError);
-    };
+  return function (...args) {
+    return Promise.resolve(action(...args)).catch(handleApiError);
+  };
 }
 
 program
-    .name('localhero')
-    .description('CLI tool for automatic I18n translations with LocalHero.ai')
-    .version(getVersion())
-    .addHelpText('beforeAll', displayBanner)
-    .action(() => {
-        console.log(`Version: ${getVersion()}`);
-        console.log('\nLocalHero.ai is a powerful i18n translation service');
-        console.log('that helps you manage your application translations.');
-        console.log('\n🔗 Visit https://localhero.ai for more information');
-        console.log('💡 Use --help to see available commands');
-    });
+  .name('localhero')
+  .description('CLI tool for automatic I18n translations with LocalHero.ai, more info at https://localhero.ai.')
+  .version(getVersion())
+  .option('--debug', 'Show debug information when errors occur')
+  .action(() => {
+    console.log('LocalHero.ai is automatic I18n translations service that easily integrates with your dev workflow.');
+    console.log(`\nVersion: ${getVersion()}`);
+    console.log('\n🔗 Visit https://localhero.ai for more information');
+    console.log('👏 Set up your project with `npx @localheroai/cli init`');
+    console.log('💡 Use --help to see available commands');
+  });
+
+program
+  .command('login')
+  .description('Authenticate with LocalHero.ai using an API key')
+  .action(wrapCommandAction(() => login()));
 
 program
-    .command('login')
-    .description('Authenticate with LocalHero.ai using an API key')
-    .action(wrapCommandAction(() => login(defaultDependencies)));
+  .command('init')
+  .description('Initialize a new LocalHero.ai project')
+  .action(wrapCommandAction(() => init()));
 
 program
-    .command('init')
-    .description('Initialize a new LocalHero.ai project')
-    .action(wrapCommandAction(() => init(defaultDependencies)));
+  .command('translate')
+  .description('Translate missing keys in your i18n files')
+  .option('-v, --verbose', 'Show detailed progress information')
+  .option('-c, --commit', 'Automatically commit changes (useful for CI/CD)')
+  .action(wrapCommandAction((options) => translate(options)));
 
 program
-    .command('translate')
-    .description('Translate missing keys in your i18n files')
-    .option('-v, --verbose', 'Show detailed progress information')
-    .option('-c, --commit', 'Automatically commit changes (useful for CI/CD)')
-    .action(wrapCommandAction((options) => translate(options)));
+  .command('sync')
+  .description('Sync updates from LocalHero.ai to your local files')
+  .option('-v, --verbose', 'Show detailed progress information')
+  .action(wrapCommandAction((options) => sync(options)));
 
 program.parse();