localingos 0.1.32 → 0.1.33

package/README.md

@@ -202,4 +202,72 @@ git push && git push --tags
 |---------|------------|---------|
 | `npm version patch` | Bug fix, typo, minor tweak | 0.1.0 → 0.1.1 |
 | `npm version minor` | New feature, new format support | 0.1.0 → 0.2.0 |
-| `npm version major` | Breaking config/API change | 0.1.0 → 1.0.0 |
+| `npm version major` | Breaking config/API change | 0.1.0 → 1.0.0 |
+
+## CI/CD Integration
+
+### GitHub Actions — Auto-sync on push
+
+Automatically sync translations when `.messages.ts` files change on `main`:
+
+1. Add your API key as a repository secret: `LOCALINGOS_API_KEY`
+   (Settings → Secrets and variables → Actions → New repository secret)
+
+2. Make sure `localingos.config.json` is committed (project config, no secrets).
+   `.localingos.json` stays in `.gitignore` (contains API key for local dev only).
+
+3. Copy [`examples/github-actions-sync.yml`](examples/github-actions-sync.yml) to `.github/workflows/localingos-sync.yml`
+
+This workflow:
+- Triggers when `.messages.ts` or `src/i18n/` files change on `main`
+- Runs `localingos sync --prune` to push source strings and pull translations
+- Commits updated translation files back to the repo
+
+### GitHub Actions — PR check
+
+Fail PRs if i18n source files are out of date or orphan messages exist:
+
+Copy [`examples/github-actions-check.yml`](examples/github-actions-check.yml) to `.github/workflows/localingos-check.yml`
+
+This runs `npm run i18n:check` which verifies:
+- `en-US.json` and `en-US.descriptions.json` match the `.messages.ts` files
+- No orphan messages (defined but never referenced in code)
+
+### Environment variable
+
+The CLI supports `LOCALINGOS_API_KEY` as an environment variable, which takes precedence over the `apiKey` field in `.localingos.json`. This lets you keep the API key out of your repo:
+
+When you run `localingos init`, it creates two files:
+
+- **`localingos.config.json`** — commit this. Contains project settings (familyId, locale, paths). No secrets.
+- **`.localingos.json`** — gitignored. Contains only your `apiKey` for local development.
+
+```bash
+# Local dev — the CLI reads apiKey from .localingos.json automatically
+localingos sync
+
+# CI — set as a GitHub secret, the CLI reads it from the env var
+LOCALINGOS_API_KEY=your-key localingos sync
+```
+
+### Multiple projects (monorepo)
+
+If you have multiple projects in one repo, each with its own `localingos.config.json` and API key, add an `apiKeyEnv` field to each config pointing to a different env var:
+
+```json
+// apps/web/localingos.config.json
+{ "apiKeyEnv": "LOCALINGOS_KEY_WEB", "familyId": "...", ... }
+
+// apps/docs/localingos.config.json
+{ "apiKeyEnv": "LOCALINGOS_KEY_DOCS", "familyId": "...", ... }
+```
+
+Then in your workflow, pass each secret:
+
+```yaml
+env:
+  LOCALINGOS_KEY_WEB: ${{ secrets.LOCALINGOS_KEY_WEB }}
+  LOCALINGOS_KEY_DOCS: ${{ secrets.LOCALINGOS_KEY_DOCS }}
+```
+
+The CLI checks `apiKeyEnv` first, then falls back to `LOCALINGOS_API_KEY`, then `apiKey` in the config file.

package/bin/localingos.js

@@ -6,6 +6,7 @@ import { syncCommand } from '../src/commands/sync.js';
 import { pullCommand } from '../src/commands/pull.js';
 import { pushCommand } from '../src/commands/push.js';
 import { extractCommand } from '../src/commands/extract.js';
+import { mcpServeCommand } from '../src/commands/mcp-serve.js';
 import pkg from '../package.json' with { type: 'json' };
 
 program
@@ -48,4 +49,9 @@ program
     .option('-c, --config <path>', 'Path to config file', '.localingos.json')
     .action(extractCommand);
 
+program
+    .command('mcp-serve')
+    .description('Start an MCP server over stdio for AI coding agents (Cursor, Claude Desktop, Kiro)')
+    .action(mcpServeCommand);
+
 program.parse();

package/examples/github-actions-check.yml

@@ -0,0 +1,35 @@
+# .github/workflows/localingos-check.yml
+#
+# Checks that i18n source files are up to date on pull requests.
+# Fails if .messages.ts files have changed but extract hasn't been run,
+# or if orphan messages exist.
+#
+# Setup:
+#   1. Copy this file to .github/workflows/localingos-check.yml
+#   2. Make sure "i18n:check" script exists in package.json
+
+name: i18n Check
+
+on:
+  pull_request:
+    paths:
+      - 'src/**/*.messages.ts'
+      - 'src/**/*.tsx'
+      - 'src/**/*.ts'
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Check i18n is up to date
+        run: npm run i18n:check

package/examples/github-actions-sync.yml

@@ -0,0 +1,58 @@
+# .github/workflows/localingos-sync.yml
+#
+# Syncs translations with Localingos on every push to main.
+# Translations are committed back to the repo automatically.
+#
+# Setup:
+#   1. Add your API key as a repository secret: LOCALINGOS_API_KEY
+#      (Settings → Secrets and variables → Actions → New repository secret)
+#   2. Make sure localingos.config.json is committed (project config, no secrets)
+#      .localingos.json stays in .gitignore (contains API key for local dev only)
+#   3. Copy this file to .github/workflows/localingos-sync.yml
+#
+# Multiple projects (monorepo):
+#   Each localingos.config.json can set "apiKeyEnv" to a different env var name:
+#     { "apiKeyEnv": "LOCALINGOS_KEY_DOCS", "familyId": "..." }
+#     { "apiKeyEnv": "LOCALINGOS_KEY_APP",  "familyId": "..." }
+#   Then add each as a separate secret and pass them all in the env block.
+
+name: Localingos Sync
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'src/**/*.messages.ts'
+      - 'src/i18n/**'
+      - 'localingos.config.json'
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install Localingos CLI
+        run: npm install -g localingos
+
+      - name: Sync translations
+        env:
+          LOCALINGOS_API_KEY: ${{ secrets.LOCALINGOS_API_KEY }}
+          # For monorepos with multiple projects, add per-project secrets:
+          # LOCALINGOS_KEY_APP: ${{ secrets.LOCALINGOS_KEY_APP }}
+          # LOCALINGOS_KEY_DOCS: ${{ secrets.LOCALINGOS_KEY_DOCS }}
+        run: localingos sync --prune
+
+      - name: Commit updated translations
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add src/i18n/
+          git diff --staged --quiet || git commit -m "chore: sync translations [skip ci]" && git push

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "localingos",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "description": "CLI tool to sync translations with Localingos",
   "main": "src/index.js",
   "type": "module",
@@ -14,14 +14,17 @@
     "i18n",
     "translation",
     "localization",
-    "cli"
+    "cli",
+    "mcp"
   ],
   "license": "MIT",
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.28.0",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "inquirer": "^9.2.0",
     "localingos": "^0.1.11",
-    "yaml": "^2.4.0"
+    "yaml": "^2.4.0",
+    "zod": "^3.25.0"
   }
 }

package/pom.xml

@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+                             https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>com.localingos</groupId>
+        <artifactId>localingos-parent</artifactId>
+        <version>1.0.0</version>
+    </parent>
+
+    <artifactId>localingos-cli</artifactId>
+    <packaging>pom</packaging>
+    <name>Localingos CLI</name>
+    <description>CLI tool to sync translations with Localingos</description>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>com.github.eirslett</groupId>
+                <artifactId>frontend-maven-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>install node and npm</id>
+                        <goals><goal>install-node-and-npm</goal></goals>
+                        <configuration>
+                            <nodeVersion>v22.12.0</nodeVersion>
+                            <npmVersion>10.9.0</npmVersion>
+                        </configuration>
+                    </execution>
+                    <execution>
+                        <id>npm install</id>
+                        <goals><goal>npm</goal></goals>
+                        <configuration>
+                            <arguments>ci</arguments>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <artifactId>maven-clean-plugin</artifactId>
+                <configuration>
+                    <filesets>
+                        <fileset><directory>node_modules</directory></fileset>
+                        <fileset><directory>node</directory></fileset>
+                    </filesets>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+</project>

package/src/commands/extract.js

@@ -351,7 +351,7 @@ Create \`scripts/extract-messages.js\` — a deterministic Node.js script that:
 3. Parses each file to extract \`id\`, \`text\`, and \`description\` from every \`MessageDefinition\`
 4. Builds nested JSON from all dot-path ids, using \`text\` as the ${languageName} value, and writes it to the configured \`sourceFile\` path
 5. Builds a **separate descriptions file** at the same path but with a \`.descriptions.json\` suffix (e.g. \`${descriptionsFile}\`) using the same nested structure, but with \`description\` as the value. Only include keys that have a non-empty \`description\`. If no descriptions exist at all, still write an empty \`{}\` file.
-6. Merges into the existing source file — **never overwrites existing values**, only adds new keys
+6. The \`*${msgExt}\` files are the **source of truth** — always overwrite the source JSON values with the text from message definitions. If a text is changed in a \`*${msgExt}\` file, the JSON must be updated to match.
 7. Reports: new keys added, existing keys preserved, duplicate ids (which should error and abort)
 
 **IMPORTANT**: Do NOT hardcode the output file name (e.g. \`en-US.json\`). The script must derive it from the \`sourceFile\` field in \`.localingos.json\` so it works for any configured locale.

package/src/commands/init.js

@@ -104,7 +104,8 @@ export async function initCommand() {
     };
 
     const savedPath = saveConfig(config);
-    console.log(chalk.green(`\n✅ Config saved to ${savedPath}`));
+    console.log(chalk.green(`\n✅ Project config saved to localingos.config.json (commit this)`));
+    console.log(chalk.green(`✅ API key saved to .localingos.json (keep this gitignored)`));
 
     // Check if .gitignore exists and suggest adding .localingos.json
     const gitignorePath = path.resolve('.gitignore');
@@ -118,7 +119,7 @@ export async function initCommand() {
                 default: true
             }]);
             if (addGitignore) {
-                fs.appendFileSync(gitignorePath, '\n# Localingos CLI config (contains API key)\n.localingos.json\n');
+                fs.appendFileSync(gitignorePath, '\n# Localingos local config (contains API key — do not commit)\n.localingos.json\n');
                 console.log(chalk.green('✅ Added .localingos.json to .gitignore'));
             }
         }

package/src/commands/mcp-serve.js

@@ -0,0 +1,222 @@
+/**
+ * localingos mcp-serve
+ *
+ * Starts an MCP server over stdio for AI coding agents.
+ * Reads the same config as the CLI (localingos.config.json + .localingos.json).
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+
+function loadConfig(cwd) {
+  let config = {};
+  try { config = JSON.parse(fs.readFileSync(path.join(cwd, 'localingos.config.json'), 'utf-8')); } catch {}
+  try { config = { ...config, ...JSON.parse(fs.readFileSync(path.join(cwd, '.localingos.json'), 'utf-8')) }; } catch {}
+  const envVarName = config.apiKeyEnv || 'LOCALINGOS_API_KEY';
+  if (process.env[envVarName]) config.apiKey = process.env[envVarName];
+  return config;
+}
+
+async function api(method, urlPath, apiUrl, apiKey, body) {
+  const url = `${apiUrl.replace(/\/+$/, '')}${urlPath}`;
+  const opts = { method, headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json', 'Accept': 'application/json' } };
+  if (body) opts.body = JSON.stringify(body);
+  const res = await fetch(url, opts);
+  if (!res.ok) throw new Error(`API ${method} ${urlPath} failed (${res.status}): ${await res.text().catch(() => '')}`);
+  const text = await res.text();
+  return text ? JSON.parse(text) : {};
+}
+
+function flatten(obj, prefix = '') {
+  const entries = [];
+  for (const [k, v] of Object.entries(obj)) {
+    const full = prefix ? `${prefix}.${k}` : k;
+    if (typeof v === 'object' && v !== null && !Array.isArray(v)) entries.push(...flatten(v, full));
+    else entries.push({ id: full, text: String(v) });
+  }
+  return entries;
+}
+
+function readSourceEntries(config, cwd) {
+  const sf = path.resolve(cwd, config.sourceFile);
+  if (!fs.existsSync(sf)) return [];
+  const entries = flatten(JSON.parse(fs.readFileSync(sf, 'utf-8')));
+  let descs = {};
+  try { for (const d of flatten(JSON.parse(fs.readFileSync(sf.replace(/\.json$/, '.descriptions.json'), 'utf-8')))) descs[d.id] = d.text; } catch {}
+  return entries.map(e => ({ id: e.id, locale: config.sourceLocale, text: e.text, description: descs[e.id] || null, forceReTranslate: false }));
+}
+
+function writeTranslations(translations, config, cwd) {
+  const byLocale = {};
+  for (const t of translations.filter(t => t.locale !== config.sourceLocale)) (byLocale[t.locale] ||= []).push(t);
+  const outputDir = path.resolve(cwd, config.outputDir);
+  const written = [];
+  for (const [locale, items] of Object.entries(byLocale)) {
+    const nested = {};
+    for (const { foreignId, text } of items) {
+      const keys = foreignId.split('.');
+      let cur = nested;
+      for (let i = 0; i < keys.length - 1; i++) { cur[keys[i]] = cur[keys[i]] || {}; cur = cur[keys[i]]; }
+      cur[keys[keys.length - 1]] = text;
+    }
+    const fileName = (config.outputPattern || '{locale}.json').replace('{locale}', locale);
+    fs.mkdirSync(outputDir, { recursive: true });
+    fs.writeFileSync(path.join(outputDir, fileName), JSON.stringify(nested, null, 2) + '\n');
+    written.push(fileName);
+  }
+  return written;
+}
+
+export async function mcpServeCommand() {
+  const cwd = process.cwd();
+  const config = loadConfig(cwd);
+  const apiUrl = process.env.LOCALINGOS_API_URL || 'https://api.localingos.com';
+
+  const server = new McpServer({ name: 'localingos', version: '0.1.0' });
+
+  server.tool('localingos_sync',
+    'Push source strings to Localingos and pull back translations. Runs extract first if available.',
+    { prune: z.boolean().optional().describe('Remove stale keys from JSON files') },
+    async ({ prune }) => {
+      let extractOut = '';
+      const script = path.join(cwd, 'scripts/extract-messages.js');
+      if (fs.existsSync(script)) {
+        try { extractOut = execSync(`node scripts/extract-messages.js${prune ? ' --prune' : ''}`, { cwd, encoding: 'utf-8', timeout: 30000 }); } catch (e) { extractOut = `Extract warning: ${e.message}`; }
+      }
+      const entries = readSourceEntries(config, cwd);
+      if (!entries.length) return { content: [{ type: 'text', text: 'No source strings found.' }] };
+      const result = await api('POST', '/sync', apiUrl, config.apiKey, { familyId: config.familyId, translatables: entries });
+      const written = writeTranslations(result.translations || [], config, cwd);
+      const pending = result.pending || [];
+      const lines = [`Pushed ${entries.length} source strings`, `${(result.translations || []).length} translations available`,
+        pending.length ? `${pending.length} keys pending` : null, written.length ? `Written: ${written.join(', ')}` : null,
+        extractOut ? `\n${extractOut}` : null].filter(Boolean);
+      return { content: [{ type: 'text', text: lines.join('\n') }] };
+    }
+  );
+
+  server.tool('localingos_push', 'Push source strings only.', {}, async () => {
+    const entries = readSourceEntries(config, cwd);
+    if (!entries.length) return { content: [{ type: 'text', text: 'No source strings found.' }] };
+    await api('POST', '/translatable', apiUrl, config.apiKey, { familyId: config.familyId, translatableList: entries });
+    return { content: [{ type: 'text', text: `Pushed ${entries.length} source strings.` }] };
+  });
+
+  server.tool('localingos_pull', 'Pull latest translations and write locale files.', {}, async () => {
+    const translations = await api('GET', `/translation/${config.familyId}`, apiUrl, config.apiKey);
+    if (!translations?.length) return { content: [{ type: 'text', text: 'No translations available yet.' }] };
+    const written = writeTranslations(translations, config, cwd);
+    return { content: [{ type: 'text', text: `Pulled:\n${written.join('\n')}` }] };
+  });
+
+  server.tool('localingos_status', 'Show project status: family, locales, key counts.', {}, async () => {
+    const entries = readSourceEntries(config, cwd);
+    const outputDir = path.resolve(cwd, config.outputDir);
+    let locales = [];
+    if (fs.existsSync(outputDir)) {
+      const re = new RegExp('^' + (config.outputPattern || '{locale}.json').replace('{locale}', '(.+)').replace('.', '\\.') + '$');
+      locales = fs.readdirSync(outputDir).map(f => f.match(re)?.[1]).filter(Boolean);
+    }
+    return { content: [{ type: 'text', text: `Family: ${config.familyId}\nSource: ${config.sourceLocale}\nKeys: ${entries.length}\nTranslations: ${locales.join(', ') || 'none'}` }] };
+  });
+
+  server.tool('localingos_search', 'Search translation keys or text.',
+    { query: z.string().describe('Search term — matches against key IDs and text values') },
+    async ({ query }) => {
+      const q = query.toLowerCase();
+      const matches = readSourceEntries(config, cwd).filter(e => e.id.toLowerCase().includes(q) || e.text.toLowerCase().includes(q));
+      if (!matches.length) return { content: [{ type: 'text', text: `No matches for "${query}"` }] };
+      const lines = matches.slice(0, 20).map(e => `${e.id}: "${e.text}"`);
+      if (matches.length > 20) lines.push(`... and ${matches.length - 20} more`);
+      return { content: [{ type: 'text', text: lines.join('\n') }] };
+    }
+  );
+
+  server.tool('localingos_extract', 'Run i18n extraction script.',
+    { prune: z.boolean().optional().describe('Remove stale/orphan keys'), check: z.boolean().optional().describe('Check mode — fail if files would change') },
+    async ({ prune, check }) => {
+      const script = path.join(cwd, 'scripts/extract-messages.js');
+      if (!fs.existsSync(script)) return { content: [{ type: 'text', text: 'scripts/extract-messages.js not found.' }] };
+      const flags = [prune && '--prune', check && '--check'].filter(Boolean).join(' ');
+      try {
+        return { content: [{ type: 'text', text: execSync(`node scripts/extract-messages.js ${flags}`, { cwd, encoding: 'utf-8', timeout: 30000 }) }] };
+      } catch (e) { return { content: [{ type: 'text', text: e.stdout || e.message }] }; }
+    }
+  );
+
+  // ── Family management tools ───────────────────────────────────────────
+
+  server.tool('localingos_family_members', 'List members of a family.',
+    { familyId: z.string().describe('Family ID') },
+    async ({ familyId }) => {
+      const members = await api('GET', `/family/${familyId}/members`, apiUrl, config.apiKey);
+      if (!members?.length) return { content: [{ type: 'text', text: 'No members found.' }] };
+      const lines = members.map(m => `${m.userId} — ${m.authorization}`);
+      return { content: [{ type: 'text', text: `${members.length} member(s):\n${lines.join('\n')}` }] };
+    }
+  );
+
+  server.tool('localingos_add_member', 'Add a member to a family (admin only).',
+    { familyId: z.string(), userId: z.string().describe('User ID to add'), role: z.enum(['ADMIN', 'WRITE', 'READ']).default('WRITE').describe('Role for the new member') },
+    async ({ familyId, userId, role }) => {
+      try {
+        await api('POST', `/family/${familyId}/members`, apiUrl, config.apiKey, { userId, authorization: role });
+        return { content: [{ type: 'text', text: `Added ${userId} as ${role} to family ${familyId}` }] };
+      } catch (e) { return { content: [{ type: 'text', text: `Failed: ${e.message}` }] }; }
+    }
+  );
+
+  server.tool('localingos_remove_member', 'Remove a member from a family (admin only).',
+    { familyId: z.string(), userId: z.string().describe('User ID to remove') },
+    async ({ familyId, userId }) => {
+      try {
+        await api('DELETE', `/family/${familyId}/members/${userId}`, apiUrl, config.apiKey);
+        return { content: [{ type: 'text', text: `Removed ${userId} from family ${familyId}` }] };
+      } catch (e) { return { content: [{ type: 'text', text: `Failed: ${e.message}` }] }; }
+    }
+  );
+
+  server.tool('localingos_billing_status', 'Show billing status for a family — plan, usage, owner.',
+    { familyId: z.string().describe('Family ID') },
+    async ({ familyId }) => {
+      try {
+        const b = await api('GET', `/family/${familyId}/billing-status`, apiUrl, config.apiKey);
+        if (!b.attached) return { content: [{ type: 'text', text: 'No billing attached to this family.' }] };
+        const lines = [
+          `Status: ${b.accessMode}${b.planName ? ' · ' + b.planName : ''}`,
+          `Owner: ${b.ownerEmail || b.ownerUserId}`,
+          b.yearlyIncludedWords > 0 ? `Usage: ${b.yearlyUsedWords.toLocaleString()} / ${b.yearlyIncludedWords.toLocaleString()} words (${b.yearlyRemainingWords.toLocaleString()} remaining)` : null,
+          b.trialInfo || null,
+        ].filter(Boolean);
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+      } catch (e) { return { content: [{ type: 'text', text: `Failed: ${e.message}` }] }; }
+    }
+  );
+
+  server.tool('localingos_attach_billing', 'Attach your billing account to a family (admin only).',
+    { familyId: z.string() },
+    async ({ familyId }) => {
+      try {
+        await api('POST', `/family/${familyId}/billing/attach`, apiUrl, config.apiKey);
+        return { content: [{ type: 'text', text: `Billing attached to family ${familyId}` }] };
+      } catch (e) { return { content: [{ type: 'text', text: `Failed: ${e.message}` }] }; }
+    }
+  );
+
+  server.tool('localingos_detach_billing', 'Detach billing from a family (admin only). Family becomes read-only.',
+    { familyId: z.string() },
+    async ({ familyId }) => {
+      try {
+        await api('POST', `/family/${familyId}/billing/detach`, apiUrl, config.apiKey);
+        return { content: [{ type: 'text', text: `Billing detached from family ${familyId}` }] };
+      } catch (e) { return { content: [{ type: 'text', text: `Failed: ${e.message}` }] }; }
+    }
+  );
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/config.js

@@ -2,7 +2,23 @@ import fs from 'fs';
 import path from 'path';
 import chalk from 'chalk';
 
-const DEFAULT_CONFIG_FILE = '.localingos.json';
+/**
+ * Config resolution order:
+ *
+ * 1. localingos.config.json  — committed to repo, shared with team/CI
+ *    Contains: familyId, sourceLocale, format, sourceFile, outputDir, outputPattern, apiKeyEnv
+ *
+ * 2. .localingos.json         — in .gitignore, local dev only
+ *    Contains: apiKey (and can override any field from the committed config)
+ *
+ * 3. Environment variable     — for CI/CD
+ *    LOCALINGOS_API_KEY (default) or custom name via apiKeyEnv field
+ *
+ * API key resolution: env var (apiKeyEnv || LOCALINGOS_API_KEY) > .localingos.json > localingos.config.json
+ */
+
+const PROJECT_CONFIG_FILE = 'localingos.config.json';
+const LOCAL_CONFIG_FILE = '.localingos.json';
 
 const ENVIRONMENTS = {
     prod: 'https://api.localingos.com',
@@ -10,13 +26,6 @@ const ENVIRONMENTS = {
     local: 'https://desktop.localingos.com:8080'
 };
 
-/**
- * Resolve the API URL based on --env flag or LOCALINGOS_ENV env variable.
- * Defaults to production.
- *
- * For the 'local' environment, TLS certificate verification is disabled
- * since the local dev server uses a self-signed certificate.
- */
 export function resolveApiUrl(envFlag) {
     const env = envFlag || process.env.LOCALINGOS_ENV || 'prod';
     const url = ENVIRONMENTS[env];
@@ -25,45 +34,97 @@ export function resolveApiUrl(envFlag) {
         console.error(chalk.red(`Unknown environment "${env}". Valid: ${valid}`));
         process.exit(1);
     }
-
-    // Disable TLS verification for local dev (self-signed certificate)
     if (env === 'local') {
         process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
     }
-
     return url;
 }
 
+function readJsonSafe(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    } catch {
+        return null;
+    }
+}
+
 export function loadConfig(configPath) {
-    const resolvedPath = path.resolve(configPath || DEFAULT_CONFIG_FILE);
+    // If explicit --config flag was passed, use only that file (backward compat)
+    if (configPath && configPath !== LOCAL_CONFIG_FILE) {
+        const resolved = path.resolve(configPath);
+        if (!fs.existsSync(resolved)) {
+            console.error(chalk.red(`Config file not found: ${resolved}`));
+            process.exit(1);
+        }
+        const config = readJsonSafe(resolved);
+        if (!config) {
+            console.error(chalk.red(`Failed to parse config file: ${resolved}`));
+            process.exit(1);
+        }
+        return resolveApiKey(config);
+    }
+
+    // Merge: project config (committed) ← local overrides (.gitignored)
+    const projectPath = path.resolve(PROJECT_CONFIG_FILE);
+    const localPath = path.resolve(LOCAL_CONFIG_FILE);
+
+    const projectConfig = readJsonSafe(projectPath) || {};
+    const localConfig = readJsonSafe(localPath) || {};
 
-    if (!fs.existsSync(resolvedPath)) {
-        console.error(chalk.red(`Config file not found: ${resolvedPath}`));
+    if (!Object.keys(projectConfig).length && !Object.keys(localConfig).length) {
+        console.error(chalk.red(`No config found. Expected ${PROJECT_CONFIG_FILE} or ${LOCAL_CONFIG_FILE}`));
         console.error(chalk.yellow('Run "localingos init" to create one.'));
         process.exit(1);
     }
 
-    try {
-        const raw = fs.readFileSync(resolvedPath, 'utf-8');
-        const config = JSON.parse(raw);
+    // Local overrides project
+    const config = { ...projectConfig, ...localConfig };
+
+    return resolveApiKey(config);
+}
+
+function resolveApiKey(config) {
+    // Env var takes precedence: check project-specific name first, then generic
+    const envVarName = config.apiKeyEnv || 'LOCALINGOS_API_KEY';
+    if (process.env[envVarName]) {
+        config.apiKey = process.env[envVarName];
+    }
 
-        // Validate required fields
-        const required = ['apiKey', 'familyId', 'sourceLocale', 'format', 'sourceFile', 'outputDir'];
-        const missing = required.filter(field => !config[field]);
-        if (missing.length > 0) {
+    const required = ['apiKey', 'familyId', 'sourceLocale', 'format', 'sourceFile', 'outputDir'];
+    const missing = required.filter(field => !config[field]);
+    if (missing.length > 0) {
+        if (missing.length === 1 && missing[0] === 'apiKey') {
+            console.error(chalk.red('API key not found. Provide it via one of:'));
+            console.error(chalk.yellow(`  • Environment variable: ${envVarName}`));
+            console.error(chalk.yellow(`  • "apiKey" field in ${LOCAL_CONFIG_FILE} (gitignored)`));
+        } else {
             console.error(chalk.red(`Missing required config fields: ${missing.join(', ')}`));
-            process.exit(1);
         }
-
-        return config;
-    } catch (e) {
-        console.error(chalk.red(`Failed to parse config file: ${e.message}`));
         process.exit(1);
     }
+
+    return config;
 }
 
+/**
+ * Save the project config (committed) and local config (gitignored) separately.
+ */
 export function saveConfig(config, configPath) {
-    const resolvedPath = path.resolve(configPath || DEFAULT_CONFIG_FILE);
-    fs.writeFileSync(resolvedPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
-    return resolvedPath;
-}
+    // If explicit path, write everything there (backward compat)
+    if (configPath && configPath !== LOCAL_CONFIG_FILE) {
+        const resolved = path.resolve(configPath);
+        fs.writeFileSync(resolved, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+        return resolved;
+    }
+
+    // Split: apiKey goes to .localingos.json, everything else to localingos.config.json
+    const { apiKey, ...projectFields } = config;
+
+    const projectPath = path.resolve(PROJECT_CONFIG_FILE);
+    const localPath = path.resolve(LOCAL_CONFIG_FILE);
+
+    fs.writeFileSync(projectPath, JSON.stringify(projectFields, null, 2) + '\n', 'utf-8');
+    fs.writeFileSync(localPath, JSON.stringify({ apiKey }, null, 2) + '\n', 'utf-8');
+
+    return projectPath;
+}