@chesterbrains/translify-cli 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chesterbrains
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,251 @@
-# Temporary Holding Version
+# Translify CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Push, pull and publish [Translify](https://translify.tommasofeltrin.work) translations from your repository.
+
+The CLI reads a `translify.json` that maps your translation files (i18next JSON, XLIFF or Flutter ARB) to a Translify project, and uses a project **secret key** to:
+
+- `push` source and target files up to Translify,
+- `pull` the current translations back into your files,
+- `status` to fail CI when local files differ from Translify,
+- `publish` an environment.
+
+## Install
+
+### Standalone binary (no Node needed)
+
+macOS and Linux (x64 or arm64):
+
+```bash
+curl -fsSL https://github.com/chesterbrains/translify-cli/releases/latest/download/install.sh | sh
+```
+
+The script checks the download against the release's `SHA256SUMS` and installs `translify` to `~/.local/bin` (set `TRANSLIFY_INSTALL_DIR` to change it, `TRANSLIFY_VERSION=v0.1.0` to pin a version). It never uses `sudo`.
+
+On Windows, download `translify-windows-x64.exe` from the [releases page](https://github.com/chesterbrains/translify-cli/releases).
+
+### With Node
+
+Requires Node 20 or newer.
+
+```bash
+# run without installing
+npx translify --help
+
+# or add it to a project
+npm i -D translify
+npx translify --help
+```
+
+`translify` is an alias of `@chesterbrains/translify-cli`: the same CLI, so `npm i -D @chesterbrains/translify-cli` and `npm i -D translify` both work.
+
+## Create a secret key
+
+In Translify, open your project's API keys, create a **secret key** (it starts with `sk_`) and give it the scopes you need: `PULL` to pull and run `status`, `PUSH` to push, `PUBLISH` to publish. The raw key is shown once.
+
+Give the key to the CLI in one of two ways:
+
+- set `TRANSLIFY_SECRET_KEY` (always wins; use this in CI), or
+- run `translify login` and paste it. It is stored in `~/.config/translify/credentials` (or under `$XDG_CONFIG_HOME`).
+
+Never commit a key. Delivery keys (public keys used by apps to download published translations) do not work here.
+
+## Quickstart: i18next
+
+```
+locales/
+  en/common.json
+  it/common.json
+```
+
+```bash
+export TRANSLIFY_SECRET_KEY=sk_...
+npx translify init            # detects your layout, writes translify.json
+npx translify push --dry-run  # show what would change, write nothing
+npx translify push
+npx translify pull
+```
+
+`translify.json`:
+
+```json
+{
+  "$schema": "https://unpkg.com/@chesterbrains/translify-cli/schema/translify.schema.json",
+  "apiUrl": "https://translify.tommasofeltrin.work/api",
+  "files": [
+    { "pattern": "locales/{locale}/{namespace}.json", "format": "json" }
+  ]
+}
+```
+
+- `pattern` must contain `{locale}`. `{namespace}` is optional; without it, set a fixed `"namespace"` on the rule.
+- `format` is `json`, `xliff` or `arb`. JSON also takes `"jsonStyle": "nested"` (default) or `"flat"`.
+- `locales` maps a locale name on disk to the Translify locale code, for example `{ "en_US": "en-US" }`. Omit it when the names already match.
+
+## Quickstart: Flutter
+
+`l10n.yaml`:
+
+```yaml
+arb-dir: lib/l10n
+template-arb-file: app_en.arb
+output-localization-file: app_localizations.dart
+```
+
+`translify.json`:
+
+```json
+{
+  "$schema": "https://unpkg.com/@chesterbrains/translify-cli/schema/translify.schema.json",
+  "apiUrl": "https://translify.tommasofeltrin.work/api",
+  "files": [
+    { "pattern": "lib/l10n/app_{locale}.arb", "format": "arb", "namespace": "app" }
+  ],
+  "locales": { "en_US": "en-US" }
+}
+```
+
+ARB files always use a fixed `namespace`. The `locales` map is only needed for locales that Flutter names with an underscore (`app_en_US.arb`); `translify init` suggests it for you.
+
+Set the key first (`export TRANSLIFY_SECRET_KEY=sk_...` or `translify login`), then:
+
+```bash
+npx translify init
+npx translify push
+npx translify pull
+flutter gen-l10n
+```
+
+`"@@locale"` is optional in ARB files: when it is absent, the file's locale is used. When it is present it must match the file's locale (case and `_`/`-` are ignored). On `pull`, the CLI writes `@@locale` using the locale name on disk (for example `en_US` in `app_en_US.arb`), as `flutter gen-l10n` expects.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `translify init` | Create `translify.json` (interactive) |
+| `translify login` | Store a secret key on this machine (interactive) |
+| `translify push` | Upload source and target files |
+| `translify pull` | Download translation files |
+| `translify status` | Exit 1 if local files differ from Translify |
+| `translify publish <env>` | Publish an environment, e.g. `production` |
+
+Options:
+
+- `push`: `--dry-run`, `--overwrite-targets`, `--prune`, `-y/--yes`, `--namespace <ns>`
+- `pull` and `status`: `--from <working|env:slug>`, `--locale <locale>` (as named on disk), `--namespace <ns>`
+- `--json` on `push`, `pull`, `status` and `publish`: machine-readable output on stdout
+- `--debug` (global): print error details and stack traces
+
+## Conflict rules
+
+`push` is conservative by default:
+
+- **Source locale: your files win.** Existing source translations are overwritten with what is in the file.
+- **Target locales: Translify fills only the gaps.** Keys that already have a translation are left alone and counted as skipped.
+- `--overwrite-targets` also overwrites existing target translations.
+- `--prune` deletes keys that no longer exist in your source files, together with their translations. Keys that are published to an environment are never deleted: they are listed as kept, and you unpublish them in Translify first. `--prune` deletes exactly the keys you confirmed: the real push sends a digest of the dry run's list, and if anything changed since (keys added, removed or published) the server refuses and you re-run `translify push --prune` to review the new list. A server too old to return that digest makes `--prune` refuse.
+- `--yes` skips the confirmation prompt for the two destructive flags. Without a terminal and without `--yes`, a destructive push is refused and nothing changes.
+- `--dry-run` shows the effect of any combination and writes nothing.
+
+## CI (GitHub Actions)
+
+Store the key in the repository secrets as `TRANSLIFY_SECRET_KEY`.
+
+Push on main:
+
+```yaml
+name: Translify push
+on:
+  push:
+    branches: [main]
+jobs:
+  push:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - run: npx translify push
+        env:
+          TRANSLIFY_SECRET_KEY: ${{ secrets.TRANSLIFY_SECRET_KEY }}
+```
+
+Fail a pull request when local files drift from Translify:
+
+```yaml
+name: Translify status
+on: pull_request
+jobs:
+  status:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - run: npx translify status
+        env:
+          TRANSLIFY_SECRET_KEY: ${{ secrets.TRANSLIFY_SECRET_KEY }}
+```
+
+Pull and publish on deploy:
+
+```yaml
+- run: npx translify pull
+  env:
+    TRANSLIFY_SECRET_KEY: ${{ secrets.TRANSLIFY_SECRET_KEY }}
+- run: npx translify publish production
+  env:
+    TRANSLIFY_SECRET_KEY: ${{ secrets.TRANSLIFY_SECRET_KEY }}
+```
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | The request or input was rejected, or `status` found drift, or a destructive flag was not confirmed |
+| 2 | Key problem: invalid, revoked, wrong kind of key, or a missing scope |
+| 3 | Plan quota exceeded |
+| 4 | Network failure, server error, push too large, CLI too old, transaction conflict, or rate limited after 3 retries |
+
+The server's error `code` decides the exit code first; the HTTP status is only used for codes the CLI does not know.
+
+## Troubleshooting
+
+| Code | Exit | What to do |
+|---|---|---|
+| `VALIDATION_FAILED` | 1 | Nothing was written. The output lists `file:line key: reason`; fix those entries and push again. |
+| `LOCALE_NOT_FOUND` | 1 | A locale in your files is not enabled in the project. Enable it in Translify, or map it with `locales` in `translify.json`. |
+| `NAMESPACE_NOT_FOUND` | 1 | The namespace does not exist in the project. Create it in Translify or fix the `--namespace` / pattern. |
+| `VALIDATION_FAILED` with `emptySourcePrune` | 1 | `--prune` was refused because a source file in the push has no entries (it would delete the whole namespace). Push the real source file, or drop `--prune`; emptying a namespace is done in the Translify web app. |
+| `JSON_STYLE_REQUIRES_JSON` | 1 | `jsonStyle` only applies to rules with `"format": "json"`. Remove it from the other rules. |
+| `BAD_REQUEST` | 1 | The request was malformed. Re-run with `--debug` for the server's message. |
+| `ENVIRONMENT_NOT_FOUND` / `ENVIRONMENT_ARCHIVED` | 1 | Check the environment slug passed to `publish` or `--from env:<slug>`, and that it is not archived. |
+| `PROJECT_ARCHIVED` | 1 | The project is archived; unarchive it in Translify. |
+| `SECRET_KEY_IN_URL` | 1 | A secret key was sent in a query string. Pass it only via `TRANSLIFY_SECRET_KEY` or `translify login`. |
+| `KEY_INVALID` | 2 | The key is not recognised. Check `TRANSLIFY_SECRET_KEY` and `apiUrl`. |
+| `KEY_REVOKED` | 2 | Create a new secret key in Translify. |
+| `KEY_WRONG_KIND` | 2 | You supplied a non-secret key. The CLI needs an `sk_` key. |
+| `SCOPE_MISSING` | 2 | The key lacks the scope named in the message (`PULL`, `PUSH` or `PUBLISH`). Create a key that has it. |
+| `QUOTA_EXCEEDED` | 3 | Your plan limit was reached (usually translation keys). Remove keys, or push a smaller set. |
+| `PUSH_TOO_LARGE` | 4 | Split the push by namespace: `translify push --namespace <ns>`. |
+| `CLI_TOO_OLD` | 4 | Upgrade: `npm i -g @chesterbrains/translify-cli@latest` (or use `npx translify@latest`). |
+| `ORPHANS_CHANGED` | 1 | The orphan list changed between the dry run and the real push (keys were added, removed or published). Nothing was written; run `translify push --prune` again to review the new list. |
+| `TRANSACTION_CONFLICT` | 4 | Another write collided with yours. Retry. |
+| `RATE_LIMITED` | 4 | The CLI already retried 3 times, honouring `Retry-After`. Wait a moment and retry. |
+| `INTERNAL_ERROR` / `DATABASE_ERROR` / 5xx | 4 | A server problem. Retry shortly; if it persists, re-run with `--debug` and report it. |
+| Network error | 4 | `Could not reach <apiUrl>`: check `apiUrl` in `translify.json` and your connection. |
+| Request timed out | 4 | A request took longer than 180 s. Retry, or split the push with `--namespace`. |
+| `Too many files (N > 500)` | 1 | A push carries at most 500 files. Split it with `--namespace`. |
+| `@@locale` does not match | 1 | `@@locale` is optional, but if an `.arb` file has it, it must match the file's locale (case and `_`/`-` are ignored). Fix or remove it and push again. |
+| `No translify.json here` | 1 | Run `translify init` in the repository root. |
+| `status` reports drift | 1 | Run `translify pull` (or `push`) to bring the two sides back in line. |
+
+## Releasing the `translify` alias
+
+The unscoped `translify` package lives in `alias/`. Its `bin.js` just imports `@chesterbrains/translify-cli`, which it depends on at `>=0.1.0 <1.0.0`, so it follows every 0.x release of the CLI without a republish. It only needs republishing (with a bumped range) for a 1.x major:
+
+```bash
+cd alias && npm publish --access public   # then approve the staged release
+```
+
+The alias is not part of the CLI's npm tarball and is ignored by lint, typecheck and tests.

package/dist/commands/init.js

@@ -0,0 +1,140 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import fg from 'fast-glob';
+import { CliError, EXIT } from '../errors.js';
+import { findFiles } from '../patterns.js';
+const SCHEMA_URL = 'https://unpkg.com/@chesterbrains/translify-cli/schema/translify.schema.json';
+const I18NEXT_ROOTS = ['locales', 'public/locales', 'src/locales', 'src/i18n'];
+const EXAMPLE_RULE = { pattern: 'locales/{locale}/{namespace}.json', format: 'json', jsonStyle: 'nested' };
+const unquote = (value) => value.replace(/^["']|["']$/g, '').replace(/^(\.\/)+/, '').replace(/\/+$/, '');
+async function detectFlutter(cwd) {
+    let yaml;
+    try {
+        yaml = await readFile(join(cwd, 'l10n.yaml'), 'utf8');
+    }
+    catch {
+        yaml = undefined;
+    }
+    if (yaml === undefined) {
+        const arbs = await fg('lib/l10n/*.arb', { cwd, onlyFiles: true });
+        return arbs.length > 0 ? [{ pattern: 'lib/l10n/app_{locale}.arb', format: 'arb', namespace: 'app' }] : [];
+    }
+    const dir = unquote(/^arb-dir:\s*(\S+)/m.exec(yaml)?.[1] ?? 'lib/l10n');
+    const template = unquote(/^template-arb-file:\s*(\S+)/m.exec(yaml)?.[1] ?? 'app_en.arb');
+    const prefix = /^(.*?)_[a-z]{2,3}(?:[_-](?:[A-Z]{2}|[0-9]{3}|[A-Z][a-z]{3}))*\.arb$/.exec(template)?.[1] ?? 'app';
+    return [{ pattern: `${dir}/${prefix}_{locale}.arb`, format: 'arb', namespace: 'app' }];
+}
+/** Recognises i18next and Flutter layouts; an empty list means "unknown, write an example". */
+export async function detectLayout(cwd) {
+    const rules = [];
+    for (const root of I18NEXT_ROOTS) {
+        const found = await fg(`${root}/*/*.json`, { cwd, onlyFiles: true });
+        if (found.length > 0)
+            rules.push({ pattern: `${root}/{locale}/{namespace}.json`, format: 'json', jsonStyle: 'nested' });
+    }
+    return [...rules, ...(await detectFlutter(cwd))];
+}
+const normalize = (locale) => locale.toLowerCase().replaceAll('_', '-');
+/** Disk locales that differ from a Translify locale only by case or separator (`en_US` → `en-US`). */
+export function suggestLocaleMap(diskLocales, translifyLocales) {
+    const known = new Set(translifyLocales);
+    const disk = new Set(diskLocales);
+    const map = {};
+    const targets = new Set();
+    for (const locale of diskLocales) {
+        if (known.has(locale))
+            continue;
+        const target = translifyLocales.find((code) => normalize(code) === normalize(locale));
+        // A bijection that cannot chain: loadConfig rejects anything else.
+        if (target === undefined || targets.has(target) || disk.has(target))
+            continue;
+        map[locale] = target;
+        targets.add(target);
+    }
+    return map;
+}
+const isHttpUrl = (value) => {
+    try {
+        return ['http:', 'https:'].includes(new URL(value).protocol);
+    }
+    catch {
+        return false;
+    }
+};
+async function exists(path) {
+    try {
+        await readFile(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function runInit(deps) {
+    if (!deps.isTty) {
+        deps.out('`translify init` needs an interactive terminal. Write translify.json by hand in CI.');
+        return EXIT.failed;
+    }
+    const target = join(deps.cwd, 'translify.json');
+    if ((await exists(target)) && !(await deps.prompt.confirm('translify.json already exists. Overwrite it?', false))) {
+        deps.out('Left translify.json unchanged.');
+        return EXIT.failed;
+    }
+    const detected = await detectLayout(deps.cwd);
+    if (detected.length === 0) {
+        deps.out(`No i18next or Flutter layout found in ${deps.cwd} (detection looks only in the current directory). Wrote an example rule (${EXAMPLE_RULE.pattern}): edit files[] to match your project.`);
+    }
+    else {
+        deps.out(`Found: ${detected.map((rule) => `${rule.pattern} (${rule.format})`).join(', ')}`);
+    }
+    let files = detected.length > 0 ? detected : [EXAMPLE_RULE];
+    if (detected.length > 1) {
+        const chosen = await deps.prompt.choose('Several layouts found. Which one holds your translations?', detected.map((rule) => rule.pattern));
+        files = detected.filter((rule) => rule.pattern === chosen);
+        if (files.length === 0)
+            files = [detected[0]];
+        deps.out(`Dropped: ${detected.filter((rule) => !files.includes(rule)).map((rule) => rule.pattern).join(', ')}`);
+    }
+    const apiUrl = (await deps.prompt.input('Translify API URL', deps.apiUrlDefault)).trim();
+    if (!isHttpUrl(apiUrl)) {
+        deps.out('The API URL must start with http:// or https://. Nothing was written.');
+        return EXIT.failed;
+    }
+    // A config that cannot resolve its own files would fail on the first push or pull: refuse to write it.
+    let matches;
+    try {
+        matches = await findFiles({ apiUrl, files, locales: {} }, deps.cwd);
+    }
+    catch (error) {
+        if (!(error instanceof CliError))
+            throw error;
+        deps.out(`${error.message} Nothing was written.`);
+        return EXIT.failed;
+    }
+    let locales = {};
+    const me = await deps.fetchWhoami(apiUrl);
+    if (me !== undefined) {
+        deps.out(`Project: ${me.project.name}, default locale ${me.project.defaultLocale ?? 'none'}; locales: ${me.locales.join(', ')}`);
+        locales = await suggestMap(deps, matches, me.locales);
+    }
+    const config = { $schema: SCHEMA_URL, apiUrl, files, locales };
+    // `locales` is omitted when empty; the schema defaults it.
+    const body = { ...config };
+    if (Object.keys(locales).length === 0)
+        delete body.locales;
+    await writeFile(target, `${JSON.stringify(body, null, 2)}\n`);
+    deps.out('Wrote translify.json. The key is not stored there: run `translify login` or set TRANSLIFY_SECRET_KEY.');
+    return EXIT.ok;
+}
+async function suggestMap(deps, matches, translifyLocales) {
+    const diskLocales = [...new Set(matches.map((match) => match.locale))];
+    const missing = diskLocales.filter((locale) => !translifyLocales.includes(locale));
+    const map = suggestLocaleMap(diskLocales, translifyLocales);
+    for (const locale of missing.filter((entry) => map[entry] === undefined)) {
+        deps.out(`Locale ${locale} on disk is not enabled in the project; push will reject it.`);
+    }
+    if (Object.keys(map).length === 0)
+        return {};
+    const text = Object.entries(map).map(([from, to]) => `${from} → ${to}`).join(', ');
+    return (await deps.prompt.confirm(`Map disk locales to Translify codes (${text})?`, true)) ? map : {};
+}

package/dist/commands/login.js

@@ -0,0 +1,18 @@
+import { assertSecret, saveKey } from '../credentials.js';
+import { EXIT } from '../errors.js';
+import { Api } from '../http.js';
+export async function runLogin(deps) {
+    if (!deps.isTty) {
+        deps.out('`translify login` needs an interactive terminal. In CI, set TRANSLIFY_SECRET_KEY instead.');
+        return EXIT.failed;
+    }
+    const key = (await deps.promptSecret()).trim();
+    // Before any network call, and the error never echoes the value.
+    assertSecret(key);
+    const api = new Api(deps.apiUrl, key, deps.fetchImpl);
+    // A 401/403 throws here, so a rejected key is never saved.
+    const me = await api.get('/cli/v1/whoami');
+    const path = await saveKey(key, deps.env);
+    deps.out(`Logged in to ${me.project.name} (${me.project.slug}) with scopes ${me.key.scopes.join(', ')}. Saved to ${path}.`);
+    return EXIT.ok;
+}

package/dist/commands/publish.js

@@ -0,0 +1,8 @@
+import { EXIT } from '../errors.js';
+export async function runPublish(environment, deps) {
+    const res = await deps.api.post('/cli/v1/publish', { environment });
+    deps.out(deps.json === true
+        ? JSON.stringify({ response: res, summary: { environment, publishedCount: res.publishedCount } })
+        : `Published ${res.publishedCount} translation(s) to ${environment}.`);
+    return EXIT.ok;
+}

package/dist/commands/pull.js

@@ -0,0 +1,114 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { CliError, EXIT } from '../errors.js';
+import { pathFor, toFsLocale, toTranslifyLocale } from '../patterns.js';
+const readOrUndefined = async (path) => readFile(path, 'utf8').catch(() => undefined);
+const NESTED_CONFLICT = /nested JSON cannot hold both/;
+/**
+ * Flutter's gen_l10n requires `@@locale` to match the file name, and only the CLI knows the disk
+ * mapping. Rewrites the value in place (key order kept) with the server's own formatting so the
+ * output is byte-stable; content that is not a JSON object is left alone.
+ */
+const withDiskLocale = (content, translifyLocale, config) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        return content;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return content;
+    const doc = parsed;
+    if (typeof doc['@@locale'] !== 'string')
+        return content;
+    doc['@@locale'] = toFsLocale(translifyLocale, config);
+    return `${JSON.stringify(doc, null, 2)}\n`;
+};
+/** A Windows checkout (autocrlf, BOM) must not count as drift. */
+const normalizeEol = (text) => text.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+export async function runPull(opts, deps) {
+    const changed = [];
+    const created = [];
+    const responses = [];
+    const lines = [];
+    let flatHinted = false;
+    // Phase 1 plans every write; nothing touches disk until every request and check has passed.
+    const plan = [];
+    const seen = new Map();
+    // Namespaces a fixed-namespace rule owns must not also be written by a `{namespace}` rule.
+    const claimed = new Set(deps.config.files.flatMap((rule) => (rule.namespace === undefined ? [] : [rule.namespace])));
+    for (const rule of deps.config.files) {
+        if (opts.namespace !== undefined && rule.namespace !== undefined && rule.namespace !== opts.namespace)
+            continue;
+        const wildcard = rule.namespace === undefined;
+        if (wildcard && opts.namespace !== undefined && claimed.has(opts.namespace))
+            continue;
+        const query = { format: rule.format };
+        if (rule.format === 'json' && rule.jsonStyle !== undefined)
+            query.jsonStyle = rule.jsonStyle;
+        if (opts.from !== undefined)
+            query.from = opts.from;
+        if (opts.locale !== undefined)
+            query.locales = toTranslifyLocale(opts.locale, deps.config);
+        const namespace = rule.namespace ?? opts.namespace;
+        if (namespace !== undefined)
+            query.namespaces = namespace;
+        const res = await deps.api.get('/cli/v1/pull', query);
+        responses.push(res);
+        for (const warning of res.warnings) {
+            lines.push(`warning: ${warning}`);
+            if (!flatHinted && NESTED_CONFLICT.test(warning)) {
+                flatHinted = true;
+                lines.push('hint: set "jsonStyle": "flat" on this files rule in translify.json to keep both keys.');
+            }
+        }
+        for (const file of res.files) {
+            if (wildcard && claimed.has(file.namespace))
+                continue;
+            const path = pathFor(rule, file.locale, file.namespace, deps.config);
+            const absolute = resolve(deps.cwd, path);
+            const rel = relative(resolve(deps.cwd), absolute);
+            if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) {
+                throw new CliError(EXIT.failed, `Refusing to write ${path}: it resolves outside the project directory.`);
+            }
+            // Two server locales can back-map to one disk locale; writing both would clobber one every run.
+            const cell = `${file.locale}/${file.namespace}`;
+            const other = seen.get(absolute);
+            if (other !== undefined) {
+                throw new CliError(EXIT.failed, `${path} would be written for both ${other} and ${cell}. Fix the "locales" map so each Translify locale has its own file.`);
+            }
+            seen.set(absolute, cell);
+            const content = rule.format === 'arb' ? withDiskLocale(file.content, file.locale, deps.config) : file.content;
+            const existing = await readOrUndefined(absolute);
+            if (existing !== undefined && (existing === content || normalizeEol(existing) === content))
+                continue;
+            (existing === undefined ? created : changed).push(path);
+            plan.push({ path, absolute, content });
+        }
+    }
+    if (!opts.check) {
+        for (const item of plan) {
+            await mkdir(dirname(item.absolute), { recursive: true });
+            await writeFile(item.absolute, item.content);
+        }
+    }
+    const drift = [...changed, ...created];
+    if (opts.json) {
+        deps.out(JSON.stringify({ responses, summary: { check: opts.check === true, changed: drift, created } }));
+    }
+    else {
+        for (const line of lines)
+            deps.out(line);
+        if (drift.length === 0)
+            deps.out(opts.check ? 'Up to date.' : 'Nothing to update.');
+        else {
+            const rows = [
+                ...changed.map((path) => `  ${path}`),
+                ...created.map((path) => `  ${path} (new)`),
+            ];
+            deps.out(`${opts.check ? 'Out of date' : 'Updated'}:\n${rows.join('\n')}`);
+        }
+    }
+    return opts.check && drift.length > 0 ? EXIT.failed : EXIT.ok;
+}

package/dist/commands/push.js

@@ -0,0 +1,107 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CliError, EXIT } from '../errors.js';
+import { findFiles } from '../patterns.js';
+import { renderPush, summarizePush } from '../render.js';
+const PUSH = '/cli/v1/push';
+const MAX_FILES = 500;
+/** One form field per file (`file0`, `file1`, …): the server matches by field, never by filename. */
+const buildForm = (uploads, opts, dryRun, prune, pruneDigest) => {
+    const form = new FormData();
+    form.set('manifest', JSON.stringify(uploads.map(({ field, match }) => ({
+        field,
+        path: match.path,
+        format: match.rule.format,
+        locale: match.locale,
+        namespace: match.namespace,
+    }))));
+    form.set('dryRun', String(dryRun));
+    form.set('overwriteTargets', String(opts.overwriteTargets === true));
+    form.set('prune', String(prune));
+    if (pruneDigest !== undefined)
+        form.set('pruneDigest', pruneDigest);
+    for (const { field, match, bytes } of uploads)
+        form.append(field, new File([bytes], match.path));
+    return form;
+};
+/**
+ * What a confirmed push would destroy, from its dry run. `updated` also counts
+ * source-locale edits, which happen without the flag, so overwrites are the
+ * target locales' `updated` only; the source locale comes from whoami.
+ */
+const describeDamage = async (preview, opts, api) => {
+    const damage = [];
+    // Published orphans are kept by the server, so they are not part of the damage.
+    const deletable = preview.orphans.filter((orphan) => !orphan.published).length;
+    if (opts.prune === true && deletable > 0)
+        damage.push(`delete ${deletable} key(s) and all their translations`);
+    if (opts.overwriteTargets === true) {
+        const { project } = await api.get('/cli/v1/whoami');
+        const overwritten = Object.entries(preview.locales)
+            .filter(([locale, counts]) => locale !== project.defaultLocale && counts.updated > 0)
+            .map(([locale, counts]) => [locale, counts.updated]);
+        const total = overwritten.reduce((sum, [, count]) => sum + count, 0);
+        if (total > 0) {
+            const byLocale = overwritten.map(([locale, count]) => `${locale}: ${count}`).join(', ');
+            damage.push(`overwrite ${total} existing translation(s) (${byLocale})`);
+        }
+    }
+    return damage;
+};
+export async function runPush(opts, deps) {
+    const matches = (await findFiles(deps.config, deps.cwd)).filter((match) => opts.namespace === undefined || match.namespace === opts.namespace);
+    if (matches.length === 0) {
+        const scope = opts.namespace === undefined ? '' : ` for namespace "${opts.namespace}"`;
+        deps.err(`No files matched the translify.json patterns${scope}.`);
+        return EXIT.failed;
+    }
+    if (matches.length > MAX_FILES) {
+        throw new CliError(EXIT.failed, `Too many files (${matches.length} > ${MAX_FILES}): split the push with --namespace.`);
+    }
+    const uploads = await Promise.all(matches.map(async (match, index) => ({
+        match,
+        field: `file${index}`,
+        bytes: new Uint8Array(await readFile(join(deps.cwd, match.path))),
+    })));
+    const show = (res, preview) => {
+        deps.out(opts.json === true
+            ? JSON.stringify({ preview, response: res, summary: summarizePush(res) })
+            : renderPush(res, { prune: opts.prune === true }));
+    };
+    const destructive = opts.prune === true || opts.overwriteTargets === true;
+    if (opts.dryRun === true || !destructive) {
+        // Plain push or an explicit dry run: one request, nothing to confirm.
+        show(await deps.api.post(PUSH, buildForm(uploads, opts, opts.dryRun === true, opts.prune === true)));
+        return EXIT.ok;
+    }
+    const preview = await deps.api.post(PUSH, buildForm(uploads, opts, true, opts.prune === true));
+    if (opts.prune === true && typeof preview.pruneDigest !== 'string') {
+        deps.err('This server cannot confirm a prune (its dry run returned no pruneDigest), so --prune would delete without a bound. ' +
+            'Nothing was changed. Upgrade the Translify server, or push without --prune.');
+        return EXIT.failed;
+    }
+    const damage = await describeDamage(preview, opts, deps.api);
+    // Nothing would be deleted or overwritten: no question to ask (F19).
+    if (damage.length > 0) {
+        // With --json, stdout is reserved for the final document.
+        (opts.json === true ? deps.err : deps.out)(renderPush(preview));
+        const question = `This will ${damage.join(' and ')}. Continue?`;
+        if (opts.yes !== true) {
+            if (!deps.isTty) {
+                deps.err(`${question}\nRefusing without a terminal; nothing was changed. Re-run with --yes to confirm.`);
+                return EXIT.failed;
+            }
+            if (!(await deps.confirm(question))) {
+                deps.err('Cancelled; nothing was changed.');
+                return EXIT.failed;
+            }
+        }
+    }
+    // With deletable orphans the real push sends the digest of the list the user confirmed: if the server's
+    // deletable set differs it answers 409 ORPHANS_CHANGED and writes nothing. With none, there is nothing to prune.
+    const deletable = preview.orphans.filter((orphan) => !orphan.published).length;
+    const prune = opts.prune === true && deletable > 0;
+    const res = await deps.api.post(PUSH, buildForm(uploads, opts, false, prune, prune ? preview.pruneDigest : undefined));
+    show(res, preview);
+    return EXIT.ok;
+}