@chesterbrains/translify-cli 0.1.0 → 0.2.0

package/README.md

@@ -29,14 +29,14 @@ Requires Node 20 or newer.
 
 ```bash
 # run without installing
-npx @chesterbrains/translify-cli@0.1 --help
+npx translify --help
 
-# or add it to a project (then `npx translify` runs the local copy)
-npm i -D @chesterbrains/translify-cli
+# or add it to a project
+npm i -D translify
 npx translify --help
 ```
 
-Always use the full scoped name `@chesterbrains/translify-cli` when running through `npx` and no local install exists (including in CI). The unscoped name `translify` on npm is not ours: `npx translify` without a local install would download whatever package holds that name, with your secret key in the environment.
+`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
 
@@ -59,14 +59,12 @@ locales/
 
 ```bash
 export TRANSLIFY_SECRET_KEY=sk_...
-npx @chesterbrains/translify-cli@0.1 init            # detects your layout, writes translify.json
-npx @chesterbrains/translify-cli@0.1 push --dry-run  # show what would change, write nothing
-npx @chesterbrains/translify-cli@0.1 push
-npx @chesterbrains/translify-cli@0.1 pull
+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
 ```
 
-(If you installed it with `npm i -D`, `npx translify ...` is equivalent.)
-
 `translify.json`:
 
 ```json
@@ -111,9 +109,9 @@ ARB files always use a fixed `namespace`. The `locales` map is only needed for l
 Set the key first (`export TRANSLIFY_SECRET_KEY=sk_...` or `translify login`), then:
 
 ```bash
-npx @chesterbrains/translify-cli@0.1 init
-npx @chesterbrains/translify-cli@0.1 push
-npx @chesterbrains/translify-cli@0.1 pull
+npx translify init
+npx translify push
+npx translify pull
 flutter gen-l10n
 ```
 
@@ -132,8 +130,9 @@ flutter gen-l10n
 
 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>`
+- `push`: `--dry-run`, `--overwrite-targets`, `--prune`, `-y/--yes`, `--namespace <ns>`, `--status <draft|needs-review|approved>`
+- `pull` and `status`: `--from <working|env:slug>`, `--locale <locale>` (as named on disk), `--namespace <ns>`, `--only-approved`
+- `publish`: `--fail-on-withheld`
 - `--json` on `push`, `pull`, `status` and `publish`: machine-readable output on stdout
 - `--debug` (global): print error details and stack traces
 
@@ -148,6 +147,15 @@ Options:
 - `--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.
 
+## Review
+
+When the project has **Require review** turned on in Translify:
+
+- `push` lands target-locale translations it writes as **needs review**. `--status draft` or `--status needs-review` picks the status explicitly, and `--status approved` approves them as they land. The source file is always approved. Each locale row shows the status its cells landed in, and the output counts approved translations that went back to review because this push changed their source text.
+- Without review, `push` approves everything it writes, and `--status draft` / `--status needs-review` are refused (`REVIEW_DISABLED`).
+- `publish` to an environment with **Publish approved text only** ships the last approved text of each translation. The output adds how many translations were **carried over** (the approved text went out instead of a newer, unapproved edit) and how many were **withheld** (never approved, so left out). Publishing still succeeds; `--fail-on-withheld` exits 5 when anything was withheld, for pipelines that must ship everything reviewed.
+- `pull --only-approved` writes the approved text from the working copy and leaves out translations that were never approved, for building a release bundle without publishing. `status --only-approved` compares against the same. It works with `--from working` only: environments already apply the gate.
+
 ## CI (GitHub Actions)
 
 Store the key in the repository secrets as `TRANSLIFY_SECRET_KEY`.
@@ -166,7 +174,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with: { node-version: 22 }
-      - run: npx @chesterbrains/translify-cli@0.1 push
+      - run: npx translify push
         env:
           TRANSLIFY_SECRET_KEY: ${{ secrets.TRANSLIFY_SECRET_KEY }}
 ```
@@ -183,7 +191,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with: { node-version: 22 }
-      - run: npx @chesterbrains/translify-cli@0.1 status
+      - run: npx translify status
         env:
           TRANSLIFY_SECRET_KEY: ${{ secrets.TRANSLIFY_SECRET_KEY }}
 ```
@@ -191,10 +199,10 @@ jobs:
 Pull and publish on deploy:
 
 ```yaml
-- run: npx @chesterbrains/translify-cli@0.1 pull
+- run: npx translify pull
   env:
     TRANSLIFY_SECRET_KEY: ${{ secrets.TRANSLIFY_SECRET_KEY }}
-- run: npx @chesterbrains/translify-cli@0.1 publish production
+- run: npx translify publish production
   env:
     TRANSLIFY_SECRET_KEY: ${{ secrets.TRANSLIFY_SECRET_KEY }}
 ```
@@ -208,6 +216,7 @@ Pull and publish on deploy:
 | 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 |
+| 5 | `publish --fail-on-withheld`: the publish went through, but the review gate withheld some translations |
 
 The server's error `code` decides the exit code first; the HTTP status is only used for codes the CLI does not know.
 
@@ -230,8 +239,10 @@ The server's error `code` decides the exit code first; the HTTP status is only u
 | `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 ...@latest`). |
+| `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. |
+| `REVIEW_DISABLED` | 1 | `push --status draft` or `--status needs-review` on a project without review. Turn on **Require review** in the project settings, or drop `--status`. Nothing was written. |
+| `APPROVED_ONLY_REQUIRES_WORKING` | 1 | `--only-approved` was combined with `--from env:<slug>`. Pull an environment without it; it already holds only what its gate allowed. |
 | `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. |
@@ -241,3 +252,13 @@ The server's error `code` decides the exit code first; the HTTP status is only u
 | `@@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/publish.js

@@ -1,8 +1,15 @@
 import { EXIT } from '../errors.js';
 export async function runPublish(environment, deps) {
     const res = await deps.api.post('/cli/v1/publish', { environment });
+    const carriedOverCount = res.carriedOverCount ?? 0;
+    const withheldCount = res.withheldCount ?? 0;
+    // An ungated environment reports 0 / 0; keep its output as it was before review state.
+    const gate = carriedOverCount > 0 || withheldCount > 0 ? ` ${carriedOverCount} carried over, ${withheldCount} withheld.` : '';
     deps.out(deps.json === true
-        ? JSON.stringify({ response: res, summary: { environment, publishedCount: res.publishedCount } })
-        : `Published ${res.publishedCount} translation(s) to ${environment}.`);
-    return EXIT.ok;
+        ? JSON.stringify({
+            response: res,
+            summary: { environment, publishedCount: res.publishedCount, carriedOverCount, withheldCount },
+        })
+        : `Published ${res.publishedCount} translation(s) to ${environment}.${gate}`);
+    return deps.failOnWithheld === true && withheldCount > 0 ? EXIT.withheld : EXIT.ok;
 }

package/dist/commands/pull.js

@@ -1,6 +1,6 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, isAbsolute, relative, resolve } from 'node:path';
-import { CliError, EXIT } from '../errors.js';
+import { CliError, EXIT, ONLY_APPROVED_NEEDS_WORKING } 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/;
@@ -28,6 +28,10 @@ const withDiskLocale = (content, translifyLocale, config) => {
 /** 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) {
+    // Environments already apply the gate; the server would 400 this, fail before any request.
+    if (opts.onlyApproved && opts.from !== undefined && opts.from !== 'working') {
+        throw new CliError(EXIT.failed, ONLY_APPROVED_NEEDS_WORKING);
+    }
     const changed = [];
     const created = [];
     const responses = [];
@@ -49,6 +53,8 @@ export async function runPull(opts, deps) {
             query.jsonStyle = rule.jsonStyle;
         if (opts.from !== undefined)
             query.from = opts.from;
+        if (opts.onlyApproved)
+            query.approvedOnly = 'true';
         if (opts.locale !== undefined)
             query.locales = toTranslifyLocale(opts.locale, deps.config);
         const namespace = rule.namespace ?? opts.namespace;

package/dist/commands/push.js

@@ -3,6 +3,12 @@ import { join } from 'node:path';
 import { CliError, EXIT } from '../errors.js';
 import { findFiles } from '../patterns.js';
 import { renderPush, summarizePush } from '../render.js';
+export const PUSH_STATUSES = ['draft', 'needs-review', 'approved'];
+const WIRE_STATUS = {
+    draft: 'DRAFT',
+    'needs-review': 'NEEDS_REVIEW',
+    approved: 'APPROVED',
+};
 const PUSH = '/cli/v1/push';
 const MAX_FILES = 500;
 /** One form field per file (`file0`, `file1`, …): the server matches by field, never by filename. */
@@ -20,6 +26,9 @@ const buildForm = (uploads, opts, dryRun, prune, pruneDigest) => {
     form.set('prune', String(prune));
     if (pruneDigest !== undefined)
         form.set('pruneDigest', pruneDigest);
+    // No default on the wire: the server resolves an absent status from the project's review setting.
+    if (opts.status !== undefined)
+        form.set('status', WIRE_STATUS[opts.status]);
     for (const { field, match, bytes } of uploads)
         form.append(field, new File([bytes], match.path));
     return form;

package/dist/errors.js

@@ -1,5 +1,5 @@
 // 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 };
+export const EXIT = { ok: 0, failed: 1, auth: 2, quota: 3, network: 4, withheld: 5 };
 /** Every expected failure. `index.ts` prints `message` and exits with `exitCode`; anything else is a bug. */
 export class CliError extends Error {
     exitCode;
@@ -10,3 +10,5 @@ export class CliError extends Error {
         this.details = details;
     }
 }
+/** Shared by the local check in `pull` and the server's `APPROVED_ONLY_REQUIRES_WORKING`. */
+export const ONLY_APPROVED_NEEDS_WORKING = '--only-approved works with --from working only; environments already apply the review gate.';

package/dist/http.js

@@ -1,4 +1,4 @@
-import { CliError, EXIT } from './errors.js';
+import { CliError, EXIT, ONLY_APPROVED_NEEDS_WORKING } from './errors.js';
 import { USER_AGENT } from './version.js';
 const NOT_JSON = Symbol('notJson');
 const MAX_RETRIES = 3;
@@ -30,6 +30,8 @@ const CODE_EXIT = {
     ORPHANS_CHANGED: EXIT.failed,
     TRANSACTION_CONFLICT: EXIT.network,
     RATE_LIMITED: EXIT.network,
+    REVIEW_DISABLED: EXIT.failed,
+    APPROVED_ONLY_REQUIRES_WORKING: EXIT.failed,
 };
 const exitFor = (status, code) => {
     const byCode = code === undefined ? undefined : CODE_EXIT[code];
@@ -82,6 +84,10 @@ const describeBody = (status, body) => {
             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 'REVIEW_DISABLED':
+            return 'Review is off for this project, so --status draft or needs-review cannot be used. Turn on "Require review" in the project settings, or drop --status.';
+        case 'APPROVED_ONLY_REQUIRES_WORKING':
+            return ONLY_APPROVED_NEEDS_WORKING;
         case 'TRANSACTION_CONFLICT':
             return 'The server hit a transaction conflict. Try again.';
         case 'RATE_LIMITED':

package/dist/index.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { confirm, input, password, select } from '@inquirer/prompts';
-import { Command } from 'commander';
+import { Command, Option } 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 { PUSH_STATUSES, runPush } from './commands/push.js';
 import { loadConfig } from './config.js';
 import { askConfirm } from './confirm.js';
 import { resolveKey } from './credentials.js';
@@ -90,6 +90,7 @@ program
     .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')
+    .addOption(new Option('--status <status>', 'status target-locale cells land in (default: needs-review when the project requires review, approved otherwise)').choices(PUSH_STATUSES))
     .option('--json', 'machine-readable output')
     .action(async (opts) => {
     process.exitCode = await runPush(opts, {
@@ -103,9 +104,15 @@ program
 program
     .command('publish <environment>')
     .description('Publish an environment')
+    .option('--fail-on-withheld', 'exit 5 when the review gate withheld any translation (the publish still happens)')
     .option('--json', 'machine-readable output')
     .action(async (environment, opts) => {
-    process.exitCode = await runPublish(environment, { api: (await withApi()).api, out, json: opts.json });
+    process.exitCode = await runPublish(environment, {
+        api: (await withApi()).api,
+        out,
+        json: opts.json,
+        failOnWithheld: opts.failOnWithheld,
+    });
 });
 program
     .command('pull')
@@ -113,6 +120,7 @@ program
     .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('--only-approved', 'approved text only; translations never approved are left out (working copy only)')
     .option('--json', 'machine-readable output')
     .action(async (opts) => {
     process.exitCode = await runPull(opts, { ...(await withApi()), out });
@@ -123,6 +131,7 @@ program
     .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('--only-approved', 'approved text only; translations never approved are left out (working copy only)')
     .option('--json', 'machine-readable output')
     .action(async (opts) => {
     process.exitCode = await runPull({ ...opts, check: true }, { ...(await withApi()), out });

package/dist/render.js

@@ -1,6 +1,8 @@
 import pc from 'picocolors';
 const MAX_ORPHANS = 20;
 const MAX_UNKNOWN = 5;
+/** APPROVED gets no label: it is all a project without review ever sees. */
+const STATUS_LABEL = { DRAFT: 'draft', NEEDS_REVIEW: 'needs review' };
 /** Totals across locales, for `--json`. */
 export function summarizePush(res) {
     const summary = {
@@ -13,6 +15,7 @@ export function summarizePush(res) {
         orphans: res.orphans.length,
         publishedOrphans: res.orphans.filter((orphan) => orphan.published).length,
         pruned: res.pruned,
+        staleReset: res.staleReset ?? 0,
     };
     for (const counts of Object.values(res.locales)) {
         summary.created += counts.created;
@@ -30,12 +33,19 @@ export function renderPush(res, view = {}) {
             pc.dim(`${c.unchanged} unchanged`);
         if (c.skippedFilled > 0)
             line += pc.dim(`, ${c.skippedFilled} kept (already translated; --overwrite-targets replaces them)`);
+        const label = c.status === undefined ? undefined : STATUS_LABEL[c.status];
+        if (label !== undefined && c.created + c.updated > 0)
+            line += pc.magenta(` · ${label}`);
         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}`));
         }
     }
+    const stale = res.staleReset ?? 0;
+    if (stale > 0) {
+        lines.push(pc.yellow(`${stale} approved translation(s) ${res.dryRun ? 'would go' : 'went'} back to review because their source text changed.`));
+    }
     // `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);

package/dist/version.js

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

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "@chesterbrains/translify-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Push, pull and publish Translify translations from your repository",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chesterbrains/translify-cli.git"
+  },
+  "homepage": "https://github.com/chesterbrains/translify-cli#readme",
+  "bugs": {
+    "url": "https://github.com/chesterbrains/translify-cli/issues"
+  },
   "type": "module",
   "bin": {
     "translify": "dist/index.js"