@chesterbrains/translify-cli 0.0.0-stage → 0.1.0

package/dist/config.js

@@ -0,0 +1,83 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { CliError, EXIT } from './errors.js';
+// Same shapes the BE validates, so a bad value fails here with a field path instead of as a 4xx.
+const NAMESPACE = /^[a-z0-9-]+$/;
+const LOCALE = /^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
+const fileRule = z
+    .object({
+    pattern: z
+        .string()
+        .min(1)
+        .refine((value) => value.includes('{locale}'), { message: 'must contain {locale}' })
+        .refine((value) => value.split('{locale}').length <= 2 && value.split('{namespace}').length <= 2, {
+        message: 'may use each of {locale} and {namespace} only once',
+    }),
+    format: z.enum(['json', 'xliff', 'arb']),
+    namespace: z.string().regex(NAMESPACE, 'must be lowercase kebab-case').max(64).optional(),
+    jsonStyle: z.enum(['nested', 'flat']).optional(),
+})
+    .strict()
+    .superRefine((rule, ctx) => {
+    const hasPlaceholder = rule.pattern.includes('{namespace}');
+    if (rule.format === 'arb' && rule.namespace === undefined) {
+        ctx.addIssue({ code: 'custom', path: ['namespace'], message: 'ARB files need a fixed namespace' });
+    }
+    else if (!hasPlaceholder && rule.namespace === undefined) {
+        ctx.addIssue({ code: 'custom', path: ['namespace'], message: 'needed when the pattern has no {namespace}' });
+    }
+    if (rule.jsonStyle !== undefined && rule.format !== 'json') {
+        ctx.addIssue({ code: 'custom', path: ['jsonStyle'], message: 'only applies to format "json"' });
+    }
+})
+    .transform((rule) => (rule.format === 'json' ? { ...rule, jsonStyle: rule.jsonStyle ?? 'nested' } : rule));
+const configSchema = z
+    .object({
+    $schema: z.string().optional(),
+    apiUrl: z.url(),
+    files: z.array(fileRule),
+    // filesystem locale -> Translify code; the target must already be a valid Translify locale
+    locales: z.record(z.string(), z.string().regex(LOCALE, 'must be a locale code such as en-US')).default({}),
+})
+    .strict()
+    .superRefine((config, ctx) => {
+    // The map must be a bijection that cannot chain, or pull and push disagree on a cell's file.
+    const seen = new Map();
+    for (const [disk, code] of Object.entries(config.locales)) {
+        const first = seen.get(code);
+        if (first !== undefined) {
+            ctx.addIssue({ code: 'custom', path: ['locales', disk], message: `maps to ${code}, already the target of ${first}` });
+        }
+        seen.set(code, disk);
+        if (code !== disk && Object.hasOwn(config.locales, code)) {
+            ctx.addIssue({ code: 'custom', path: ['locales', disk], message: `target ${code} is itself a mapped disk locale` });
+        }
+    }
+});
+export async function loadConfig(cwd) {
+    let raw;
+    try {
+        raw = await readFile(join(cwd, 'translify.json'), 'utf8');
+    }
+    catch {
+        throw new CliError(EXIT.failed, 'No translify.json here. Run `translify init` to create one.');
+    }
+    let json;
+    try {
+        json = JSON.parse(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw);
+    }
+    catch {
+        throw new CliError(EXIT.failed, 'translify.json is not valid JSON.');
+    }
+    if (typeof json === 'object' && json !== null && Object.keys(json).some((key) => /key|secret|token/i.test(key))) {
+        throw new CliError(EXIT.failed, 'Never put a key in translify.json — set TRANSLIFY_SECRET_KEY or run `translify login`.');
+    }
+    const parsed = configSchema.safeParse(json);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        throw new CliError(EXIT.failed, `translify.json: ${issue?.path.join('.')} ${issue?.message}`);
+    }
+    const { apiUrl, files, locales } = parsed.data;
+    return { apiUrl, files, locales };
+}

package/dist/confirm.js

@@ -0,0 +1,12 @@
+import { confirm } from '@inquirer/prompts';
+/** Asks on stderr, so stdout stays clean for `--json`. Defaults to no; Ctrl+C counts as no. */
+export const askConfirm = async (message) => {
+    try {
+        return await confirm({ message, default: false }, { output: process.stderr });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'ExitPromptError')
+            return false;
+        throw error;
+    }
+};

package/dist/credentials.js

@@ -0,0 +1,53 @@
+import { chmod, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join } from 'node:path';
+import { CliError, EXIT } from './errors.js';
+export function credentialsPath(env = process.env) {
+    // Empty or relative values would resolve against the cwd (often a repo); ignore them, as the XDG spec says.
+    const absolute = (value) => value !== undefined && isAbsolute(value) ? value : undefined;
+    const appData = absolute(env.APPDATA);
+    if (process.platform === 'win32' && appData !== undefined)
+        return join(appData, 'translify', 'credentials');
+    return join(absolute(env.XDG_CONFIG_HOME) ?? join(homedir(), '.config'), 'translify', 'credentials');
+}
+// Messages never echo the value: a mistyped key is still a secret.
+export const assertSecret = (key) => {
+    if (key.startsWith('pk_')) {
+        throw new CliError(EXIT.auth, 'That is a publishable key: pk_ keys are for delivery. Create a secret (sk_) key in Translify.');
+    }
+    if (!key.startsWith('sk_'))
+        throw new CliError(EXIT.auth, 'Not a Translify secret key (expected sk_...).');
+    return key;
+};
+export async function resolveKey(env = process.env) {
+    const fromEnv = env.TRANSLIFY_SECRET_KEY?.trim();
+    if (fromEnv)
+        return assertSecret(fromEnv);
+    let stored;
+    try {
+        stored = (await readFile(credentialsPath(env), 'utf8')).trim();
+    }
+    catch {
+        throw new CliError(EXIT.auth, 'No key. Set TRANSLIFY_SECRET_KEY or run `translify login`.');
+    }
+    if (stored === '')
+        throw new CliError(EXIT.auth, 'No key. Set TRANSLIFY_SECRET_KEY or run `translify login`.');
+    return assertSecret(stored);
+}
+export async function saveKey(key, env = process.env) {
+    const path = credentialsPath(env);
+    const secret = assertSecret(key.trim());
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await chmod(dirname(path), 0o700);
+    // Temp file created 0600, then renamed over the target: never world-readable, never truncated.
+    const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        await writeFile(temp, `${secret}\n`, { mode: 0o600, flag: 'wx' });
+        await rename(temp, path);
+    }
+    catch (error) {
+        await rm(temp, { force: true });
+        throw error;
+    }
+    return path;
+}

package/dist/errors.js

@@ -0,0 +1,12 @@
+// Minimal for Task 6.2; Task 6.3 owns this file and extends it.
+export const EXIT = { ok: 0, failed: 1, auth: 2, quota: 3, network: 4 };
+/** Every expected failure. `index.ts` prints `message` and exits with `exitCode`; anything else is a bug. */
+export class CliError extends Error {
+    exitCode;
+    details;
+    constructor(exitCode, message, details) {
+        super(message);
+        this.exitCode = exitCode;
+        this.details = details;
+    }
+}

package/dist/http.js

@@ -0,0 +1,178 @@
+import { CliError, EXIT } from './errors.js';
+import { USER_AGENT } from './version.js';
+const NOT_JSON = Symbol('notJson');
+const MAX_RETRIES = 3;
+const MAX_WAIT_MS = 60_000;
+/** One request, not the whole command: a stalled server must not hang CI forever. */
+const REQUEST_TIMEOUT_MS = 180_000;
+const UPGRADE = 'npm i -g @chesterbrains/translify-cli@latest, or for the standalone binary: curl -fsSL https://github.com/chesterbrains/translify-cli/releases/latest/download/install.sh | sh';
+const sleep = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Exit code by the body's `code` first; the status only decides for a code we do not know. */
+const CODE_EXIT = {
+    VALIDATION_FAILED: EXIT.failed,
+    LOCALE_NOT_FOUND: EXIT.failed,
+    NAMESPACE_NOT_FOUND: EXIT.failed,
+    JSON_STYLE_REQUIRES_JSON: EXIT.failed,
+    BAD_REQUEST: EXIT.failed,
+    ENVIRONMENT_NOT_FOUND: EXIT.failed,
+    ENVIRONMENT_ARCHIVED: EXIT.failed,
+    PROJECT_ARCHIVED: EXIT.failed,
+    SECRET_KEY_IN_URL: EXIT.failed,
+    KEY_INVALID: EXIT.auth,
+    KEY_REVOKED: EXIT.auth,
+    KEY_WRONG_KIND: EXIT.auth,
+    SCOPE_MISSING: EXIT.auth,
+    QUOTA_EXCEEDED: EXIT.quota,
+    INTERNAL_ERROR: EXIT.network,
+    DATABASE_ERROR: EXIT.network,
+    PUSH_TOO_LARGE: EXIT.network,
+    CLI_TOO_OLD: EXIT.network,
+    ORPHANS_CHANGED: EXIT.failed,
+    TRANSACTION_CONFLICT: EXIT.network,
+    RATE_LIMITED: EXIT.network,
+};
+const exitFor = (status, code) => {
+    const byCode = code === undefined ? undefined : CODE_EXIT[code];
+    if (byCode !== undefined)
+        return byCode;
+    if (status === 401 || status === 403)
+        return EXIT.auth;
+    if (status === 402)
+        return EXIT.quota;
+    if (status === 413 || status === 426 || status === 429 || status >= 500)
+        return EXIT.network;
+    return EXIT.failed;
+};
+const list = (value) => (Array.isArray(value) ? value.map(String).join(', ') : String(value));
+const validationLines = (errors) => {
+    if (!Array.isArray(errors) || errors.length === 0)
+        return '';
+    return errors
+        .map((raw) => {
+        const e = typeof raw === 'object' && raw !== null ? raw : {};
+        const where = `${String(e.file ?? '?')}${e.line === undefined ? '' : `:${String(e.line)}`}`;
+        return `${where}${e.key === undefined ? '' : ` ${String(e.key)}`}: ${String(e.reason ?? 'invalid')}`;
+    })
+        .join('\n');
+};
+const describeBody = (status, body) => {
+    const text = Array.isArray(body.message) ? body.message.join('; ') : (body.message ?? '');
+    switch (body.code) {
+        case 'KEY_INVALID':
+            return 'The key was not recognised. Check TRANSLIFY_SECRET_KEY.';
+        case 'KEY_REVOKED':
+            return 'This key was revoked. Create a new secret key in Translify.';
+        case 'KEY_WRONG_KIND':
+            return 'This is not a secret key. The CLI needs an sk_ key.';
+        case 'SCOPE_MISSING':
+            return `This key lacks the ${String(body.required)} scope. Create a key that has it.`;
+        case 'QUOTA_EXCEEDED':
+            return `Plan limit reached for ${String(body.dimension)}: ${String(body.current)} of ${String(body.limit)} used.`;
+        case 'PUSH_TOO_LARGE':
+            return `Push too large (${String(body.entries ?? body.bytes)} over the limit of ${String(body.limit)}). Split it with --namespace.`;
+        case 'CLI_TOO_OLD':
+            return `This CLI is too old; ${String(body.minimum)} or newer is required. Upgrade: ${UPGRADE}`;
+        case 'VALIDATION_FAILED': {
+            const lines = validationLines(body.errors);
+            return lines === '' ? text || 'The push was rejected; nothing was written.' : `The push was rejected; nothing was written.\n${lines}`;
+        }
+        case 'LOCALE_NOT_FOUND':
+            return `Unknown locale(s): ${list(body.locales)}. They are not enabled in this project.`;
+        case 'NAMESPACE_NOT_FOUND':
+            return `Unknown namespace(s): ${list(body.namespaces)}.`;
+        case 'ORPHANS_CHANGED':
+            return 'The orphans changed since the dry run (keys were added, removed or published meanwhile). Nothing was written. Run translify push --prune again to review the new list.';
+        case 'TRANSACTION_CONFLICT':
+            return 'The server hit a transaction conflict. Try again.';
+        case 'RATE_LIMITED':
+            return 'Rate limited by the server; gave up after retries. Try again shortly.';
+        default:
+            if (status >= 500)
+                return `Translify server error (${status}). Try again shortly.`;
+            if (status === 429)
+                return 'Rate limited by the server; gave up after retries. Try again shortly.';
+            return text || `HTTP ${status}${body.code === undefined ? '' : ` ${body.code}`}`;
+    }
+};
+const explain = (status, body) => new CliError(exitFor(status, body.code), describeBody(status, body), body);
+/** Retry-After is delta-seconds or an HTTP date; anything else falls back to exponential backoff. Capped. */
+export const retryDelayMs = (header, attempt, now = Date.now()) => {
+    let ms = 2 ** attempt * 1000;
+    if (header !== null && header.trim() !== '') {
+        const seconds = Number(header);
+        if (Number.isFinite(seconds) && seconds >= 0)
+            ms = seconds * 1000;
+        else {
+            const date = Date.parse(header);
+            if (!Number.isNaN(date))
+                ms = Math.max(0, date - now);
+        }
+    }
+    return Math.min(ms, MAX_WAIT_MS);
+};
+const safeJson = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { message: text.slice(0, 200), [NOT_JSON]: true };
+    }
+};
+export class Api {
+    apiUrl;
+    key;
+    fetchImpl;
+    constructor(apiUrl, key, fetchImpl = fetch) {
+        this.apiUrl = apiUrl;
+        this.key = key;
+        this.fetchImpl = fetchImpl;
+    }
+    async get(path, query = {}) {
+        const search = new URLSearchParams(query).toString();
+        return this.send(`${path}${search ? `?${search}` : ''}`, { method: 'GET' });
+    }
+    async post(path, body) {
+        return body instanceof FormData
+            ? this.send(path, { method: 'POST', body })
+            : this.send(path, {
+                method: 'POST',
+                body: JSON.stringify(body),
+                headers: { 'content-type': 'application/json' },
+            });
+    }
+    async send(path, init) {
+        const url = `${this.apiUrl.replace(/\/$/, '')}${path}`;
+        const headers = {
+            ...init.headers,
+            authorization: `Bearer ${this.key}`,
+            'user-agent': USER_AGENT,
+            accept: 'application/json',
+        };
+        for (let attempt = 0;; attempt += 1) {
+            let response;
+            try {
+                response = await this.fetchImpl(url, { ...init, headers, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+            }
+            catch (error) {
+                if (error instanceof Error && error.name === 'TimeoutError') {
+                    throw new CliError(EXIT.network, `Request to ${this.apiUrl} timed out after ${REQUEST_TIMEOUT_MS / 1000}s. Try again, or split the push with --namespace.`);
+                }
+                // The cause is dropped on purpose: it can carry the request URL or headers.
+                throw new CliError(EXIT.network, `Could not reach ${this.apiUrl}. Check apiUrl and your connection.`);
+            }
+            if (response.status === 429 && attempt < MAX_RETRIES) {
+                await sleep(retryDelayMs(response.headers.get('retry-after'), attempt));
+                continue;
+            }
+            const text = await response.text();
+            const body = text === '' ? {} : safeJson(text);
+            if (response.ok) {
+                if (typeof body === 'object' && body !== null && NOT_JSON in body) {
+                    throw new CliError(EXIT.network, `Unexpected non-JSON response from ${this.apiUrl}; check apiUrl in translify.json.`);
+                }
+                return body;
+            }
+            throw explain(response.status, (typeof body === 'object' && body !== null ? body : {}));
+        }
+    }
+}

package/dist/index.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+import { confirm, input, password, select } from '@inquirer/prompts';
+import { Command } from 'commander';
+import { runInit } from './commands/init.js';
+import { runLogin } from './commands/login.js';
+import { runPublish } from './commands/publish.js';
+import { runPull } from './commands/pull.js';
+import { runPush } from './commands/push.js';
+import { loadConfig } from './config.js';
+import { askConfirm } from './confirm.js';
+import { resolveKey } from './credentials.js';
+import { CliError, EXIT } from './errors.js';
+import { Api } from './http.js';
+import { VERSION } from './version.js';
+const out = (line) => {
+    process.stdout.write(`${line}\n`);
+};
+const err = (line) => {
+    process.stderr.write(`${line}\n`);
+};
+const withApi = async () => {
+    const cwd = process.cwd();
+    const config = await loadConfig(cwd);
+    return { cwd, config, api: new Api(config.apiUrl, await resolveKey()) };
+};
+const isTty = Boolean(process.stdin.isTTY && process.stderr.isTTY);
+const DEFAULT_API_URL = 'https://translify.tommasofeltrin.work/api';
+// Prompts render on stderr so stdout stays clean; Ctrl+C is an ordinary exit, not a bug.
+const guarded = async (run, fallback) => {
+    try {
+        return await run();
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'ExitPromptError')
+            return fallback;
+        throw error;
+    }
+};
+const program = new Command('translify')
+    .version(VERSION)
+    .description('Sync translation files with Translify')
+    .option('--debug', 'print error details and stack traces');
+program
+    .command('init')
+    .description('Create translify.json for this repository')
+    .action(async () => {
+    process.exitCode = await runInit({
+        cwd: process.cwd(),
+        isTty,
+        out,
+        apiUrlDefault: DEFAULT_API_URL,
+        prompt: {
+            input: async (message, defaultValue) => guarded(async () => input({ message, default: defaultValue }, { output: process.stderr }), ''),
+            confirm: async (message, defaultValue) => guarded(async () => confirm({ message, default: defaultValue }, { output: process.stderr }), false),
+            choose: async (message, options) => guarded(async () => select({ message, choices: options.map((value) => ({ value })) }, { output: process.stderr }), options[0] ?? ''),
+        },
+        fetchWhoami: async (apiUrl) => {
+            try {
+                return await new Api(apiUrl, await resolveKey()).get('/cli/v1/whoami');
+            }
+            catch {
+                return undefined;
+            }
+        },
+    });
+});
+program
+    .command('login')
+    .description('Store a secret key for this machine')
+    .action(async () => {
+    let apiUrl = DEFAULT_API_URL;
+    try {
+        apiUrl = (await loadConfig(process.cwd())).apiUrl;
+    }
+    catch {
+        // No (valid) config: log in against the default API.
+    }
+    process.exitCode = await runLogin({
+        isTty,
+        apiUrl,
+        out,
+        promptSecret: async () => guarded(async () => password({ message: 'Secret key (sk_…)', mask: '*' }, { output: process.stderr }), ''),
+    });
+});
+program
+    .command('push')
+    .description('Upload source and target files')
+    .option('--dry-run', 'show what would change, write nothing')
+    .option('--overwrite-targets', 'overwrite existing target-locale translations')
+    .option('--prune', 'delete keys missing from your source files; published keys are kept; deletes exactly the keys you confirmed, and refuses if anything changed meanwhile (re-run to review)')
+    .option('-y, --yes', 'confirm destructive flags without prompting')
+    .option('--namespace <ns>', 'only this namespace')
+    .option('--json', 'machine-readable output')
+    .action(async (opts) => {
+    process.exitCode = await runPush(opts, {
+        ...(await withApi()),
+        isTty: Boolean(process.stdin.isTTY && process.stderr.isTTY),
+        confirm: askConfirm,
+        out,
+        err,
+    });
+});
+program
+    .command('publish <environment>')
+    .description('Publish an environment')
+    .option('--json', 'machine-readable output')
+    .action(async (environment, opts) => {
+    process.exitCode = await runPublish(environment, { api: (await withApi()).api, out, json: opts.json });
+});
+program
+    .command('pull')
+    .description('Download translation files')
+    .option('--from <source>', 'working (default) or env:<slug>')
+    .option('--locale <locale>', 'only this locale (as named on disk)')
+    .option('--namespace <ns>', 'only this namespace')
+    .option('--json', 'machine-readable output')
+    .action(async (opts) => {
+    process.exitCode = await runPull(opts, { ...(await withApi()), out });
+});
+program
+    .command('status')
+    .description('Exit 1 if local files differ from Translify (CI check)')
+    .option('--from <source>', 'working (default) or env:<slug>')
+    .option('--locale <locale>', 'only this locale (as named on disk)')
+    .option('--namespace <ns>', 'only this namespace')
+    .option('--json', 'machine-readable output')
+    .action(async (opts) => {
+    process.exitCode = await runPull({ ...opts, check: true }, { ...(await withApi()), out });
+});
+try {
+    await program.parseAsync(process.argv);
+}
+catch (error) {
+    // Read from argv too: a failure can come before commander has parsed the global flags.
+    const debug = program.opts().debug === true || process.argv.includes('--debug');
+    if (error instanceof CliError) {
+        err(error.message);
+        // `details` is the parsed response body only; Api never puts the key or request headers in it.
+        if (debug && error.details !== undefined)
+            err(JSON.stringify(error.details, null, 2));
+        process.exitCode = error.exitCode;
+    }
+    else {
+        err(`Unexpected error (this is a bug in translify-cli): ${error instanceof Error ? error.message : String(error)}`);
+        if (debug && error instanceof Error && error.stack !== undefined)
+            err(error.stack);
+        else
+            err('Re-run with --debug for details.');
+        process.exitCode = EXIT.network;
+    }
+}

package/dist/patterns.js

@@ -0,0 +1,59 @@
+import fg from 'fast-glob';
+import { CliError, EXIT } from './errors.js';
+const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** Patterns are written with `/`; tolerate `\` so a Windows-edited config still matches. */
+const posix = (value) => value.replaceAll('\\', '/');
+/** `locales/{locale}/{namespace}.json` → a glob and a regex with named groups. */
+const compile = (pattern) => {
+    const parts = posix(pattern).split(/(\{locale\}|\{namespace\})/);
+    const glob = parts.map((part) => (part === '{locale}' || part === '{namespace}' ? '*' : part)).join('');
+    const regex = new RegExp(`^${parts
+        .map((part) => part === '{locale}'
+        ? '(?<locale>[A-Za-z0-9_-]+)'
+        : part === '{namespace}'
+            ? '(?<namespace>[a-z0-9-]{1,64})'
+            : escape(part))
+        .join('')}$`);
+    return { glob, regex };
+};
+/** Unmapped locales pass through; the server rejects an unknown one rather than creating it. */
+export const toTranslifyLocale = (fsLocale, config) => config.locales[fsLocale] ?? fsLocale;
+export const toFsLocale = (code, config) => Object.entries(config.locales).find(([, mapped]) => mapped === code)?.[0] ?? code;
+export async function findFiles(config, cwd) {
+    const matches = [];
+    for (const rule of config.files) {
+        const { glob, regex } = compile(rule.pattern);
+        const paths = await fg(glob, { cwd, onlyFiles: true, dot: false });
+        for (const path of paths.map(posix).sort()) {
+            const groups = regex.exec(path)?.groups;
+            if (groups?.locale === undefined)
+                continue;
+            const namespace = groups.namespace ?? rule.namespace;
+            if (namespace === undefined)
+                continue;
+            matches.push({ path, locale: toTranslifyLocale(groups.locale, config), namespace, rule });
+        }
+    }
+    // One file per (locale, namespace) cell, one rule per file; otherwise push sends a cell twice and pull skips one.
+    const byPath = new Map();
+    const byCell = new Map();
+    for (const match of matches) {
+        const samePath = byPath.get(match.path);
+        if (samePath !== undefined) {
+            throw new CliError(EXIT.failed, `${match.path} is matched by more than one files rule.`);
+        }
+        const cell = `${match.locale}\u0000${match.namespace}`;
+        const sameCell = byCell.get(cell);
+        if (sameCell !== undefined) {
+            throw new CliError(EXIT.failed, `${sameCell.path} and ${match.path} both map to locale ${match.locale}, namespace ${match.namespace}. Fix the "locales" map or remove one file.`);
+        }
+        byPath.set(match.path, match);
+        byCell.set(cell, match);
+    }
+    return matches;
+}
+export function pathFor(rule, translifyLocale, namespace, config) {
+    return posix(rule.pattern)
+        .replaceAll('{locale}', toFsLocale(translifyLocale, config))
+        .replaceAll('{namespace}', namespace);
+}

package/dist/render.js

@@ -0,0 +1,70 @@
+import pc from 'picocolors';
+const MAX_ORPHANS = 20;
+const MAX_UNKNOWN = 5;
+/** Totals across locales, for `--json`. */
+export function summarizePush(res) {
+    const summary = {
+        dryRun: res.dryRun,
+        created: 0,
+        updated: 0,
+        unchanged: 0,
+        skippedFilled: 0,
+        unknownKeys: 0,
+        orphans: res.orphans.length,
+        publishedOrphans: res.orphans.filter((orphan) => orphan.published).length,
+        pruned: res.pruned,
+    };
+    for (const counts of Object.values(res.locales)) {
+        summary.created += counts.created;
+        summary.updated += counts.updated;
+        summary.unchanged += counts.unchanged;
+        summary.skippedFilled += counts.skippedFilled;
+        summary.unknownKeys += counts.unknownKeys.length;
+    }
+    return summary;
+}
+export function renderPush(res, view = {}) {
+    const lines = [res.dryRun ? pc.yellow('Dry run: nothing was written.') : pc.green('Pushed.')];
+    for (const [locale, c] of Object.entries(res.locales).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+        let line = `  ${pc.bold(locale.padEnd(8))} ${pc.green(`${c.created} created`)}, ${pc.cyan(`${c.updated} updated`)}, ` +
+            pc.dim(`${c.unchanged} unchanged`);
+        if (c.skippedFilled > 0)
+            line += pc.dim(`, ${c.skippedFilled} kept (already translated; --overwrite-targets replaces them)`);
+        lines.push(line);
+        if (c.unknownKeys.length > 0) {
+            const more = c.unknownKeys.length > MAX_UNKNOWN ? ', …' : '';
+            lines.push(pc.yellow(`           ${c.unknownKeys.length} unknown key(s) skipped: ${c.unknownKeys.slice(0, MAX_UNKNOWN).join(', ')}${more}`));
+        }
+    }
+    // `pruned` is what a dry run would delete or a real push did delete: unpublished orphans only.
+    const unpublished = res.orphans.filter((orphan) => !orphan.published);
+    const published = res.orphans.filter((orphan) => orphan.published);
+    const listed = unpublished;
+    const names = (list) => {
+        for (const orphan of list.slice(0, MAX_ORPHANS))
+            lines.push(`    ${orphan.namespace}:${orphan.key}`);
+        if (list.length > MAX_ORPHANS)
+            lines.push(`    …and ${list.length - MAX_ORPHANS} more`);
+    };
+    if (listed.length > 0) {
+        const header = res.pruned === 0
+            ? `${listed.length} key(s) in Translify are not in your source files:`
+            : res.dryRun
+                ? `${listed.length} key(s) not in your source files would be deleted:`
+                : `Deleted ${res.pruned} key(s) that were not in your source files${listed.length > res.pruned ? ` (${listed.length - res.pruned} kept: published during the push)` : ''}:`;
+        lines.push(pc.yellow(`  ${header}`));
+        names(listed);
+        if (res.pruned === 0 && view.prune !== true)
+            lines.push(pc.dim('  Use --prune to delete them.'));
+    }
+    if (published.length > 0) {
+        lines.push(pc.yellow(`  ${published.length} key(s) kept — published; unpublish it in Translify to delete it:`));
+        names(published);
+    }
+    if (res.pruned > 0 && res.dryRun)
+        lines.push(pc.yellow(`  Would delete ${res.pruned} key(s).`));
+    // A real prune's orphan header already says it; repeat it only when there was no list.
+    if (res.pruned > 0 && !res.dryRun && listed.length === 0)
+        lines.push(pc.red(`  Deleted ${res.pruned} key(s).`));
+    return lines.join('\n');
+}

package/dist/version.js

@@ -0,0 +1,3 @@
+// Must equal package.json "version"; src/version.test.ts fails when they drift.
+export const VERSION = '0.1.0';
+export const USER_AGENT = `translify-cli/${VERSION}`;