@chesterbrains/translify-cli 0.7.0 → 0.8.1

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 }}
@@ -305,9 +309,97 @@ When the project has **Require review** turned on in Translify:
 - `publish` refuses when a translation that would go live has a placeholder error (a missing or extra placeholder, invalid ICU, a printf type mismatch). Nothing is published, the refused translations are listed like `lint` lists them, and the command exits 6. Warnings never block. On an environment with **Publish approved text only**, only approved translations count: one carried over from its last approved text never blocks. `--allow-errors` publishes anyway and reports how many went out with errors; the publish is recorded in the activity log with the override.
 - `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.
 
+## Webhooks
+
+A project's admins can add webhooks under **Integrations**. Translify calls them with `publication.created` every time
+an environment's live batch changes: a publish, a rollback or an unpublish (`batch.kind` says which). A publish whose
+result is identical to what is live emits nothing. `ping` is the test event, sent by "Send test" and by the
+verification dispatch that saves a GitHub webhook.
+
+Deliveries are made by a worker, not by the request that published: five attempts, waiting 1 minute, 5 minutes,
+30 minutes and 2 hours between them, then the delivery is `DEAD` and can be resent from the app. The log keeps 30
+days. The delivery id is the same on every attempt (`X-Translify-Delivery` and the payload's `id`), so a receiver that
+answers slowly and gets the retry can dedupe on it. Answer 2xx as soon as the request is accepted and do the work
+afterwards; the sender waits 10 seconds.
+
+### Payload
+
+```json
+{
+  "id": "<delivery id>",
+  "event": "publication.created",
+  "createdAt": "2026-10-25T14:02:11.000Z",
+  "project": { "id": "…", "slug": "shop", "name": "Shop" },
+  "environment": { "id": "…", "slug": "production", "name": "Production", "requireApproved": true },
+  "batch": {
+    "id": "…", "seq": 41, "kind": "PUBLISH",
+    "publishedCount": 1280, "addedCount": 3, "changedCount": 14, "removedCount": 0,
+    "withheldCount": 0, "errorCount": 0
+  },
+  "actor": { "type": "user", "id": "…", "name": "Anna Rossi" }
+}
+```
+
+`addedCount`, `changedCount` and `removedCount` are the batch's diff against the previous live batch: a first publish
+has everything in `addedCount`; an `UNPUBLISH` has `publishedCount: 0` and everything that went offline in
+`removedCount`. "Did anything change" is the sum of the three. `withheldCount` is what a `requireApproved` gate kept
+back, `errorCount` the cells published with placeholder errors (`--allow-errors`). `actor.type` is `user`, `apiKey`
+(a CLI publish; `name` is the key's name) or `system`. A `ping` carries `id`, `event`, `createdAt`, `project` and
+`webhook { id, target, destination }` only.
+
+### Verify a delivery
+
+Generic webhooks `POST` the payload as `application/json` to an `https://` URL on a public host, with:
+
+| Header | Value |
+| --- | --- |
+| `X-Translify-Event` | `publication.created` or `ping` |
+| `X-Translify-Delivery` | the delivery id, identical on every attempt |
+| `X-Translify-Timestamp` | unix seconds when the attempt was sent |
+| `X-Translify-Signature` | `v1=<hex hmac-sha256(secret, "<timestamp>.<body>")>` |
+| `User-Agent` | `translify-webhooks/1` |
+
+The signing secret (`whsec_…`) is shown once when the webhook is created. Verify over the raw body, compare in constant
+time and refuse a timestamp more than 300 s (5 minutes) away from now:
+
+```js
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+export function verify(rawBody, headers, secret) {
+  const timestamp = Number(headers['x-translify-timestamp']);
+  if (!Number.isFinite(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
+  const expected = `v1=${createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex')}`;
+  const given = Buffer.from(String(headers['x-translify-signature'] ?? ''));
+  const wanted = Buffer.from(expected);
+  return given.length === wanted.length && timingSafeEqual(given, wanted);
+}
+```
+
+### GitHub
+
+A webhook with the **GitHub** target sends a
+[`repository_dispatch`](https://docs.github.com/en/rest/repos/repos#create-a-repository-dispatch-event) instead:
+`POST https://api.github.com/repos/<owner>/<repo>/dispatches` with `event_type` `translify.publication` (or
+`translify.ping`) and the payload above as `client_payload`. No signature: GitHub authenticates the token.
+
+The token is a fine-grained personal access token with **Contents: Read and write** on that one repository (that is
+the permission `repository_dispatch` needs). Translify verifies it with a `translify.ping` dispatch before saving and
+refuses a token or repository GitHub rejects; the expiry GitHub reports is shown in the list from 14 days out.
+
+[`recipes/github-actions/translify-pull-on-publish.yml`](https://github.com/chesterbrains/translify-cli/blob/main/recipes/github-actions/translify-pull-on-publish.yml)
+is the workflow that closes the loop: on `translify.publication` it runs `translify pull --from env:<slug>` for the
+environment in the payload, commits, opens a pull request whose body carries the publish summary (batch, counts,
+actor), runs your build and merges. Two things to set after copying it: the repository setting **Allow GitHub Actions
+to create and approve pull requests** (Settings → Actions → General; without it the job token cannot open the PR),
+and the environment the repository follows: a literal in the job's `if:`, and the webhook limited to that environment
+in Translify, since every environment pulls into the same files. The workflow builds and merges inside the
+same run because a pull request opened with `GITHUB_TOKEN` never triggers other workflows. The
+[translify-examples](https://github.com/chesterbrains/translify-examples/blob/main/.github/workflows/translify-pull-on-publish.yml)
+repository runs this workflow against the demo project.
+
 ## CI (GitHub Actions)
 
-Store the key in the repository secrets as `TRANSLIFY_SECRET_KEY`. Two ready-made workflows live in
+Store the key in the repository secrets as `TRANSLIFY_SECRET_KEY`. Three ready-made workflows live in
 [`recipes/github-actions/`](https://github.com/chesterbrains/translify-cli/tree/main/recipes/github-actions); copy the
 one you need to `.github/workflows/` as it is.
 
@@ -319,8 +411,11 @@ one you need to `.github/workflows/` as it is.
 - [`translify-release.yml`](https://github.com/chesterbrains/translify-cli/blob/main/recipes/github-actions/translify-release.yml)
   is for apps that bundle translations at build time: `lint`, then `pull`, your build, then `publish` to the environment
   chosen in the Actions tab (or on a tag). Key scopes: `PULL` and `PUBLISH`.
+- [`translify-pull-on-publish.yml`](https://github.com/chesterbrains/translify-cli/blob/main/recipes/github-actions/translify-pull-on-publish.yml)
+  runs when Translify's GitHub webhook announces a publish: `pull --from env:<slug>` for the published environment,
+  commit, a pull request with the publish summary, your build, merge. Key scope: `PULL`. Setup in [Webhooks](#webhooks).
 
-Both use `npx -y translify`, so they follow every 0.x release; pin a version (`npx -y @chesterbrains/translify-cli@0.6`) if a breaking
+All three use `npx -y translify`, so they follow every 0.x release; pin a version (`npx -y @chesterbrains/translify-cli@0.6`) if a breaking
 release must not turn the workflow red on its own.
 
 Fail a pull request when local files drift from Translify:
@@ -364,7 +459,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 +472,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.1';
 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.1",
   "description": "Push, pull and publish Translify translations from your repository",
   "license": "MIT",
   "repository": {