@chesterbrains/translify-cli 0.7.0 → 0.8.0

package/README.md

@@ -257,34 +257,38 @@ Options:
 - **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. See [Prune safety](#prune-safety).
+- `--prune` moves keys that no longer exist in your source files to the Translify trash, together with their translations. They can be restored for 30 days. See [Prune safety](#prune-safety).
 - `--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.
 
 ## Prune safety
 
-`translify push --prune` is the only command that deletes keys. What it deletes, and what stops it:
+`translify push --prune` is the only command that removes keys. It never deletes on the spot: it archives them. What
+it archives, and what stops it:
 
 - **Only the namespaces in this push.** A key is an orphan when its namespace is in the push and its source file no
   longer has it. Namespaces you did not push (another rule, another repository, `--namespace` left them out) are never
   touched.
-- **Never published keys.** A key published to any environment is listed as kept and survives. Unpublish it in
-  Translify first if it really should go.
+- **Archived, not deleted.** A pruned key goes to the trash in Translify, with its translations and their history.
+  It is deleted for good 30 days later. Until then, restore it from the trash on the project's Translations tab, or
+  push a source file that names it again: the push restores it in place and reports it as restored.
+- **Live keys too.** A key that is live in an environment is archived like any other, but the
+  environment keeps serving it until its next publish, which drops it. Restore it before then if it should stay.
 - **Never a whole namespace by accident.** If a source file in the push has no entries, the push is refused
-  (`VALIDATION_FAILED` with `emptySourcePrune`) instead of deleting every key in that namespace. Emptying a namespace
+  (`VALIDATION_FAILED` with `emptySourcePrune`) instead of archiving every key in that namespace. Emptying a namespace
   is done in the Translify web app.
-- **Exactly the list you confirmed.** The CLI always runs a dry run first, shows the keys it would delete and asks
+- **Exactly the list you confirmed.** The CLI always runs a dry run first, shows the keys it would archive and asks
   for confirmation. The real push sends a digest of that list; if the server's list differs by then (keys added,
-  removed or published in between), it refuses with `ORPHANS_CHANGED` and writes nothing. A server too old to return
+  removed, archived or restored in between), it refuses with `ORPHANS_CHANGED` and writes nothing. A server too old to return
   the digest makes `--prune` refuse.
 - **No silent prune in CI.** Without a terminal, `--prune` is refused unless you pass `--yes`.
-- **Atomic.** The whole push, deletions included, is one transaction: if anything fails, nothing is written.
+- **Atomic.** The whole push, archives and restores included, is one transaction: if anything fails, nothing is written.
 
 `--yes` confirms whatever that run's dry run lists, so in CI review the list before it runs unattended. One way:
 show the orphans on pull requests and prune on `main`.
 
 ```yaml
-# on pull_request: list what a prune would delete, change nothing
+# on pull_request: list what a prune would archive, change nothing
 - run: npx translify push --prune --dry-run
   env:
     TRANSLIFY_SECRET_KEY: ${{ secrets.TRANSLIFY_SECRET_KEY }}
@@ -364,7 +368,7 @@ The server's error `code` decides the exit code first; the HTTP status is only u
 | `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. |
+| `VALIDATION_FAILED` with `emptySourcePrune` | 1 | `--prune` was refused because a source file in the push has no entries (it would archive 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. |
@@ -377,7 +381,7 @@ The server's error `code` decides the exit code first; the HTTP status is only u
 | `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. |
+| `ORPHANS_CHANGED` | 1 | The orphan list changed between the dry run and the real push (keys were added, removed, archived or restored). 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. |
 | `INVALID_CELLS` | 6 | `publish` refused: translations that would go live have placeholder errors. Nothing was published; the output lists them like `lint` does. Fix them in Translify, or re-run with `--allow-errors` to publish anyway (recorded in the activity log). |

package/dist/commands/push.js

@@ -42,10 +42,11 @@ const buildForm = (uploads, opts, dryRun, prune, pruneDigest) => {
  */
 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`);
+    // Every orphan is archived, live ones included: they keep serving until the next publish.
+    const archivable = preview.orphans.length;
+    if (opts.prune === true && archivable > 0) {
+        damage.push(`move ${archivable} key(s) and their translations to the trash (restorable for 30 days in Translify)`);
+    }
     if (opts.overwriteTargets === true) {
         const { project } = await api.get('/cli/v1/whoami');
         const overwritten = Object.entries(preview.locales)
@@ -90,12 +91,12 @@ export async function runPush(opts, deps) {
     }
     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. ' +
+        deps.err('This server cannot confirm a prune (its dry run returned no pruneDigest), so --prune would archive 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).
+    // Nothing would be archived 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));
@@ -111,10 +112,9 @@ export async function runPush(opts, deps) {
             }
         }
     }
-    // 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;
+    // With orphans the real push sends the digest of the list the user confirmed: if the server's orphan
+    // set differs it answers 409 ORPHANS_CHANGED and writes nothing. With none, there is nothing to prune.
+    const prune = opts.prune === true && preview.orphans.length > 0;
     const res = await deps.api.post(PUSH, buildForm(uploads, opts, false, prune, prune ? preview.pruneDigest : undefined));
     show(res, preview);
     return EXIT.ok;

package/dist/http.js

@@ -85,7 +85,7 @@ const describeBody = (status, body) => {
         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.';
+            return 'The orphans changed since the dry run (keys were added, removed, archived or restored 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':

package/dist/index.js

@@ -89,7 +89,7 @@ program
     .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('--prune', 'move keys missing from your source files to the Translify trash (restorable for 30 days); archives 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))

package/dist/render.js

@@ -14,8 +14,8 @@ export function summarizePush(res) {
         skippedFilled: 0,
         unknownKeys: 0,
         orphans: res.orphans.length,
-        publishedOrphans: res.orphans.filter((orphan) => orphan.published).length,
         pruned: res.pruned,
+        keysRestored: res.keysRestored ?? 0,
         staleReset: res.staleReset ?? 0,
     };
     for (const counts of Object.values(res.locales)) {
@@ -47,36 +47,36 @@ export function renderPush(res, view = {}) {
     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);
-    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`);
-    };
+    const restored = res.keysRestored ?? 0;
+    if (restored > 0) {
+        lines.push(pc.green(`${res.dryRun ? 'Would restore' : 'Restored'} ${restored} key(s) from the trash.`));
+    }
+    // A prune archives every orphan (it goes to the trash, purged 30 days later); `pruned` is what a dry
+    // run would archive or a real push did. A real prune can archive fewer than it listed when some
+    // orphans were archived from the web app meanwhile.
+    const listed = res.orphans;
     if (listed.length > 0) {
+        const meanwhile = listed.length - res.pruned;
         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)` : ''}:`;
+                ? `${listed.length} key(s) not in your source files would be moved to the trash:`
+                : `Moved ${res.pruned} key(s) that were not in your source files to the trash (restorable for 30 days${meanwhile > 0 ? `; ${meanwhile} already archived meanwhile` : ''}):`;
         lines.push(pc.yellow(`  ${header}`));
-        names(listed);
+        for (const orphan of listed.slice(0, MAX_ORPHANS))
+            lines.push(`    ${orphan.namespace}:${orphan.key}`);
+        if (listed.length > MAX_ORPHANS)
+            lines.push(`    …and ${listed.length - MAX_ORPHANS} more`);
         if (res.pruned === 0 && view.prune !== true)
-            lines.push(pc.dim('  Use --prune to delete them.'));
+            lines.push(pc.dim('  Use --prune to move them to the trash.'));
     }
-    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 move ${res.pruned} key(s) to the trash (restorable for 30 days).`));
     }
-    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).`));
+    if (res.pruned > 0 && !res.dryRun && listed.length === 0) {
+        lines.push(pc.yellow(`  Moved ${res.pruned} key(s) to the Translify trash (restorable for 30 days).`));
+    }
     return lines.join('\n');
 }
 const MAX_VALUE = 80;

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.7.0';
+export const VERSION = '0.8.0';
 export const USER_AGENT = `translify-cli/${VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chesterbrains/translify-cli",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Push, pull and publish Translify translations from your repository",
   "license": "MIT",
   "repository": {