@final-commerce/common 1.1.4-beta.4

package/bin/gate-i18n-sync.mjs

@@ -0,0 +1,351 @@
+#!/usr/bin/env node
+/**
+ * gate-i18n-sync — generic i18n key sync bin.
+ *
+ * Reads config from the "fc-i18n" key in the project's package.json:
+ *
+ *   "fc-i18n": {
+ *     "slug":          "my-project",              // required — mt project slug
+ *     "localesDir":    "src/locales",             // optional, default "src/locales"
+ *     "i18nIndexPath": "src/providers/i18n/index.ts"  // optional — file containing
+ *   }                                             //   the SUPPORTED_LOCALES marker block
+ *
+ * Flow:
+ *   1. Run i18next-parser → JSON of all t() keys extracted from src/.
+ *   2. Diff against the committed localesDir/en.json.
+ *   3. If new/changed keys: call mt sync_keys (autoTranslate), then
+ *      get_translations to pull the canonical bundle, write localesDir/*.json.
+ *   4. If i18nIndexPath set, rewrite SUPPORTED_LOCALES between marker comments.
+ *   5. git add localesDir (and i18nIndexPath if changed) so the bundle lands
+ *      in the same commit.
+ *
+ * Env:
+ *   MT_API_KEY       — required for the mt round-trip
+ *   SKIP_I18N_SYNC=1 — escape hatch for offline commits
+ *   MT_URL           — override mt MCP endpoint
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+// ── bootstrap ─────────────────────────────────────────────────────────────────
+
+const root = process.cwd();
+
+if (process.env.SKIP_I18N_SYNC === '1') {
+  console.log('[i18n-sync] SKIP_I18N_SYNC=1 — skipping.');
+  process.exit(0);
+}
+
+const pkgPath = resolve(root, 'package.json');
+if (!existsSync(pkgPath)) process.exit(0);
+
+let pkg;
+try {
+  pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+} catch {
+  process.exit(0);
+}
+
+const cfg = pkg['fc-i18n'];
+if (!cfg?.slug) {
+  console.error('[i18n-sync] No "fc-i18n" config with a "slug" found in package.json — skipping.');
+  process.exit(0);
+}
+
+const PROJECT_SLUG = cfg.slug;
+const SOURCE_LOCALE = 'en';
+const LOCALES_DIR = resolve(root, cfg.localesDir ?? 'src/locales');
+const I18N_INDEX_PATH = cfg.i18nIndexPath ? resolve(root, cfg.i18nIndexPath) : null;
+const EXTRACT_DIR = resolve(root, 'node_modules/.cache/i18next-extract');
+const CURRENT_EN = resolve(LOCALES_DIR, `${SOURCE_LOCALE}.json`);
+const MT_URL = process.env.MT_URL ?? 'https://mt.finalpos.com/api/mcp';
+
+const LOCALES_BLOCK_START = '// <i18n-sync:locales>';
+const LOCALES_BLOCK_END = '// </i18n-sync:locales>';
+
+// Load env from .env.local then .env (process.env values always win).
+function loadEnvFile(path) {
+  if (!existsSync(path)) return;
+  for (const rawLine of readFileSync(path, 'utf-8').split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const eq = line.indexOf('=');
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim();
+    if (!key || key in process.env) continue;
+    let value = line.slice(eq + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    process.env[key] = value;
+  }
+}
+
+loadEnvFile(resolve(root, '.env.local'));
+loadEnvFile(resolve(root, '.env'));
+
+// ── ANSI helpers ──────────────────────────────────────────────────────────────
+
+const COLOR = !process.env.NO_COLOR && process.stderr.isTTY;
+const c = {
+  reset: COLOR ? '\x1b[0m' : '',
+  bold: COLOR ? '\x1b[1m' : '',
+  dim: COLOR ? '\x1b[2m' : '',
+  red: COLOR ? '\x1b[31m' : '',
+  yellow: COLOR ? '\x1b[33m' : '',
+  cyan: COLOR ? '\x1b[36m' : '',
+};
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function readJson(path, fallback) {
+  if (!existsSync(path)) return fallback;
+  return JSON.parse(readFileSync(path, 'utf-8'));
+}
+
+function writeJsonSorted(path, data) {
+  const sorted = Object.fromEntries(Object.entries(data).sort(([a], [b]) => a.localeCompare(b)));
+  const content = JSON.stringify(sorted, null, 2) + '\n';
+  if (existsSync(path) && readFileSync(path, 'utf-8') === content) return false;
+  writeFileSync(path, content, 'utf-8');
+  return true;
+}
+
+function readSupportedLocalesFromCode() {
+  if (!I18N_INDEX_PATH || !existsSync(I18N_INDEX_PATH)) return null;
+  const content = readFileSync(I18N_INDEX_PATH, 'utf-8');
+  const startIdx = content.indexOf(LOCALES_BLOCK_START);
+  const endIdx = content.indexOf(LOCALES_BLOCK_END);
+  if (startIdx === -1 || endIdx === -1 || endIdx < startIdx) return null;
+  const matches = content.slice(startIdx, endIdx).match(/["']([a-zA-Z]{2,3}(?:-[a-zA-Z]{1,8})?)["']/g) ?? [];
+  return matches.map((m) => m.slice(1, -1));
+}
+
+function writeSupportedLocalesToCode(locales) {
+  if (!I18N_INDEX_PATH) return false;
+  if (!existsSync(I18N_INDEX_PATH)) {
+    console.error(`[i18n-sync] ${I18N_INDEX_PATH} missing; cannot write locales.`);
+    return false;
+  }
+  const content = readFileSync(I18N_INDEX_PATH, 'utf-8');
+  const startIdx = content.indexOf(LOCALES_BLOCK_START);
+  const endIdx = content.indexOf(LOCALES_BLOCK_END);
+  if (startIdx === -1 || endIdx === -1 || endIdx < startIdx) {
+    console.error(`[i18n-sync] Missing markers in ${I18N_INDEX_PATH}. Restore the // <i18n-sync:locales> block.`);
+    return false;
+  }
+  const arrayLiteral = `[${[...locales]
+    .sort()
+    .map((l) => JSON.stringify(l))
+    .join(', ')}]`;
+  const replacement =
+    LOCALES_BLOCK_START +
+    ' — auto-managed by gate-i18n-sync; do not edit by hand\n' +
+    `export const SUPPORTED_LOCALES = ${arrayLiteral} as const;\n`;
+  const updated = content.slice(0, startIdx) + replacement + content.slice(endIdx);
+  if (updated === content) return false;
+  writeFileSync(I18N_INDEX_PATH, updated, 'utf-8');
+  return true;
+}
+
+function runExtractor() {
+  mkdirSync(EXTRACT_DIR, { recursive: true });
+  const result = spawnSync('npx', ['i18next-parser', '--config', 'i18next-parser.config.cjs', '--silent'], {
+    cwd: root,
+    stdio: 'inherit',
+  });
+  if (result.status !== 0) {
+    console.error('[i18n-sync] i18next-parser failed.');
+    process.exit(1);
+  }
+  return readJson(resolve(EXTRACT_DIR, 'en.json'), {});
+}
+
+function computeDesiredSource(extracted, currentEn) {
+  const desired = {};
+  for (const [key, extractedValue] of Object.entries(extracted)) {
+    const isPlaceholder = extractedValue === key || extractedValue === '';
+    desired[key] = isPlaceholder ? (currentEn[key] ?? key) : extractedValue;
+  }
+  return desired;
+}
+
+function diffKeys(currentEn, desired) {
+  const added = [];
+  const changed = [];
+  const removed = [];
+  for (const key of Object.keys(desired)) {
+    if (!(key in currentEn)) added.push(key);
+    else if (currentEn[key] !== desired[key]) changed.push(key);
+  }
+  for (const key of Object.keys(currentEn)) {
+    if (!(key in desired)) removed.push(key);
+  }
+  return { added, changed, removed };
+}
+
+function unwrapMcpJson(result) {
+  const block = result.content?.[0];
+  if (!block || block.type !== 'text' || typeof block.text !== 'string') {
+    throw new Error('[i18n-sync] Unexpected MCP response shape.');
+  }
+  return JSON.parse(block.text);
+}
+
+function pruneLocaleFiles(liveKeys) {
+  let count = 0;
+  if (!existsSync(LOCALES_DIR)) return 0;
+  for (const file of readdirSync(LOCALES_DIR)) {
+    if (!file.endsWith('.json') || file.startsWith('_')) continue;
+    const path = resolve(LOCALES_DIR, file);
+    const existing = readJson(path, {});
+    const filtered = Object.fromEntries(Object.entries(existing).filter(([k]) => liveKeys.has(k)));
+    if (JSON.stringify(existing) !== JSON.stringify(filtered)) {
+      writeJsonSorted(path, filtered);
+      count += Object.keys(existing).length - Object.keys(filtered).length;
+    }
+  }
+  return count;
+}
+
+// ── main ──────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const extracted = runExtractor();
+  const currentEn = readJson(CURRENT_EN, {});
+  const desired = computeDesiredSource(extracted, currentEn);
+  const { added, changed, removed } = diffKeys(currentEn, desired);
+  const liveKeys = new Set(Object.keys(desired));
+  const needsPush = added.length > 0 || changed.length > 0;
+
+  const MT_API_KEY = process.env.MT_API_KEY;
+  if (!MT_API_KEY) {
+    if (needsPush) {
+      console.error(
+        `\n[i18n-sync] ERROR: MT_API_KEY is not set.\n\n` +
+          `  ${added.length} new key(s), ${changed.length} changed key(s) need to be synced.\n\n` +
+          `  Add MT_API_KEY to .env.local, or set SKIP_I18N_SYNC=1 to bypass.\n`,
+      );
+      process.exit(1);
+    }
+    console.warn('[i18n-sync] MT_API_KEY not set — skipped server-side check.');
+    pruneLocaleFiles(liveKeys);
+    if (existsSync(LOCALES_DIR)) spawnSync('git', ['add', LOCALES_DIR], { cwd: root, stdio: 'inherit' });
+    return;
+  }
+
+  let Client, StreamableHTTPClientTransport;
+  try {
+    ({ Client } = await import('@modelcontextprotocol/sdk/client/index.js'));
+    ({ StreamableHTTPClientTransport } = await import('@modelcontextprotocol/sdk/client/streamableHttp.js'));
+  } catch {
+    console.error('[i18n-sync] @modelcontextprotocol/sdk is required. Run: npm i -D @modelcontextprotocol/sdk');
+    process.exit(1);
+  }
+
+  const transport = new StreamableHTTPClientTransport(new URL(MT_URL), {
+    requestInit: { headers: { Authorization: `Bearer ${MT_API_KEY}` } },
+  });
+  const client = new Client({ name: 'fc-i18n-sync', version: '1.0.0' });
+
+  const SYNC_TIMEOUT_MS = 5 * 60 * 1000;
+  const PULL_TIMEOUT_MS = 90 * 1000;
+
+  try {
+    try {
+      await client.connect(transport);
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      console.error(
+        `\n${c.yellow}${c.bold}[i18n-sync] WARN:${c.reset}${c.yellow} could not reach mt — skipping server-side sync.${c.reset}\n`,
+      );
+      console.error(`  ${c.dim}Reason:${c.reset} ${c.red}${reason}${c.reset}`);
+      if (needsPush) {
+        console.error(
+          `\n  ${c.red}${added.length} new + ${changed.length} changed key(s) will NOT be pushed to mt this commit.${c.reset}`,
+        );
+        console.error(
+          `  ${c.dim}Re-run${c.reset} ${c.cyan}npm run i18n:sync${c.reset} ${c.dim}once mt is reachable.${c.reset}\n`,
+        );
+      }
+      pruneLocaleFiles(liveKeys);
+      if (existsSync(LOCALES_DIR)) spawnSync('git', ['add', LOCALES_DIR], { cwd: root, stdio: 'inherit' });
+      return;
+    }
+
+    if (needsPush) {
+      const keysPayload = Object.entries(desired).map(([key, value]) => ({ key, value }));
+      await client.callTool(
+        { name: 'sync_keys', arguments: { slug: PROJECT_SLUG, keys: keysPayload, autoTranslate: true } },
+        undefined,
+        { timeout: SYNC_TIMEOUT_MS },
+      );
+    }
+
+    const translationsResult = await client.callTool(
+      { name: 'get_translations', arguments: { slug: PROJECT_SLUG } },
+      undefined,
+      { timeout: PULL_TIMEOUT_MS },
+    );
+    const payload = unwrapMcpJson(translationsResult);
+    const mtLocales = Object.keys(payload.locales);
+    const codeLocales = readSupportedLocalesFromCode() ?? [];
+    const newLocales = mtLocales.filter((l) => !codeLocales.includes(l));
+    const removedLocales = codeLocales.filter((l) => !mtLocales.includes(l));
+
+    const PLURAL_SUFFIX_RE = /_(zero|one|two|few|many|other)$/;
+    const localeFilesChanged = [];
+
+    for (const [locale, keys] of Object.entries(payload.locales)) {
+      const filtered = {};
+      for (const [key, rawValue] of Object.entries(keys)) {
+        const pluralMatch = key.match(PLURAL_SUFFIX_RE);
+        const baseKey = pluralMatch ? key.slice(0, pluralMatch.index) : key;
+        if (!liveKeys.has(key) && !liveKeys.has(baseKey)) continue;
+        let value = rawValue;
+        if (locale === SOURCE_LOCALE && pluralMatch && value === key) value = baseKey;
+        filtered[key] = value;
+      }
+      const path = resolve(LOCALES_DIR, `${locale}.json`);
+      if (writeJsonSorted(path, filtered)) localeFilesChanged.push(locale);
+    }
+
+    for (const locale of removedLocales) {
+      const path = resolve(LOCALES_DIR, `${locale}.json`);
+      if (existsSync(path)) spawnSync('git', ['rm', '--quiet', path], { cwd: root });
+    }
+
+    const codeUpdated = writeSupportedLocalesToCode(mtLocales);
+
+    if (localeFilesChanged.length > 0 || newLocales.length > 0 || removedLocales.length > 0 || codeUpdated) {
+      spawnSync('git', ['add', LOCALES_DIR], { cwd: root, stdio: 'inherit' });
+      if (codeUpdated && I18N_INDEX_PATH) {
+        spawnSync('git', ['add', I18N_INDEX_PATH], { cwd: root, stdio: 'inherit' });
+      }
+    }
+
+    const parts = [];
+    if (needsPush) parts.push(`${added.length} new`);
+    if (changed.length > 0) parts.push(`${changed.length} changed`);
+    if (removed.length > 0) parts.push(`${removed.length} orphan(s) on mt`);
+    if (newLocales.length > 0) parts.push(`pulled new locale(s): ${newLocales.join(', ')}`);
+    if (removedLocales.length > 0) parts.push(`dropped locale(s): ${removedLocales.join(', ')}`);
+    if (localeFilesChanged.length > 0 && !needsPush && newLocales.length === 0) {
+      parts.push(`updated ${localeFilesChanged.join(', ')} from mt`);
+    }
+    console.log(parts.length > 0 ? `[i18n-sync] ${parts.join(' · ')}` : '[i18n-sync] No changes.');
+  } finally {
+    try {
+      await client.close();
+    } catch {
+      /* ignore close errors */
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error('[i18n-sync] Failed:', err);
+  process.exit(1);
+});

package/bin/gate-save.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+/**
+ * gate-save — pre-commit hook.
+ *
+ * 1. Runs lint-staged over modified surfaces.
+ * 2. Scans staged .ts/.tsx/.js files for TODO comments that lack a Jira ticket
+ *    reference (e.g. "// TODO: do something FI-123").  Bare TODOs block commit.
+ *
+ * Exits 0 on success, 1 on any gate failure.
+ *
+ * Install as Husky pre-commit hook:
+ *   echo "npx gate-save" > .husky/pre-commit
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+/** Run a command, inheriting stdio so output is streamed to the terminal. */
+function run(cmd) {
+  return spawnSync(cmd, { shell: true, encoding: 'utf8', stdio: 'inherit' });
+}
+
+/** Run a command capturing stdout/stderr (no terminal output). */
+function capture(cmd) {
+  return spawnSync(cmd, { shell: true, encoding: 'utf8' });
+}
+
+function fail(msg) {
+  process.stderr.write(`\x1b[31m✖  ${msg}\x1b[0m\n`);
+  process.exit(1);
+}
+
+function info(msg) {
+  process.stdout.write(`\x1b[36mℹ  ${msg}\x1b[0m\n`);
+}
+
+function ok(msg) {
+  process.stdout.write(`\x1b[32m✔  ${msg}\x1b[0m\n`);
+}
+
+// ── staged file list ──────────────────────────────────────────────────────────
+
+const stagedResult = capture('git diff --cached --name-only --diff-filter=ACMR');
+if (stagedResult.status !== 0) {
+  fail(`Could not enumerate staged files:\n${stagedResult.stderr.trim()}`);
+}
+
+const CODE_EXTS = /\.(ts|tsx|mts|cts|js|mjs|cjs|jsx)$/;
+const VERSION_BUMP_FILES = /^(package\.json|package-lock\.json|yarn\.lock)$/;
+
+const allStaged = stagedResult.stdout
+  .split('\n')
+  .map((f) => f.trim())
+  .filter(Boolean);
+
+if (allStaged.length > 0 && allStaged.every((f) => VERSION_BUMP_FILES.test(f))) {
+  ok('Version bump commit detected — skipping gates.');
+  process.exit(0);
+}
+
+const codeFiles = allStaged.filter((f) => CODE_EXTS.test(f) && !f.startsWith('bin/'));
+
+// ── 1. lint-staged ────────────────────────────────────────────────────────────
+
+info('Running lint-staged…');
+
+const lintResult = run('npx lint-staged');
+if (lintResult.status !== 0) {
+  fail('lint-staged reported errors. Fix them and re-stage before committing.');
+}
+
+ok('lint-staged passed.');
+
+// ── 2. TODO scanner ──────────────────────────────────────────────────────────
+
+info('Scanning staged files for bare TODOs…');
+
+// A Jira-style ticket reference: one or more uppercase letters, a dash, and digits.
+const JIRA_REF_RE = /[A-Z]+-\d+/;
+// Matches any TODO annotation (case-insensitive), with optional owner parens.
+const TODO_LINE_RE = /TODO(?:\s*\([^)]*\))?\s*[:：]?\s+(.+)/i;
+
+const violations = [];
+
+for (const file of codeFiles) {
+  // Read the staged blob, not the working-tree file, to avoid false positives
+  // from unstaged edits made after the last `git add`.
+  const blobResult = capture(`git show :${file}`);
+  if (blobResult.status !== 0) continue;
+
+  const lines = blobResult.stdout.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const match = lines[i].match(TODO_LINE_RE);
+    if (match && !JIRA_REF_RE.test(lines[i])) {
+      violations.push({ file, line: i + 1, text: lines[i].trim() });
+    }
+  }
+}
+
+if (violations.length > 0) {
+  process.stderr.write(
+    '\x1b[31m✖  Bare TODOs detected — each TODO must carry a Jira ticket reference:\x1b[0m\n',
+  );
+
+  const byFile = violations.reduce((acc, v) => {
+    (acc[v.file] ??= []).push(v);
+    return acc;
+  }, {});
+
+  for (const [file, items] of Object.entries(byFile)) {
+    process.stderr.write(`\x1b[33m\n   ${file}\x1b[0m\n`);
+    items.forEach(({ line, text }) => {
+      process.stderr.write(`\x1b[90m     ${String(line).padStart(4)}  ${text}\x1b[0m\n`);
+    });
+  }
+
+  process.stderr.write(
+    '\x1b[90m\n   Example fix:  // TODO: refactor this FI-999\x1b[0m\n',
+  );
+  fail(`${violations.length} bare TODO(s) must be resolved before committing.`);
+}
+
+ok('No bare TODOs detected.');
+
+// ── 3. i18n sync ──────────────────────────────────────────────────────────────
+
+const pkgJsonPath = resolve(process.cwd(), 'package.json');
+if (existsSync(pkgJsonPath)) {
+  let rootPkg;
+  try { rootPkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8')); } catch { /* ignore */ }
+
+  if (rootPkg?.['fc-i18n']?.slug) {
+    info('Running i18n sync…');
+    const syncResult = run('npx gate-i18n-sync');
+    if (syncResult.status !== 0) {
+      fail('i18n sync failed. Fix the errors above or set SKIP_I18N_SYNC=1 to bypass.');
+    }
+    ok('i18n sync complete.');
+  }
+}
+
+process.exit(0);