langctl 0.2.0 → 0.3.0

package/dist/core/http.js

@@ -0,0 +1,121 @@
+import { CliError, ExitCode, httpError, networkError } from './errors.js';
+import { requireCredentials } from './config.js';
+import { detectCi, log } from './output.js';
+import { VERSION } from '../version.js';
+export const httpSettings = {
+    timeoutMs: Number(process.env.LANGCTL_TIMEOUT || 30) * 1000,
+    retries: 3,
+};
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+function userAgent() {
+    const ci = detectCi();
+    return `langctl/${VERSION} (node ${process.versions.node}; ${process.platform}${ci ? `; ci=${ci}` : ''})`;
+}
+export class ApiClient {
+    constructor(creds) {
+        this.creds = creds;
+    }
+    get baseUrl() {
+        return this.creds.apiUrl;
+    }
+    async request(method, path, opts = {}) {
+        const url = new URL(this.creds.apiUrl + path);
+        for (const [k, v] of Object.entries(opts.query ?? {})) {
+            if (v !== undefined && v !== '')
+                url.searchParams.set(k, String(v));
+        }
+        const headers = {
+            'X-API-Key': this.creds.apiKey,
+            'User-Agent': userAgent(),
+            Accept: 'application/json',
+        };
+        // Only declare a JSON body when there is one — Fastify rejects an empty body with this header
+        if (opts.body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        const idempotent = opts.idempotent ?? (method === 'GET');
+        const attempts = idempotent ? httpSettings.retries : 1;
+        for (let attempt = 1;; attempt++) {
+            const started = Date.now();
+            let res;
+            try {
+                res = await fetch(url, {
+                    method,
+                    headers,
+                    body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+                    signal: AbortSignal.timeout(httpSettings.timeoutMs),
+                });
+            }
+            catch (err) {
+                const mapped = networkError(err, this.creds.apiUrl, httpSettings.timeoutMs);
+                log.debug(`${method} ${url.pathname} → ${mapped.message} (${Date.now() - started}ms, attempt ${attempt}/${attempts})`);
+                if (attempt < attempts) {
+                    await sleep(backoff(attempt));
+                    continue;
+                }
+                throw mapped;
+            }
+            log.debug(`${method} ${url.pathname}${url.search} → ${res.status} (${Date.now() - started}ms)`);
+            const retryable = res.status === 429 || res.status === 502 || res.status === 503 || res.status === 504;
+            if (retryable && attempt < attempts) {
+                const retryAfter = Number(res.headers.get('retry-after'));
+                await sleep(Number.isFinite(retryAfter) && retryAfter > 0 ? Math.min(retryAfter, 30) * 1000 : backoff(attempt));
+                continue;
+            }
+            const text = await res.text();
+            let data = undefined;
+            if (text) {
+                try {
+                    data = JSON.parse(text);
+                }
+                catch {
+                    if (!res.ok)
+                        throw httpError(res.status, undefined, method, url.pathname);
+                    throw new CliError(`Unexpected non-JSON response from ${url.host} (${res.status}).`, ExitCode.Network, 'Is LANGCTL_API_URL pointing at the Langctl API (…/api/v1)?');
+                }
+            }
+            if (!res.ok) {
+                const d = data;
+                throw httpError(res.status, d?.error || d?.message, method, url.pathname);
+            }
+            return data;
+        }
+    }
+    get(path, query) {
+        return this.request('GET', path, { query });
+    }
+    post(path, body, idempotent = false) {
+        return this.request('POST', path, { body, idempotent });
+    }
+    patch(path, body) {
+        return this.request('PATCH', path, { body, idempotent: true });
+    }
+    delete(path) {
+        return this.request('DELETE', path, { idempotent: true });
+    }
+}
+function backoff(attempt) {
+    return Math.min(8000, 500 * 2 ** (attempt - 1)) + Math.floor(Math.random() * 250);
+}
+/** Look up which org a key belongs to (and its scopes). Returns null if the key is invalid/revoked. */
+export async function validateKey(api, apiKey) {
+    const res = await api.request('POST', '/api-keys/validate', { body: { apiKey }, idempotent: true });
+    return res.valid && res.organizationId ? { organizationId: res.organizationId, scopes: res.scopes ?? [] } : null;
+}
+let cached = null;
+export async function getSession() {
+    if (cached)
+        return cached;
+    const creds = requireCredentials();
+    const api = new ApiClient(creds);
+    if (creds.organizationId) {
+        cached = { api, orgId: creds.organizationId, creds };
+        return cached;
+    }
+    // Env/flag key: resolve the org from the key itself, so CI needs no config file
+    const info = await validateKey(api, creds.apiKey);
+    if (!info) {
+        throw new CliError(`The API key from ${creds.source === 'env' ? 'LANGCTL_API_KEY' : '--api-key'} is invalid or revoked.`, ExitCode.Auth, 'Create a new key at https://app.langctl.com/organization/api-keys.');
+    }
+    cached = { api, orgId: info.organizationId, creds, scopes: info.scopes };
+    return cached;
+}

package/dist/core/output.js

@@ -0,0 +1,96 @@
+import chalk from 'chalk';
+/**
+ * Process-wide output settings, set once from global flags in index.ts.
+ *
+ * Contract: command *results* go to stdout (and only JSON when --json is set);
+ * progress, warnings and errors go to stderr. That keeps `langctl ... --json | jq`
+ * and `$(langctl ...)` reliable in CI.
+ */
+export const runtime = {
+    json: false,
+    quiet: false,
+    verbose: false,
+    yes: false,
+};
+const ciEnv = ['CI', 'GITHUB_ACTIONS', 'GITLAB_CI', 'BUILDKITE', 'CIRCLECI', 'JENKINS_URL', 'TF_BUILD', 'BITBUCKET_BUILD_NUMBER'];
+export function detectCi() {
+    for (const name of ciEnv) {
+        const value = process.env[name];
+        if (value && value !== 'false' && value !== '0')
+            return name === 'CI' ? 'ci' : name.toLowerCase();
+    }
+    return null;
+}
+/** True only when a human is at an interactive terminal (prompts and spinners allowed). */
+export function isInteractive() {
+    return Boolean(process.stdin.isTTY && process.stderr.isTTY) && !detectCi() && !runtime.json;
+}
+const write = (stream, line) => stream.write(line + '\n');
+export const log = {
+    /** Human-readable result line (stdout). Suppressed in --json mode — print JSON with `printJson` instead. */
+    out(line = '') {
+        if (!runtime.json)
+            write(process.stdout, line);
+    },
+    info(line) {
+        if (!runtime.quiet && !runtime.json)
+            write(process.stderr, line);
+    },
+    success(line) {
+        if (!runtime.quiet && !runtime.json)
+            write(process.stderr, `${chalk.green('✔')} ${line}`);
+    },
+    warn(line) {
+        write(process.stderr, `${chalk.yellow('warning:')} ${line}`);
+    },
+    error(line, hint) {
+        write(process.stderr, `${chalk.red('error:')} ${line}`);
+        if (hint)
+            write(process.stderr, `${chalk.dim('hint:')} ${hint}`);
+    },
+    debug(line) {
+        if (runtime.verbose)
+            write(process.stderr, chalk.dim(`[debug] ${line}`));
+    },
+};
+export function printJson(data) {
+    process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+}
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+/**
+ * Progress indicator that only animates for humans at a terminal; elsewhere (CI, pipes,
+ * --json, --quiet) it is a no-op. Deliberately not `ora`: ora touches stdin/cursor state and
+ * froze the CLI under emulated terminals (`script`, `docker -t`, some CI runners). This
+ * writes to stderr only, and its timer is unref'd so it can never keep the process alive.
+ */
+export function spinner(text) {
+    if (!isInteractive() || runtime.quiet || runtime.verbose)
+        return { text, stop() { } };
+    let i = 0;
+    const state = { text };
+    const render = () => process.stderr.write(`\r\x1b[2K${chalk.cyan(FRAMES[i++ % FRAMES.length])} ${state.text}`);
+    render();
+    const timer = setInterval(render, 80);
+    timer.unref();
+    return {
+        get text() { return state.text; },
+        set text(t) { state.text = t; },
+        stop() {
+            clearInterval(timer);
+            process.stderr.write('\r\x1b[2K');
+        },
+    };
+}
+/** Minimal aligned table for human output. */
+export function table(rows, header) {
+    const all = header ? [header, ...rows] : rows;
+    const widths = all[0]?.map((_, i) => Math.max(...all.map(r => stripAnsi(r[i] ?? '').length))) ?? [];
+    const fmt = (r) => r.map((c, i) => (i === r.length - 1 ? c : c + ' '.repeat(widths[i] - stripAnsi(c).length))).join('  ');
+    if (header)
+        log.out(chalk.bold(fmt(header)));
+    rows.forEach(r => log.out(fmt(r)));
+}
+function stripAnsi(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/\x1b\[[0-9;]*m/g, '');
+}

package/dist/core/project.js

@@ -0,0 +1,58 @@
+import { CliError, ExitCode, notFoundError, usageError } from './errors.js';
+import { loadProjectConfig } from './config.js';
+/** Project slug from the argument, else langctl.json, else a usage error. */
+export function projectSlugFrom(arg) {
+    if (arg)
+        return arg;
+    const loaded = loadProjectConfig();
+    if (loaded?.config.project)
+        return loaded.config.project;
+    throw usageError('No project given.', 'Pass a project slug, or add "project" to langctl.json (see "langctl init"). List projects with "langctl projects list".');
+}
+export async function getProject(session, slug) {
+    try {
+        return await session.api.get(`/orgs/${session.orgId}/projects/by-slug/${encodeURIComponent(slug)}`);
+    }
+    catch (err) {
+        if (err instanceof CliError && err.exitCode === ExitCode.NotFound) {
+            const projects = await session.api.get(`/orgs/${session.orgId}/projects`).catch(() => []);
+            const available = projects.map(p => p.slug);
+            throw notFoundError(`Project "${slug}" not found.`, available.length ? `Available projects: ${available.join(', ')}` : 'This organization has no projects yet — create one with "langctl projects create".');
+        }
+        throw err;
+    }
+}
+export function assertLanguages(project, languages) {
+    const missing = languages.filter(l => !project.languages.includes(l));
+    if (missing.length) {
+        throw usageError(`Language${missing.length > 1 ? 's' : ''} ${missing.join(', ')} not in project "${project.slug}".`, `Project languages: ${project.languages.join(', ')}. Add one with "langctl projects add-language ${project.slug} <code>".`);
+    }
+}
+export async function findKey(session, project, keyName) {
+    const res = await session.api.get(`/orgs/${session.orgId}/projects/${project.id}/keys`, { key: keyName, pageSize: 1 });
+    return res.data.find(k => k.key === keyName) ?? null;
+}
+export async function requireKey(session, project, keyName) {
+    const key = await findKey(session, project, keyName);
+    if (!key)
+        throw notFoundError(`Key "${keyName}" not found in project "${project.slug}".`, `Search with "langctl keys list ${project.slug} --search <text>".`);
+    return key;
+}
+/** Fetch every key page by page (the API caps pages at 100). */
+export async function listAllKeys(session, project, filters = {}) {
+    const out = [];
+    for (let page = 1;; page++) {
+        const res = await session.api.get(`/orgs/${session.orgId}/projects/${project.id}/keys`, {
+            page,
+            pageSize: 100,
+            sortBy: 'key',
+            sortOrder: 'asc',
+            module: filters.module,
+            search: filters.search,
+            published: filters.published === undefined ? undefined : String(filters.published),
+        });
+        out.push(...res.data);
+        if (page >= res.pagination.totalPages)
+            return out;
+    }
+}

package/dist/core/prompts.js

@@ -0,0 +1,56 @@
+import { createInterface } from 'readline';
+import { Writable } from 'stream';
+import { isInteractive, runtime } from './output.js';
+import { usageError } from './errors.js';
+/**
+ * Tiny prompts on node:readline (replaces inquirer). They are only ever shown at an
+ * interactive terminal; in CI a missing answer is a usage error, never a hang.
+ */
+function ask(question, { hidden = false } = {}) {
+    let muted = false;
+    const output = new Writable({
+        write(chunk, _enc, cb) {
+            if (!muted)
+                process.stderr.write(chunk);
+            cb();
+        },
+    });
+    const rl = createInterface({ input: process.stdin, output, terminal: true });
+    return new Promise((resolve, reject) => {
+        rl.question(question, answer => {
+            rl.close();
+            if (hidden)
+                process.stderr.write('\n');
+            resolve(answer.trim());
+        });
+        rl.on('SIGINT', () => { rl.close(); process.stderr.write('\n'); reject(usageError('Cancelled.')); });
+        muted = hidden;
+    });
+}
+export async function input(question, fallback) {
+    const answer = await ask(`${question}${fallback ? ` (${fallback})` : ''}: `);
+    return answer || fallback || '';
+}
+export async function password(question) {
+    return ask(`${question}: `, { hidden: true });
+}
+/**
+ * Ask before something destructive. `--yes` skips the question; without a TTY and
+ * without `--yes` we refuse instead of guessing.
+ */
+export async function confirm(question, flagName = '--yes') {
+    if (runtime.yes)
+        return true;
+    if (!isInteractive()) {
+        throw usageError(`Refusing to ${question.replace(/\?$/, '').toLowerCase()} without confirmation.`, `Re-run with ${flagName} to confirm in non-interactive environments.`);
+    }
+    const answer = (await ask(`${question} [y/N] `)).toLowerCase();
+    return answer === 'y' || answer === 'yes';
+}
+/** Read all of stdin (for `auth --stdin`). */
+export async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf-8');
+}

package/dist/formats/index.js

@@ -0,0 +1,285 @@
+import { usageError } from '../core/errors.js';
+const PLACEHOLDER = /\{\{\s*([A-Za-z0-9_.-]+)\s*\}\}/g;
+/** Unique placeholder names in order of first appearance — the same name always gets the same position. */
+function placeholderOrder(text) {
+    const names = [];
+    for (const m of text.matchAll(PLACEHOLDER))
+        if (!names.includes(m[1]))
+            names.push(m[1]);
+    return names;
+}
+function toPositional(text, suffix) {
+    const names = placeholderOrder(text);
+    if (names.length === 0)
+        return text;
+    // A literal % must be doubled once the string is used as a format string
+    const escaped = text.replace(/%/g, '%%');
+    return escaped.replace(PLACEHOLDER, (_m, name) => `%${names.indexOf(name) + 1}$${suffix}`);
+}
+function fromPositional(text, suffix) {
+    const re = new RegExp(`%(\\d+)\\$${suffix.replace('@', '@')}`, 'g');
+    if (!re.test(text))
+        return text;
+    return text.replace(re, (_m, n) => `{{${n}}}`).replace(/%%/g, '%');
+}
+function sortEntries(entries) {
+    return [...entries].sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+}
+/** Rename keys for platforms with stricter identifier rules; fail loudly on collisions instead of silently dropping strings. */
+function renameKeys(entries, rename, platform) {
+    const seen = new Map();
+    const collisions = [];
+    const out = entries.map(e => {
+        const id = rename(e.key);
+        const prev = seen.get(id);
+        if (prev !== undefined && prev !== e.key)
+            collisions.push(`"${prev}" and "${e.key}" both become "${id}"`);
+        seen.set(id, e.key);
+        return { ...e, id };
+    });
+    if (collisions.length) {
+        throw usageError(`Keys collide when converted to ${platform} names:\n  ${collisions.join('\n  ')}`, 'Rename one of the keys, or export with a JSON format.');
+    }
+    return out;
+}
+// ── Flat JSON ───────────────────────────────────────────────────
+function flatten(obj, prefix = '', out = {}, bad = []) {
+    if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+        throw usageError('Expected a JSON object of translations.');
+    }
+    for (const [k, v] of Object.entries(obj)) {
+        const key = prefix ? `${prefix}.${k}` : k;
+        if (typeof v === 'string')
+            out[key] = v;
+        else if (v && typeof v === 'object' && !Array.isArray(v))
+            flatten(v, key, out, bad);
+        else
+            bad.push(`${key} (${Array.isArray(v) ? 'array' : v === null ? 'null' : typeof v})`);
+    }
+    if (!prefix && bad.length) {
+        throw usageError(`Only string values can be imported. Not strings:\n  ${bad.slice(0, 10).join('\n  ')}${bad.length > 10 ? `\n  …and ${bad.length - 10} more` : ''}`);
+    }
+    return out;
+}
+function parseJson(content) {
+    try {
+        return JSON.parse(content.replace(/^\uFEFF/, ''));
+    }
+    catch (e) {
+        throw usageError(`Invalid JSON: ${e.message}`);
+    }
+}
+const flatJson = {
+    id: 'json',
+    aliases: ['flat-json', 'i18n-json', 'i18next'],
+    label: 'Flat JSON  { "home.title": "Welcome" }',
+    defaultOutput: 'locales/{lang}.json',
+    serialize(entries) {
+        const obj = {};
+        for (const e of sortEntries(entries))
+            obj[e.key] = e.value;
+        return JSON.stringify(obj, null, 2) + '\n';
+    },
+    parse: content => flatten(parseJson(content)),
+};
+// ── Nested JSON ─────────────────────────────────────────────────
+const nestedJson = {
+    id: 'nested-json',
+    aliases: ['json-nested'],
+    label: 'Nested JSON  { "home": { "title": "Welcome" } }',
+    defaultOutput: 'locales/{lang}.json',
+    serialize(entries) {
+        const root = {};
+        const conflicts = [];
+        for (const e of sortEntries(entries)) {
+            const parts = e.key.split('.');
+            let node = root;
+            let ok = true;
+            for (let i = 0; i < parts.length - 1; i++) {
+                const next = node[parts[i]];
+                if (typeof next === 'string') {
+                    conflicts.push(`"${e.key}" is nested under "${parts.slice(0, i + 1).join('.')}", which is also a string`);
+                    ok = false;
+                    break;
+                }
+                node = next ?? (node[parts[i]] = {});
+            }
+            const leaf = parts[parts.length - 1];
+            if (!ok)
+                continue;
+            if (node[leaf] !== undefined && typeof node[leaf] === 'object') {
+                conflicts.push(`"${e.key}" is a string but also has nested keys`);
+                continue;
+            }
+            node[leaf] = e.value;
+        }
+        if (conflicts.length) {
+            throw usageError(`These keys can't be represented as nested JSON:\n  ${conflicts.join('\n  ')}`, 'Use --format json (flat) or rename the keys.');
+        }
+        return JSON.stringify(root, null, 2) + '\n';
+    },
+    parse: content => flatten(parseJson(content)),
+};
+// ── Android strings.xml ─────────────────────────────────────────
+const androidName = (key) => {
+    const n = key.replace(/[^A-Za-z0-9_]/g, '_');
+    return /^[0-9]/.test(n) ? `_${n}` : n;
+};
+function escapeAndroid(text) {
+    let s = text
+        .replace(/\\/g, '\\\\')
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/'/g, "\\'")
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\t/g, '\\t');
+    if (/^[@?]/.test(s))
+        s = `\\${s}`;
+    return s;
+}
+function unescapeAndroid(text) {
+    return text
+        .replace(/^\\([@?])/, '$1')
+        .replace(/\\n/g, '\n')
+        .replace(/\\t/g, '\t')
+        .replace(/\\'/g, "'")
+        .replace(/\\"/g, '"')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, '&')
+        .replace(/\\\\/g, '\\');
+}
+const escapeXmlComment = (s) => s.replace(/--/g, '- -');
+const android = {
+    id: 'android',
+    aliases: ['android-xml', 'xml'],
+    label: 'Android strings.xml (res/values-xx/)',
+    defaultOutput: 'res/{android}/strings.xml',
+    serialize(entries) {
+        const lines = ['<?xml version="1.0" encoding="utf-8"?>', '<resources>'];
+        for (const e of renameKeys(sortEntries(entries), androidName, 'Android resource')) {
+            if (e.description)
+                lines.push(`    <!-- ${escapeXmlComment(e.description)} -->`);
+            lines.push(`    <string name="${e.id}">${escapeAndroid(toPositional(e.value, 's'))}</string>`);
+        }
+        lines.push('</resources>');
+        return lines.join('\n') + '\n';
+    },
+    parse(content) {
+        const out = {};
+        const re = /<string\s+name="([^"]+)"[^>]*>([\s\S]*?)<\/string>/g;
+        for (const m of content.matchAll(re)) {
+            const raw = m[2].replace(/^<!\[CDATA\[([\s\S]*)\]\]>$/, '$1');
+            out[m[1]] = fromPositional(unescapeAndroid(raw), 's');
+        }
+        if (!/<resources/.test(content))
+            throw usageError('Not an Android strings.xml file (no <resources> element).');
+        return out;
+    },
+};
+// ── iOS Localizable.strings ─────────────────────────────────────
+const escapeStrings = (s) => s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t');
+const unescapeStrings = (s) => s.replace(/\\(["\\nrt])/g, (_m, c) => ({ n: '\n', r: '\r', t: '\t', '"': '"', '\\': '\\' }[c] ?? c));
+const ios = {
+    id: 'ios',
+    aliases: ['ios-strings', 'strings'],
+    label: 'iOS Localizable.strings (xx.lproj/)',
+    defaultOutput: '{lang}.lproj/Localizable.strings',
+    serialize(entries) {
+        const blocks = sortEntries(entries).map(e => `${e.description ? `/* ${e.description.replace(/\*\//g, '* /')} */\n` : ''}"${escapeStrings(e.key)}" = "${escapeStrings(toPositional(e.value, '@'))}";`);
+        return blocks.join('\n') + (blocks.length ? '\n' : '');
+    },
+    parse(content) {
+        const out = {};
+        const body = content.replace(/^\uFEFF/, '').replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
+        const re = /"((?:[^"\\]|\\.)*)"\s*=\s*"((?:[^"\\]|\\.)*)"\s*;/g;
+        for (const m of body.matchAll(re))
+            out[unescapeStrings(m[1])] = fromPositional(unescapeStrings(m[2]), '@');
+        return out;
+    },
+};
+// ── Flutter ARB ─────────────────────────────────────────────────
+/** ARB message ids must be valid Dart identifiers: "auth.login.title" → "authLoginTitle". */
+function arbName(key) {
+    const parts = key.split(/[^A-Za-z0-9]+/).filter(Boolean);
+    const id = parts.map((p, i) => (i === 0 ? p.charAt(0).toLowerCase() + p.slice(1) : p.charAt(0).toUpperCase() + p.slice(1))).join('');
+    return /^[A-Za-z]/.test(id) ? id : `k${id}`;
+}
+const arb = {
+    id: 'arb',
+    aliases: ['flutter', 'flutter-arb'],
+    label: 'Flutter ARB (lib/l10n/app_xx.arb)',
+    defaultOutput: 'lib/l10n/app_{lang_}.arb',
+    serialize(entries, lang) {
+        const obj = { '@@locale': lang.replace('-', '_') };
+        for (const e of renameKeys(sortEntries(entries), arbName, 'Flutter ARB')) {
+            const names = placeholderOrder(e.value);
+            obj[e.id] = e.value.replace(PLACEHOLDER, '{$1}');
+            const meta = {};
+            if (e.description)
+                meta.description = e.description;
+            if (names.length)
+                meta.placeholders = Object.fromEntries(names.map(n => [n, { type: 'String' }]));
+            if (Object.keys(meta).length)
+                obj[`@${e.id}`] = meta;
+        }
+        return JSON.stringify(obj, null, 2) + '\n';
+    },
+    parse(content) {
+        const obj = parseJson(content);
+        const out = {};
+        for (const [k, v] of Object.entries(obj)) {
+            if (k.startsWith('@'))
+                continue;
+            if (typeof v !== 'string')
+                throw usageError(`ARB entry "${k}" is not a string.`);
+            // Simple {name} placeholders → {{name}}; ICU blocks like {count, plural, …} are left as-is
+            out[k] = v.replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, '{{$1}}');
+        }
+        return out;
+    },
+};
+// ── Registry ────────────────────────────────────────────────────
+export const FORMATS = [flatJson, nestedJson, android, ios, arb];
+export function getFormat(name) {
+    const wanted = (name || 'json').toLowerCase();
+    const found = FORMATS.find(f => f.id === wanted || f.aliases.includes(wanted));
+    if (!found) {
+        throw usageError(`Unknown format "${name}".`, `Supported: ${FORMATS.map(f => f.id).join(', ')} (see "langctl formats").`);
+    }
+    return found;
+}
+/** Guess a format from a file name (used by import/push when --format is omitted). */
+export function formatFromPath(path) {
+    const lower = path.toLowerCase();
+    if (lower.endsWith('.arb'))
+        return arb;
+    if (lower.endsWith('.xml'))
+        return android;
+    if (lower.endsWith('.strings'))
+        return ios;
+    if (lower.endsWith('.json'))
+        return flatJson; // flat and nested JSON both parse to the same thing
+    throw usageError(`Can't tell the format of "${path}" from its extension.`, 'Pass --format.');
+}
+/**
+ * Expand a path template for one language.
+ *   {lang}     pt-BR
+ *   {lang_}    pt_BR          (Flutter / gettext style)
+ *   {android}  values / values-pt-rBR   (default language → "values")
+ */
+export function expandTemplate(template, lang, defaultLang) {
+    const [base, region] = lang.split('-');
+    const androidDir = lang === defaultLang ? 'values' : `values-${base}${region ? `-r${region.toUpperCase()}` : ''}`;
+    return template
+        .replace(/\{lang_\}/g, lang.replace(/-/g, '_'))
+        .replace(/\{lang\}/g, lang)
+        .replace(/\{android\}/g, androidDir);
+}
+export function templateHasLanguage(template) {
+    return /\{(lang|lang_|android)\}/.test(template);
+}