@i18n-agent/cli 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 i18n Agent Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# @i18n-agent/cli
+
+Terminal client for the i18n-agent translation service. Translate text and files directly from your terminal.
+
+## Install
+
+```bash
+npm install -g @i18n-agent/cli
+```
+
+Requires Node.js >= 18.
+
+## Setup
+
+```bash
+# Save your API key (get one at https://app.i18nagent.ai)
+i18nagent login
+```
+
+Or set via environment variable (for CI/CD):
+```bash
+export I18N_AGENT_API_KEY=your-key-here
+```
+
+## Usage
+
+### Translate text
+```bash
+i18nagent translate "Hello world" --lang es
+i18nagent translate "Hello world" --lang es,fr,ja
+```
+
+### Translate files
+```bash
+i18nagent translate ./locales/en.json --lang es,fr
+i18nagent translate ./docs/guide.md --lang de --namespace my-project
+```
+
+### Interactive mode
+```bash
+i18nagent translate     # prompts for input
+i18nagent tui           # full interactive menu
+```
+
+### Check job status
+```bash
+i18nagent status <jobId>
+```
+
+### Download translations
+```bash
+i18nagent download <jobId> --output ./locales
+```
+
+### Resume failed jobs
+```bash
+i18nagent resume <jobId>
+```
+
+### Check credits
+```bash
+i18nagent credits
+```
+
+### Upload existing translations
+```bash
+i18nagent upload ./de.json --source en --target de --namespace my-project
+```
+
+### List supported languages
+```bash
+i18nagent languages
+```
+
+### Analyze content
+```bash
+i18nagent analyze ./en.json --lang es
+```
+
+## JSON output
+
+All commands support `--json` for machine-readable output:
+```bash
+i18nagent translate "Hello" --lang es --json
+i18nagent credits --json
+```
+
+## Config
+
+Config is stored at `~/.config/i18nagent/config.json`:
+```json
+{
+  "apiKey": "i18n_...",
+  "defaultLanguages": ["es", "fr"],
+  "defaultNamespace": "my-project"
+}
+```
+
+Environment variable `I18N_AGENT_API_KEY` takes priority over config file.
+
+## Binary distribution
+
+See [docs/BINARY_DISTRIBUTION.md](docs/BINARY_DISTRIBUTION.md) for standalone binary packaging.
+
+## License
+
+MIT

package/bin/i18nagent.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { createProgram } from '../src/index.js';
+
+const program = createProgram();
+program.parse(process.argv);

package/docs/BINARY_DISTRIBUTION.md

@@ -0,0 +1,108 @@
+# Binary Distribution Strategy
+
+Notes on future standalone binary packaging for `@i18n-agent/cli`.
+
+## Current: npm only
+
+```bash
+npm install -g @i18n-agent/cli
+```
+
+Requires Node.js >= 18.
+
+## Future Options
+
+### Option 1: Node.js SEA (Single Executable Applications)
+
+Available since Node.js 20. Bundles the app into a single executable.
+
+**Pros:** Official Node.js feature, no external tools
+**Cons:** Large binary (~50MB), Node 20+ only for building
+
+```bash
+# 1. Generate SEA config
+echo '{"main":"bin/i18nagent.js","output":"sea-prep.blob"}' > sea-config.json
+
+# 2. Generate the blob
+node --experimental-sea-config sea-config.json
+
+# 3. Copy node binary and inject
+cp $(which node) i18nagent
+npx postject i18nagent NODE_SEA_BLOB sea-prep.blob \
+  --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2
+
+# 4. Sign on macOS
+codesign --sign - i18nagent
+```
+
+### Option 2: Bun compile
+
+Bun has built-in single-file compilation.
+
+**Pros:** Fast, small binaries (~10-20MB), cross-compile support
+**Cons:** Requires Bun, may have Node.js compatibility edge cases
+
+```bash
+bun build --compile bin/i18nagent.js --outfile i18nagent
+# Cross-compile:
+bun build --compile --target=bun-linux-x64 bin/i18nagent.js --outfile i18nagent-linux
+bun build --compile --target=bun-darwin-arm64 bin/i18nagent.js --outfile i18nagent-macos
+```
+
+### Option 3: pkg (legacy)
+
+Vercel's pkg tool. Deprecated but still works.
+
+```bash
+npx pkg bin/i18nagent.js --targets node18-macos-arm64,node18-linux-x64,node18-win-x64
+```
+
+### Option 4: esbuild + SEA
+
+Bundle with esbuild first (tree-shaking, single file), then use SEA.
+
+```bash
+npx esbuild bin/i18nagent.js --bundle --platform=node --outfile=dist/i18nagent.cjs --format=cjs
+# Then use SEA on the bundled file
+```
+
+## Recommended Approach
+
+**Bun compile** for simplest DX and smallest binaries. Fall back to **Node.js SEA** if Bun compatibility issues arise.
+
+## Distribution Channels
+
+1. **GitHub Releases** - attach binaries for macOS (arm64, x64), Linux (x64, arm64), Windows (x64)
+2. **Homebrew tap** - `brew install i18n-agent/tap/i18nagent`
+3. **curl installer** - `curl -fsSL https://i18nagent.ai/install.sh | sh`
+
+## CI/CD
+
+Use GitHub Actions to build binaries on each release tag:
+
+```yaml
+# .github/workflows/release-binaries.yml
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        include:
+          - os: macos-latest
+            target: bun-darwin-arm64
+            artifact: i18nagent-macos-arm64
+          - os: ubuntu-latest
+            target: bun-linux-x64
+            artifact: i18nagent-linux-x64
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: cd cli && bun build --compile --target=${{ matrix.target }} bin/i18nagent.js --outfile ${{ matrix.artifact }}
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: cli/${{ matrix.artifact }}
+```

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@i18n-agent/cli",
+  "version": "1.0.1",
+  "description": "Terminal client for i18n-agent translation service",
+  "type": "module",
+  "bin": {
+    "i18nagent": "./bin/i18nagent.js"
+  },
+  "main": "./src/index.js",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^12.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "docs/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "i18n",
+    "translation",
+    "cli",
+    "internationalization",
+    "localization"
+  ],
+  "author": "FatCouple OU",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/i18n-agent/cli.git"
+  },
+  "homepage": "https://i18nagent.ai",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test tests/unit/*.test.js",
+    "test:integration": "node --test tests/integration/*.test.js"
+  }
+}

package/src/api-client.js

@@ -0,0 +1,127 @@
+export const MCP_SERVER_URL = 'https://mcp.i18nagent.ai';
+
+const HEAVY_LOAD_PATTERNS = [
+  /Our system is under heavy load/i,
+  /system is under heavy load.*resume.*later/i,
+];
+
+export function isHeavyLoadError(message) {
+  if (!message) return false;
+  return HEAVY_LOAD_PATTERNS.some(p => p.test(message));
+}
+
+export function buildJsonRpcRequest(toolName, args) {
+  return {
+    jsonrpc: '2.0',
+    id: Date.now(),
+    method: 'tools/call',
+    params: {
+      name: toolName,
+      arguments: args,
+    },
+  };
+}
+
+export function parseJsonRpcResponse(response) {
+  if (response.error) {
+    const msg = response.error.message || JSON.stringify(response.error);
+    throw new Error(msg);
+  }
+
+  const result = response.result;
+  if (result && result.content && result.content[0]) {
+    const text = result.content[0].text;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  return result;
+}
+
+export async function callTool(toolName, args, apiKey, opts = {}) {
+  const timeout = opts.timeout || 300000;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const response = await fetch(MCP_SERVER_URL, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify(buildJsonRpcRequest(toolName, args)),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => 'Unknown error');
+      handleHttpError(response.status, errorText, toolName);
+    }
+
+    const data = await response.json();
+    return parseJsonRpcResponse(data);
+  } catch (error) {
+    if (error.name === 'AbortError') {
+      throw new Error(`Request timed out after ${timeout / 1000}s. For large translations, the job may still be processing. Check status with: i18nagent status <jobId>`);
+    }
+    if (isHeavyLoadError(error.message)) {
+      throw new Error('System under heavy load. Your job has been saved -- resume later with: i18nagent resume <jobId>');
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function handleHttpError(status, body, toolName) {
+  if (status === 401) {
+    throw new Error('Invalid or missing API key. Run: i18nagent login');
+  }
+  if (status === 402) {
+    throw new Error('Insufficient credits. Top up at: https://app.i18nagent.ai');
+  }
+  if (status === 404) {
+    throw new Error(`Resource not found (${toolName})`);
+  }
+  if (status === 503) {
+    throw new Error('Service temporarily unavailable. Try again later.');
+  }
+  throw new Error(`HTTP ${status}: ${body}`);
+}
+
+export async function uploadFile(endpoint, fields, fileField, apiKey, opts = {}) {
+  const timeout = opts.timeout || 60000;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const formData = new FormData();
+    for (const [key, value] of Object.entries(fields)) {
+      formData.append(key, value);
+    }
+    if (fileField) {
+      formData.append(fileField.name, new Blob([fileField.content]), fileField.fileName);
+    }
+
+    const response = await fetch(`${MCP_SERVER_URL}${endpoint}`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${apiKey}`,
+      },
+      body: formData,
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => 'Unknown error');
+      handleHttpError(response.status, errorText, endpoint);
+    }
+
+    return await response.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/commands/analyze.js

@@ -0,0 +1,58 @@
+import fs from 'fs';
+import { requireApiKey } from '../config.js';
+import { callTool } from '../api-client.js';
+import { formatOutput, print } from '../output.js';
+
+export async function analyzeAction(input, opts) {
+  if (!input) {
+    console.error('Error: provide text or file path to analyze');
+    console.error('Usage: i18nagent analyze <text-or-file> --lang <target>');
+    process.exit(1);
+  }
+
+  if (!opts.lang) {
+    console.error('Error: --lang is required (target language)');
+    process.exit(1);
+  }
+
+  const apiKey = requireApiKey();
+
+  let content = input;
+  if (fs.existsSync(input)) {
+    content = fs.readFileSync(input, 'utf8');
+  }
+
+  try {
+    const result = await callTool('analyze_content', {
+      content,
+      targetLanguage: opts.lang,
+      sourceLanguage: opts.source,
+      industry: opts.industry || 'general',
+      targetAudience: opts.audience || 'general',
+    }, apiKey);
+
+    print(formatOutput(result, {
+      json: opts.json,
+      template: (data) => {
+        const lines = ['Content Analysis\n'];
+        if (data.sourceLanguage) lines.push(`  Source language: ${data.sourceLanguage} (${data.confidence || ''})`);
+        if (data.contentType) lines.push(`  Content type:   ${data.contentType}`);
+        if (data.readinessScore !== undefined) lines.push(`  Readiness:      ${data.readinessScore}/100`);
+        if (data.wordCount) lines.push(`  Word count:     ${data.wordCount}`);
+        if (data.estimatedCredits) lines.push(`  Est. credits:   ${data.estimatedCredits}`);
+        if (data.suggestions?.length) {
+          lines.push('\n  Suggestions:');
+          data.suggestions.forEach(s => lines.push(`    - ${s}`));
+        }
+        if (data.warnings?.length) {
+          lines.push('\n  Warnings:');
+          data.warnings.forEach(w => lines.push(`    ! ${w}`));
+        }
+        return lines.join('\n');
+      }
+    }));
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+}

package/src/commands/credits.js

@@ -0,0 +1,27 @@
+import { requireApiKey } from '../config.js';
+import { callTool } from '../api-client.js';
+import { formatOutput, print } from '../output.js';
+
+export async function creditsAction(opts) {
+  const apiKey = requireApiKey();
+
+  try {
+    const result = await callTool('get_credits', {}, apiKey);
+
+    print(formatOutput(result, {
+      json: opts.json,
+      template: (data) => {
+        const credits = data.credits ?? data.remainingCredits ?? data;
+        if (typeof credits === 'object') {
+          const remaining = credits.remaining ?? credits.balance ?? 'unknown';
+          const wordsRemaining = credits.wordsRemaining ?? (typeof remaining === 'number' ? Math.floor(remaining / 0.01) : 'unknown');
+          return `Credits remaining: ${remaining}\nEstimated words:  ${typeof wordsRemaining === 'number' ? wordsRemaining.toLocaleString() : wordsRemaining}\n\nTop up at: https://app.i18nagent.ai`;
+        }
+        return `Credits: ${JSON.stringify(credits)}`;
+      }
+    }));
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+}

package/src/commands/download.js

@@ -0,0 +1,53 @@
+import fs from 'fs';
+import path from 'path';
+import { requireApiKey } from '../config.js';
+import { callTool } from '../api-client.js';
+import { print, printErr } from '../output.js';
+
+export async function downloadAction(jobId, opts) {
+  if (!jobId) {
+    console.error('Error: jobId is required');
+    console.error('Usage: i18nagent download <jobId>');
+    process.exit(1);
+  }
+
+  const apiKey = requireApiKey();
+  const outputDir = opts.output || `./i18n-translations-${jobId}`;
+
+  try {
+    printErr(`Downloading translations for job ${jobId}...`);
+
+    const result = await callTool('download_translations', { jobId }, apiKey, { timeout: 60000 });
+
+    fs.mkdirSync(outputDir, { recursive: true });
+    const filesWritten = [];
+
+    if (result.downloadUrls) {
+      for (const [lang, url] of Object.entries(result.downloadUrls)) {
+        printErr(`  Downloading ${lang}...`);
+        const response = await fetch(url);
+        const content = await response.text();
+        const ext = result.fileName?.split('.').pop() || 'json';
+        const filePath = path.join(outputDir, `${lang}.${ext}`);
+        fs.writeFileSync(filePath, content);
+        filesWritten.push(filePath);
+      }
+    } else if (result.translations) {
+      for (const [lang, content] of Object.entries(result.translations)) {
+        const ext = result.fileName?.split('.').pop() || 'json';
+        const filePath = path.join(outputDir, `${lang}.${ext}`);
+        fs.writeFileSync(filePath, content);
+        filesWritten.push(filePath);
+      }
+    }
+
+    if (opts.json) {
+      print(JSON.stringify({ jobId, outputDir, filesWritten }, null, 2));
+    } else {
+      print(`Downloaded ${filesWritten.length} files to ${outputDir}:\n${filesWritten.map(f => `  ${f}`).join('\n')}`);
+    }
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+}

package/src/commands/languages.js

@@ -0,0 +1,33 @@
+import { requireApiKey } from '../config.js';
+import { callTool } from '../api-client.js';
+import { formatOutput, print } from '../output.js';
+
+export async function languagesAction(opts) {
+  const apiKey = requireApiKey();
+
+  try {
+    const result = await callTool('list_supported_languages', {
+      includeQuality: opts.quality,
+    }, apiKey);
+
+    print(formatOutput(result, {
+      json: opts.json,
+      template: (data) => {
+        const languages = data.languages || data;
+        if (!Array.isArray(languages)) {
+          return JSON.stringify(data, null, 2);
+        }
+        const lines = ['Supported Languages:', ''];
+        for (const lang of languages) {
+          const quality = lang.quality ? ` (${lang.quality})` : '';
+          lines.push(`  ${(lang.code || '').padEnd(12)} ${lang.name || ''}${quality}`);
+        }
+        lines.push('', `Total: ${languages.length} languages`);
+        return lines.join('\n');
+      }
+    }));
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+}

package/src/commands/login.js

@@ -0,0 +1,26 @@
+import { getConfigPath, saveConfig, getApiKey } from '../config.js';
+import { promptApiKey } from '../prompts.js';
+import { print } from '../output.js';
+
+export async function loginAction(opts) {
+  const configPath = getConfigPath();
+
+  const existingKey = getApiKey(configPath);
+  if (existingKey && !opts.force) {
+    print('Already logged in. Use --force to overwrite.');
+    return;
+  }
+
+  let apiKey = opts.key;
+  if (!apiKey) {
+    apiKey = await promptApiKey();
+  }
+
+  if (!apiKey) {
+    print('No API key provided. Aborting.');
+    return;
+  }
+
+  saveConfig(configPath, { apiKey });
+  print(`API key saved to ${configPath}`);
+}

package/src/commands/logout.js

@@ -0,0 +1,19 @@
+import { getConfigPath, loadConfig } from '../config.js';
+import { print } from '../output.js';
+import fs from 'fs';
+import path from 'path';
+
+export async function logoutAction() {
+  const configPath = getConfigPath();
+  const config = loadConfig(configPath);
+
+  if (!config.apiKey) {
+    print('Not logged in.');
+    return;
+  }
+
+  delete config.apiKey;
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+  print('API key removed. Logged out.');
+}

package/src/commands/resume.js

@@ -0,0 +1,30 @@
+import { requireApiKey } from '../config.js';
+import { callTool } from '../api-client.js';
+import { formatOutput, print } from '../output.js';
+
+export async function resumeAction(jobId, opts) {
+  if (!jobId) {
+    console.error('Error: jobId is required');
+    console.error('Usage: i18nagent resume <jobId>');
+    process.exit(1);
+  }
+
+  const apiKey = requireApiKey();
+
+  try {
+    const result = await callTool('resume_translation', { jobId }, apiKey, { timeout: 30000 });
+
+    print(formatOutput(result, {
+      json: opts.json,
+      template: (data) => {
+        if (data.status === 'processing' || data.status === 'resumed') {
+          return `Job ${jobId} resumed. Check progress with: i18nagent status ${jobId}`;
+        }
+        return `Resume result: ${JSON.stringify(data, null, 2)}`;
+      }
+    }));
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+}