locale-sync-cli 1.0.0

package/bin/locale-sync.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// Polyfill Web APIs (fetch, Headers, FormData, etc.) for Node < 18
+if (typeof globalThis.fetch === 'undefined') {
+  const undici = require('undici');
+  const globals = ['fetch','Headers','Request','Response','FormData','File'];
+  for (const k of globals) { if (undici[k]) globalThis[k] = undici[k]; }
+}
+if (typeof globalThis.Blob === 'undefined') {
+  globalThis.Blob = require('buffer').Blob;
+}
+if (typeof globalThis.ReadableStream === 'undefined') {
+  const webStreams = require('stream/web');
+  const streamGlobals = ['ReadableStream','WritableStream','TransformStream'];
+  for (const k of streamGlobals) { if (webStreams[k]) globalThis[k] = webStreams[k]; }
+}
+
+const { Command } = require('commander');
+const pkg = require('../package.json');
+const chalk = require('chalk');
+
+const program = new Command();
+program
+  .name('locale-sync')
+  .description('Enterprise i18n Sync CLI')
+  .version(pkg.version, '-v, --version');
+
+program
+  .command('set-credentials')
+  .description('🔑 Save Google service-account credentials to local env var')
+  .action(require('../lib/cli/commands/set-credentials'));
+
+program
+  .command('init')
+  .description(' Initialize project config')
+  .action(require('../lib/cli/commands/init'));
+
+program
+  .command('push')
+  .alias('p')
+  .description('📤 Local → Google Sheets')
+  .option('-y, --yes', 'Skip confirmation prompt')
+  .option('-v, --verbose', 'Enable verbose logging')
+  .action(require('../lib/cli/commands/push'));
+
+program
+  .command('pull')
+  .alias('l')
+  .description('📥 Google Sheets → Local')
+  .option('-y, --yes', 'Skip confirmation prompt')
+  .option('-v, --verbose', 'Enable verbose logging')
+  .action(require('../lib/cli/commands/pull'));
+
+program
+  .command('ignore [patterns...]')
+  .description('🚫 Manage ignore patterns (files/folders/extensions to skip during scan)')
+  .option('-l, --list', 'List current ignore patterns')
+  .option('-r, --remove', 'Remove the specified patterns instead of adding')
+  .action(require('../lib/cli/commands/ignore'));
+
+program
+  .description('⚙️ Show current configuration')
+  .action(async () => {
+    const { loadConfig } = require('../lib/config/manager');
+    console.log(chalk.bold('\n📋 Current Config:'));
+    console.log(JSON.stringify(await loadConfig(), null, 2));
+  });
+
+program.parse(process.argv);
+
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+}

package/config/default.json

@@ -0,0 +1,18 @@
+{
+  "project": "${package.json.name}",
+  "sheetId": "",
+  "keyFile": "./service-account.json",
+  "locales": ["locales/lang"],
+  "ignore": [],
+  "targetLocales": ["ar", "pt", "es", "zh", "ja", "fr", "de"],
+  "sync": {
+    "antiLoopWindow": 0,
+    "ciAntiLoopWindow": 300,
+    "dryRun": true,
+    "pruneDeadKeys": false
+  },
+  "formats": {
+    "js": { "strategy": "ast", "preserve": "100%" },
+    "json": { "strategy": "stable", "indent": 2, "sortKeys": true }
+  }
+}

package/lib/cli/commands/ignore.js

@@ -0,0 +1,79 @@
+const fs   = require('fs').promises;
+const path = require('path');
+const logger = require('../utils/logger');
+
+const CONFIG_PATH = () => path.join(process.cwd(), '.locale-sync.json');
+
+async function readConfig() {
+  try {
+    return JSON.parse(await fs.readFile(CONFIG_PATH(), 'utf8'));
+  } catch (e) {
+    if (e.code === 'ENOENT') throw new Error('No .locale-sync.json found. Run `locale-sync init` first.');
+    throw e;
+  }
+}
+
+async function writeConfig(config) {
+  await fs.writeFile(CONFIG_PATH(), JSON.stringify(config, null, 2));
+}
+
+module.exports = async (patterns, options) => {
+  // --list: 显示当前忽略规则
+  if (options.list) {
+    const config = await readConfig();
+    const current = config.ignore || [];
+    if (current.length === 0) {
+      logger.info('No ignore patterns configured.');
+    } else {
+      logger.info('📋 Current ignore patterns:');
+      current.forEach((p, i) => console.log(`  ${i + 1}. ${p}`));
+    }
+    return;
+  }
+
+  // --remove: 移除指定规则
+  if (options.remove) {
+    const config = await readConfig();
+    const before = config.ignore || [];
+    config.ignore = before.filter(p => !patterns.includes(p));
+    const removed = before.filter(p => patterns.includes(p));
+    if (removed.length === 0) {
+      logger.warn(`⚠️  None of the specified patterns were found: ${patterns.join(', ')}`);
+      return;
+    }
+    await writeConfig(config);
+    logger.success(`✅ Removed: ${removed.join(', ')}`);
+    if (config.ignore.length > 0) {
+      logger.info(`📋 Remaining: ${config.ignore.join(', ')}`);
+    }
+    return;
+  }
+
+  // 默认：添加规则
+  if (!patterns || patterns.length === 0) {
+    logger.warn('Usage: locale-sync ignore <pattern...>');
+    logger.info('  Examples:');
+    logger.info('    locale-sync ignore node_modules');
+    logger.info('    locale-sync ignore *.d.ts index.js');
+    logger.info('    locale-sync ignore --list');
+    logger.info('    locale-sync ignore --remove node_modules');
+    return;
+  }
+
+  const config = await readConfig();
+  const current = config.ignore || [];
+  const toAdd   = patterns.filter(p => !current.includes(p));
+  const skipped = patterns.filter(p => current.includes(p));
+
+  if (toAdd.length === 0) {
+    logger.info(`All patterns already exist: ${patterns.join(', ')}`);
+    return;
+  }
+
+  config.ignore = [...current, ...toAdd];
+  await writeConfig(config);
+
+  logger.success(`✅ Added: ${toAdd.join(', ')}`);
+  if (skipped.length > 0) logger.info(`⏭  Already existed: ${skipped.join(', ')}`);
+  logger.info(`📋 All ignore patterns: ${config.ignore.join(', ')}`);
+};

package/lib/cli/commands/init.js

@@ -0,0 +1,59 @@
+const inquirer = require('inquirer');
+const fs = require('fs');
+const fsP = require('fs').promises;
+const path = require('path');
+const logger = require('../utils/logger');
+const { hasCredentials, fetchOrReadCredentials, writeCredentials } = require('../utils/credentials');
+
+function isUrl(s) { return /^https?:\/\//i.test(s.trim()); }
+
+module.exports = async () => {
+  logger.info('🛠 Initialize locale-sync configuration\n');
+  const answers = await inquirer.prompt([
+    { type: 'input', name: 'sheetId', message: 'Google Sheet ID:', validate: v => v.length > 10 || 'Required' },
+    { type: 'input', name: 'locales', message: 'Locales Directory:', default: 'locales/lang' },
+    { type: 'input', name: 'project', message: 'Project Name:', default: path.basename(process.cwd()) },
+    { type: 'input', name: 'ignore', message: 'Ignore patterns (comma-separated, e.g. node_modules,*.d.ts):', default: '' }
+  ]);
+
+  const config = {
+    sheetId:  answers.sheetId,
+    locales:  [answers.locales],
+    ignore:   answers.ignore ? answers.ignore.split(',').map(s => s.trim()).filter(Boolean) : [],
+    project:  answers.project,
+    sync: { dryRun: true, pruneDeadKeys: false, antiLoopWindow: 0 }
+  };
+
+  await fsP.writeFile(path.join(process.cwd(), '.locale-sync.json'), JSON.stringify(config, null, 2));
+  logger.success('✅ Configuration saved to .locale-sync.json');
+
+  if (hasCredentials()) {
+    logger.info('✅ LOCALE_SYNC_CREDENTIALS already set, skipping credential setup.');
+  } else {
+    logger.warn('⚠️  LOCALE_SYNC_CREDENTIALS not found. Please provide your service-account.json.\n');
+    const { source } = await inquirer.prompt([{
+      type: 'input',
+      name: 'source',
+      message: 'Path or URL to service-account.json:',
+      default: './service-account.json',
+      validate: v => {
+        if (isUrl(v)) return true;
+        if (!fs.existsSync(v.trim())) return `File not found: ${v.trim()}`;
+        try { JSON.parse(fs.readFileSync(v.trim(), 'utf8')); return true; }
+        catch { return 'File is not valid JSON'; }
+      }
+    }]);
+    if (isUrl(source)) {
+      logger.warn('⚠️  Fetching credentials from a URL. Make sure this URL is private and not publicly accessible.');
+    }
+    const raw     = await fetchOrReadCredentials(source);
+    const profile = writeCredentials(raw);
+    logger.success(`✅ Credentials saved to ${profile}`);
+    if (!isUrl(source)) {
+      logger.info(`💡 The original file can now be deleted: rm ${source.trim()}`);
+    }
+    logger.info(`💡 For existing terminals run: source ${profile}`);
+  }
+
+  logger.info('\n💡 Run `locale-sync push` or `locale-sync pull` to start syncing.');
+};

package/lib/cli/commands/pull.js

@@ -0,0 +1,60 @@
+const chalk = require('chalk');
+const ora = require('ora');
+const inquirer = require('inquirer');
+const { loadConfig } = require('../../config/manager');
+const { getClient, readSheet, ensureMetadataColumns } = require('../../io/googleSheets');
+const { scanLocales } = require('../../io/localFs/scanner');
+const { generatePullPlan } = require('../../core/engines/pullEngine');
+const { applyAstUpdates } = require('../../io/localFs/astUpdater');
+const logger = require('../utils/logger');
+
+module.exports = async (options) => {
+  const config = await loadConfig(options);
+  const spinner = ora('📥 Reading Sheets & Scanning Locales...').start();
+  
+  try {
+    const sheets = await getClient(config.keyFile);
+    await ensureMetadataColumns(sheets, config.sheetId, config.project);
+    await ensureMetadataColumns(sheets, config.sheetId, 'common');
+    
+    const [commonData, projectData] = await Promise.all([
+      readSheet(sheets, config.sheetId, 'common'),
+      readSheet(sheets, config.sheetId, config.project)
+    ]);
+    
+    const local = await scanLocales(config.locales, config.ignore);
+    spinner.succeed('✅ Data loaded');
+
+    const plan = await generatePullPlan(projectData, commonData, local, config);
+    
+    console.log(chalk.bold('\n📋 Pull Preview'));
+    console.log(`   Updates: ${plan.length}`);
+    if (plan.length > 0) {
+      plan.forEach(p => console.log(`  - ${p.locale}/${p.key}: "${p.oldValue}" → "${p.newValue}"`));
+    }
+
+    if (plan.length === 0 || config.sync.dryRun) {
+      spinner.info('✅ No changes or Dry-Run mode');
+      return;
+    }
+
+    if (!options.yes) {
+      const { proceed } = await inquirer.prompt([{ type: 'confirm', name: 'proceed', message: 'Apply to local files?', default: false }]);
+      if (!proceed) return logger.info('👋 Sync cancelled.');
+    }
+
+    spinner.start(' Updating local files...');
+    const res = await applyAstUpdates(plan, false);
+    spinner.succeed(`✅ Updated ${res.updated} files`);
+    
+    if (res.warnings.length) {
+      logger.warn('⚠️  Warnings:');
+      res.warnings.forEach(w => logger.warn(`  ${w}`));
+    }
+  } catch (err) {
+    spinner.fail(' Pull failed');
+    logger.error(err.message);
+    if (options.verbose) console.error(err);
+    process.exit(1);
+  }
+};

package/lib/cli/commands/push.js

@@ -0,0 +1,136 @@
+const chalk = require('chalk');
+const ora = require('ora');
+const inquirer = require('inquirer');
+const { loadConfig } = require('../../config/manager');
+const { getClient, readSheet, ensureMetadataColumns, batchWrite, buildSheetFormatRequests } = require('../../io/googleSheets');
+const { scanLocales } = require('../../io/localFs/scanner');
+const { generatePushPlan } = require('../../core/engines/pushEngine');
+const { formatLocaleHeader } = require('../../core/utils/stringNormalizer');
+const logger = require('../utils/logger');
+
+module.exports = async (options) => {
+  const config = await loadConfig(options);
+  const spinner = ora('📤 Reading Sheets & Scanning Locales...').start();
+  
+  try {
+    const sheets = await getClient(config.keyFile);
+    // 先扫描语言包，再动态生成表头（en-US / ar-SA 格式）
+    const local = await scanLocales(config.locales, config.ignore);
+    const _getLocaleBase = loc => loc.length <= 3 ? loc : loc.slice(0, 2);
+    const scannedNorms = Object.keys(local)
+      .filter(k => Object.keys(local[k].values).length > 0)
+      .map(k => k.toLowerCase().replace(/[-_]/g, ''));
+    const enNorm       = scannedNorms.find(k => _getLocaleBase(k) === 'en') || 'en';
+    const enColHeader  = formatLocaleHeader(enNorm);
+    const nonEnHeaders = scannedNorms
+      .filter(k => _getLocaleBase(k) !== 'en')
+      .map(formatLocaleHeader);
+    // 自动初始化 Sheet 结构（新 Sheet 时写入动态表头）
+    const projectBaseHeaders = ['key', 'filePath', enColHeader, ...nonEnHeaders];
+    const commonBaseHeaders  = [enColHeader, ...nonEnHeaders];
+    await ensureMetadataColumns(sheets, config.sheetId, config.project, projectBaseHeaders);
+    await ensureMetadataColumns(sheets, config.sheetId, 'common', commonBaseHeaders);
+
+    const [commonData, projectData] = await Promise.all([
+      readSheet(sheets, config.sheetId, 'common'),
+      readSheet(sheets, config.sheetId, config.project)
+    ]);
+    spinner.succeed('✅ Data loaded');
+
+    // locale 基础语言码映射：'enus'→'en', 'arae'→'ar', 'zhcn'→'zh'（≤3位视为纯代码）
+    const getLocaleBase = loc => loc.length <= 3 ? loc : loc.slice(0, 2);
+    // 优先找纯语言文件，否则找任意同基础语言的 locale
+    const findLocaleData = base =>
+      local[base] || Object.entries(local).find(([k]) => getLocaleBase(k) === base)?.[1];
+
+    const enData = findLocaleData('en');
+    const allKeys = new Set();
+    for (const data of Object.values(local)) {
+      for (const key of Object.keys(data.values)) allKeys.add(key);
+    }
+
+    // ── 扫描摘要：帮助确认本地内容是否完整 ──
+    const localeEntries = Object.entries(local)
+      .filter(([, d]) => Object.keys(d.values).length > 0)
+      .sort(([, a], [, b]) => Object.keys(b.values).length - Object.keys(a.values).length);
+    const maxLocale = Math.max(...localeEntries.map(([k]) => k.length), 6);
+    console.log(chalk.bold('\n🔍 Scan Summary'));
+    console.log(`   Total unique keys : ${chalk.cyan(allKeys.size)}`);
+    console.log(`   Locales scanned   : ${localeEntries.length}`);
+    for (const [loc, data] of localeEntries) {
+      const count = Object.keys(data.values).length;
+      const emptyCount = Object.values(data.values).filter(v => v == null || String(v).trim() === '').length;
+      const pad = ' '.repeat(maxLocale - loc.length);
+      const emptyNote = emptyCount > 0 ? chalk.gray(` (${emptyCount} empty)`) : '';
+      console.log(`   ${chalk.yellow(loc)}${pad}  ${count} keys${emptyNote}`);
+    }
+
+    const localItems = [...allKeys].map(key => {
+      const translations = {};
+      for (const [locale, data] of Object.entries(local)) {
+        if (data.values[key] === undefined) continue;
+        translations[locale] = data.values[key];
+        // 同时填充基础语言码（arae→ar, enus→en），纯语言文件优先不覆盖
+        const base = getLocaleBase(locale);
+        if (base !== locale && !(base in translations)) {
+          translations[base] = data.values[key];
+        }
+      }
+      let filePath = '';
+      for (const data of Object.values(local)) {
+        const fp = data.filePaths?.[key] || (data.values[key] !== undefined ? data.filePath : null);
+        if (fp) { filePath = fp; break; }
+      }
+      return { key, filePath, en: translations['en'] || enData?.values[key] || '', translations };
+    });
+
+    const requests = await generatePushPlan(localItems, {
+      common: commonData,
+      project: projectData,
+      projectHeaders: projectData.headers || [],
+      projectSheetId: projectData.sheetId ?? 0,
+      commonHeaders:  commonData.headers  || [],
+      commonSheetId:  commonData.sheetId  ?? 0
+    }, config);
+    
+    let newRows = 0;
+    const updatedRowKeys = new Set();
+    for (const req of requests) {
+      if (req.appendCells) {
+        newRows += req.appendCells.rows?.length ?? 0;
+      } else if (req.updateCells) {
+        // 仅统计翻译/内容写入（有 backgroundColor 格式），排除纯元数据行
+        if (req.updateCells.fields && req.updateCells.fields.includes('backgroundColor')) {
+          const r = req.updateCells.range;
+          updatedRowKeys.add(`${r.sheetId}:${r.startRowIndex}`);
+        }
+      }
+    }
+    console.log(chalk.bold('\n📋 Push Preview'));
+    console.log(`   New rows    : ${newRows}`);
+    console.log(`   Updated rows: ${updatedRowKeys.size}`);
+
+    if (config.sync.dryRun || requests.length === 0) {
+      spinner.info('✅ No changes or Dry-Run mode');
+      return;
+    }
+
+    if (!options.yes) {
+      const { proceed } = await inquirer.prompt([{ type: 'confirm', name: 'proceed', message: 'Apply to Google Sheets?', default: false }]);
+      if (!proceed) return logger.info('👋 Sync cancelled.');
+    }
+
+    spinner.start('🔄 Syncing to Google Sheets...');
+    const formatReqs = [
+      ...buildSheetFormatRequests(commonData.sheetId),
+      ...buildSheetFormatRequests(projectData.sheetId)
+    ];
+    await batchWrite(sheets, config.sheetId, [...formatReqs, ...requests]);
+    spinner.succeed('✅ Push completed successfully');
+  } catch (err) {
+    spinner.fail('❌ Push failed');
+    logger.error(err.message);
+    if (options.verbose) console.error(err);
+    process.exit(1);
+  }
+};

package/lib/cli/commands/set-credentials.js

@@ -0,0 +1,35 @@
+const inquirer = require('inquirer');
+const fs       = require('fs');
+const logger   = require('../utils/logger');
+const { fetchOrReadCredentials, writeCredentials } = require('../utils/credentials');
+
+function isUrl(s) { return /^https?:\/\//i.test(s.trim()); }
+
+module.exports = async () => {
+  logger.info('🔑 Update Google Service Account credentials\n');
+
+  const { source } = await inquirer.prompt([{
+    type: 'input',
+    name: 'source',
+    message: 'Path or URL to service-account.json:',
+    default: './service-account.json',
+    validate: v => {
+      if (isUrl(v)) return true;  // URL 延迟验证
+      if (!fs.existsSync(v.trim())) return `File not found: ${v.trim()}`;
+      try { JSON.parse(fs.readFileSync(v.trim(), 'utf8')); return true; }
+      catch { return 'File is not valid JSON'; }
+    }
+  }]);
+
+  if (isUrl(source)) {
+    logger.warn('⚠️  Fetching credentials from a URL. Make sure this URL is private and not publicly accessible.');
+  }
+
+  const raw     = await fetchOrReadCredentials(source);
+  const profile = writeCredentials(raw);
+  logger.success(`✅ Credentials saved to ${profile}`);
+  if (!isUrl(source)) {
+    logger.info(`💡 The original file can now be deleted: rm ${source.trim()}`);
+  }
+  logger.info(`💡 For existing terminals run: source ${profile}`);
+};

package/lib/cli/utils/credentials.js

@@ -0,0 +1,66 @@
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+const ENV_KEY = 'LOCALE_SYNC_CREDENTIALS';
+
+function detectShellProfile() {
+  const shell = process.env.SHELL || '';
+  if (shell.includes('zsh'))  return path.join(os.homedir(), '.zshrc');
+  if (shell.includes('fish')) return path.join(os.homedir(), '.config', 'fish', 'config.fish');
+  return path.join(os.homedir(), '.bash_profile');
+}
+
+/**
+ * 从本地文件路径或 http(s) URL 读取 service-account JSON 内容。
+ * @param {string} source  文件路径或 URL
+ * @returns {Promise<string>}  JSON 字符串
+ */
+async function fetchOrReadCredentials(source) {
+  const trimmed = source.trim();
+  if (/^https?:\/\//i.test(trimmed)) {
+    const res = await fetch(trimmed);
+    if (!res.ok) throw new Error(`Failed to fetch credentials: ${res.status} ${res.statusText}`);
+    return res.text();
+  }
+  // 本地文件
+  return fs.readFileSync(trimmed, 'utf8');
+}
+
+/**
+ * 将 service-account JSON 字符串 base64 编码后写入 shell profile，
+ * 同时设置当前进程的环境变量（本次运行立即生效）。
+ * @param {string} jsonString  service-account JSON 原文
+ * @returns {string}           写入的 profile 文件路径
+ */
+function writeCredentials(jsonString) {
+  JSON.parse(jsonString.trim()); // 验证 JSON 合法
+
+  const token   = Buffer.from(jsonString.trim()).toString('base64');
+  const profile = detectShellProfile();
+
+  let content = '';
+  try { content = fs.readFileSync(profile, 'utf8'); } catch { /* 文件不存在则新建 */ }
+
+  const lines = content.split('\n');
+  const idx   = lines.findIndex(l => l.includes(ENV_KEY));
+  const line  = `export ${ENV_KEY}="${token}"`;
+
+  if (idx >= 0) {
+    lines[idx] = line;
+  } else {
+    lines.push('', '# locale-sync Google credentials (base64 service-account JSON)', line);
+  }
+
+  fs.writeFileSync(profile, lines.join('\n'));
+  process.env[ENV_KEY] = token;
+
+  return profile;
+}
+
+/** 检查当前环境变量是否已配置 */
+function hasCredentials() {
+  return !!process.env[ENV_KEY];
+}
+
+module.exports = { ENV_KEY, detectShellProfile, fetchOrReadCredentials, writeCredentials, hasCredentials };

package/lib/cli/utils/logger.js

@@ -0,0 +1,9 @@
+const chalk = require('chalk');
+
+module.exports = {
+  info: (msg) => console.log(chalk.blue('ℹ️'), msg),
+  success: (msg) => console.log(chalk.green('✅'), msg),
+  warn: (msg) => console.warn(chalk.yellow('⚠️'), msg),
+  error: (msg) => console.error(chalk.red('❌'), msg),
+  debug: (msg) => process.env.DEBUG ? console.log(chalk.gray('🐛'), msg) : null
+};

package/lib/config/manager.js

@@ -0,0 +1,44 @@
+const fs = require('fs').promises;
+const path = require('path');
+
+const LOCAL_CONFIG = path.join(process.cwd(), '.locale-sync.json');
+const DEFAULT_CONFIG = require('../../config/default.json');
+
+function deepMerge(target, source) {
+  const output = Object.assign({}, target);
+  if (typeof source === 'object' && source !== null) {
+    Object.keys(source).forEach(key => {
+      if (typeof source[key] === 'object' && source[key] !== null && !Array.isArray(source[key])) {
+        output[key] = deepMerge(output[key] != null ? output[key] : {}, source[key]);
+      } else {
+        output[key] = source[key];
+      }
+    });
+  }
+  return output;
+}
+
+async function loadConfig(overrides = {}) {
+  let config = DEFAULT_CONFIG;
+  try {
+    const local = JSON.parse(await fs.readFile(LOCAL_CONFIG, 'utf8'));
+    config = deepMerge(config, local);
+  } catch (err) {
+    if (err.code !== 'ENOENT') console.warn(`[locale-sync] Warning: could not load config: ${err.message}`);
+  }
+
+  if (config.project === '${package.json.name}') {
+    try {
+      config.project = require(path.join(process.cwd(), 'package.json')).name;
+    } catch {
+      config.project = 'unknown-project';
+    }
+  }
+
+  const isCI = process.env.CI === 'true' || process.argv.includes('--ci');
+  config.sync.antiLoopWindow = isCI ? config.sync.ciAntiLoopWindow : config.sync.antiLoopWindow;
+
+  return deepMerge(config, overrides);
+}
+
+module.exports = { loadConfig };