@blocofy/cli 0.11.0 → 0.13.0

package/README.md

@@ -63,13 +63,15 @@ Show which site a command in `[dir]` would hit (verified), without writing anyth
 ```
 blocofy theme dev [dir] [--port <n>] [--no-sync] [--name <name>]
 ```
-Start a dev server and print 3 auto-reloading views — Local, live-domain Preview, and the theme
-Editor. Press `l` / `p` / `e` to open each, `q` to quit. Edit a file and save → every open view
-reloads. Saves sync to a **draft** theme only (never the live site). `dir` defaults to cwd.
+Start a local dev server that renders your local theme files with the site's live content.
+Press `l` to open it, `q` to quit. Edit a file and save → the view reloads. Saves sync to a
+**draft** theme only (never the live site). `dir` defaults to cwd. The platform's remote preview
+and editor views for this command are retired; to share a draft page, create a preview link for
+it (v1 API `POST /themes/{id}/preview-links` or MCP `create_preview_link`; one page per link).
 The target site is verified once at start; a long session keeps that target (restart it after
 changing credentials, context or the project binding).
 - `--port <n>` — local port (default 3030).
-- `--no-sync` — local preview only (skip draft sync + remote views).
+- `--no-sync` — local preview only (skip draft sync).
 - `--name <name>` — name the draft when it is first created (ignored if it already exists).
 
 ```
@@ -94,13 +96,20 @@ the admin panel, never touching the live site. Publish it with `blocofy theme pu
 - `--yes` — confirm a `--live` push without prompting (CI/agents).
 - `--instance <handle>` — push to a specific theme by its handle (safe targeted write — no
   live-confirmation prompt).
-- `--name <name>` — name the new draft (draft mode only; ignored on `--live`/`--instance`).
+- `--name <name>` — name the new draft (draft mode only; ignored on `--live`/`--instance`). A draft
+  push reuses the existing CLI draft whatever its name; then the push says `--name` was not applied
+  and prints the `blocofy theme rename` command for it.
 - `--dry-run` / `--validate` — check the push on the server without writing; the two flags are
   aliases. The dry run covers exactly the files the push would send (remote-only files it keeps
   included; with `--prune`, without the ones it would remove). A current platform plans the whole
   deploy and prints the target, its pointer version and what happens to each file
   (`+` created, `~` updated, `-` removed; unchanged files are counted).
-- `--diff` — show what a push would change vs the target (read-only), then stop.
+- `--diff` — show what a push would change vs the target (read-only), then stop. A draft push
+  compares with the CLI draft it writes to (named by handle); with no CLI draft yet, with the live
+  theme (the push would create the draft). `--live` compares with live, `--instance` with that theme.
+
+After a draft push the CLI prints the draft it wrote to (`Draft: <handle> "<name>" (new)` or
+`(existing CLI draft, updated)`) and the `blocofy theme publish --instance <handle>` command.
 - `--idempotency-key <k>` — attach a key so a retried push is not double-applied.
 - `--prune` — also remove target files that no longer exist locally (`locales/` included);
   lists them first, and on the live theme asks to confirm (non-interactive shells add `--yes`).
@@ -226,6 +235,43 @@ get a random UUID. Transient failures (429/502/503/504, network) are retried aga
 idempotency key, so a retry replays the same batch. Exit 0 on success (or "No changes" when
 every item was already recorded).
 
+### Translations
+
+```
+blocofy translations export --locale <tag> --out <file> [--force] [--format json|xliff] [--only all|missing|stale|pending] [--json]
+blocofy translations import <file.json|file.xlf> [--dry-run] [--publish] [--on-source-change skip|apply] [--json]
+```
+`export` writes every text of one language that needs translating (pages, image texts, records,
+menus, site settings, theme texts) to ONE file. The platform answers in windows; the command
+follows every window until the last and merges them, then lists what was left out and why.
+`--format xliff` writes XLIFF 1.2 for translation tools (the platform's own dialect, byte for
+byte); `--only pending` limits the file to texts that are missing or need an update. The export
+asks for every kind, so the API key needs the read scopes of all of them: `pages:read`,
+`content:read`, `navigation:write` (menus have no read scope), `settings:read`, `themes:read` and
+`models:read`; a key without one of them is refused for the whole export. An existing `--out` file
+is never replaced silently: the command refuses before any request unless `--force` is given, and
+the file is written through a temporary file and a rename.
+
+`import` reads a JSON or XLIFF package, drops empty translations, and sends the rest as JSON in
+chunks of at most 500 units (a page or record is never split; one group of up to 5,000 units is
+sent whole). Every chunk is checked locally before the first request. It prints the count per
+state (written, unchanged, empty, source changed, target changed, invalid, blocked). New pages and
+records are created as drafts and page content goes to the draft; menus, site settings, theme texts,
+a live record's text and a live page's title and SEO texts change at once (a live page's URL only
+with `--publish`, once that page's publish succeeded). `--publish` also publishes the pages and records this
+import wrote (needs `pages:write` and `content:write`) and reports what could not be published;
+`--dry-run` writes nothing and reports what would change. The API key needs the write scopes of
+the kinds in the package. A refusal (for example an invalid text) exits 2 with the server's error
+JSON on stderr; if a later chunk fails, the chunks already written stay written, the report of
+those chunks (counts, what was published or held back, a failed cache refresh) is printed before the
+error (`--json`: one object with `"stopped": true` on stdout), and running the command again is safe
+(written texts answer "unchanged"). Transient failures (429/502/503/504, network) are retried, except
+for a chunk imported with `--publish`: a resend could not see what the first attempt already
+published, so such a chunk is sent once. A 5xx or a lost connection stops the command with
+`TRANSLATIONS_IMPORT_OUTCOME_UNKNOWN` (exit 1), naming the chunk that may or may not have been
+applied and published; a 429 stops it with `TRANSLATIONS_IMPORT_NOT_APPLIED` (exit 1), since that
+chunk was not applied.
+
 ### Settings
 
 ```
@@ -408,10 +454,37 @@ Retries: network errors and HTTP 429/502/503/504 are retried up to 3 times (`Ret
 honoured, max 30s per wait; else 0.3s/0.9s/2s), resending the identical request (`pages push`
 carries one `x-idempotency-key` per push). HTTP 500 is never retried, nor is a `theme push` dry
 run answered 502 `readback_unverified` (a verdict on a rolled-back plan, not a transient failure).
+`translations import --publish` is never retried either: a resend could not see what the first
+attempt already published, so a failed chunk stops the command with
+`TRANSLATIONS_IMPORT_OUTCOME_UNKNOWN` (5xx, network) or `TRANSLATIONS_IMPORT_NOT_APPLIED` (429).
 Each retry prints a notice on stderr.
 
 ## Changelog
 
+- **0.13.0** — Draft push names its target (customer items PS-22/PS-23/PS-26).
+  - `theme push` (draft) prints the draft it wrote to — handle, name, new or existing — and
+    `blocofy theme publish --instance <handle>`. When it updated the existing CLI draft, it says
+    `--name` was not applied and prints the rename command.
+  - **Behaviour change:** `theme push --diff` without `--live`/`--instance` now compares with the CLI
+    draft the push writes to (found read-only via the site status, never provisioned), not with the
+    live theme. With no CLI draft yet it says so and compares with live. Release it after the
+    platform's PS-22 fix (uncached theme reads): before that fix a draft read could return its
+    pre-push files for up to five minutes.
+  - `theme dev` help no longer lists the retired live-domain and editor views.
+  - `TARGET_BINDING_REQUIRED` also names `blocofy link <dir>` for env credentials.
+- **0.12.0** — Translation packages (#925).
+  - `blocofy translations export --locale <tag> --out <file> [--format json|xliff] [--only …]`
+    writes every text of one language that needs translating to one JSON or XLIFF 1.2 file. It
+    follows every export window and lists what the platform left out, by reason.
+  - `blocofy translations import <file> [--dry-run] [--publish] [--on-source-change skip|apply]`
+    reads a JSON or XLIFF package and imports it in chunks of at most 500 units (a page or record
+    is never split, up to 5,000 units). It prints the count per state, what was published, and
+    whether the site cache could not be refreshed. A chunk imported with `--publish` is never
+    resent automatically: when it gets no definite answer the command stops with
+    `TRANSLATIONS_IMPORT_OUTCOME_UNKNOWN` (a 429: `TRANSLATIONS_IMPORT_NOT_APPLIED`), exit 1, names
+    the chunk, and running it again is safe. A run that stops part-way still prints the report of
+    the chunks done before it.
+  - `export` refuses an existing `--out` file unless `--force`.
 - **0.11.0** — One named context per site, one explicit target (customer item 1.8).
   The dev token and the v1 API key remain two separate credentials; a context references both.
   - **Breaking:** conflicting context choices now fail closed. When `BLOCOFY_CONTEXT`, the env
@@ -566,11 +639,9 @@ files and sends them to the platform's dev-render endpoint (`/api/dev/render`).
 renders them with the site's **live data** and returns HTML — so the CLI ships no rendering
 engine and you see exactly the production output.
 
-It also continuously syncs your local files to a **draft theme** so you can view the same work
-three ways — the local preview, a shareable live-domain preview link, and the admin theme
-editor — without affecting your published theme. Save a file and **every open view reloads**
-(the platform-rendered pages connect back to the local dev server's reload channel). Publish
-the draft from the theme editor when you're ready.
+It also continuously syncs your local files to a **draft theme**, so the same work can be opened
+in the admin theme editor without affecting your published theme. Save a file and the local view
+reloads. Publish the draft from the theme editor, or with `blocofy theme publish`, when you're ready.
 
 Credentials live in `~/.blocofy/credentials.json` (contexts, no secrets) + either
 `~/.blocofy/secrets.json` (0600) or the macOS keychain — written by `blocofy login`, or the

package/bin/blocofy.mjs

@@ -9,7 +9,7 @@
  * livereload. No monorepo required.
  */
 import { randomUUID } from "node:crypto";
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { join, relative, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -49,13 +49,29 @@ import {
 import { startDevServer } from "../lib/dev-server.mjs";
 import { readLocalTemplates } from "../lib/local-theme.mjs";
 import { CliRefusal, DEFAULT_API_URL, decidePageMediaUses, fetchPageMediaUses, isValidApiKey } from "../lib/media-uses.mjs";
+import {
+  ImportNotApplied,
+  ImportOutcomeUnknown,
+  TRANSLATION_ONLY,
+  XLIFF_MAX_CHARS,
+  addImportReport,
+  chunkPackage,
+  emptyImportTally,
+  exportAllTranslations,
+  exportSkipLines,
+  fitChunksToBodyCap,
+  importSummaryLines,
+  importTranslationChunk,
+  readPackageFile,
+  toXliff,
+} from "../lib/translations.mjs";
 import { githubNote, healthAdvice, retryNotice, statusLine, syncScopeNote } from "../lib/messages.mjs";
 import { promptSecret } from "../lib/secret-prompt.mjs";
 import { MANIFEST_PATH, buildManifest, validateSiteStateTree, verifyManifest } from "../lib/site-state.mjs";
 import { SiteStateFsError, hashBuffer, readSiteStateTree, stagedWriteTree } from "../lib/site-state-fs.mjs";
 import { migrateSiteState } from "../lib/site-migrate.mjs";
 import { applySiteState, downloadAssetBytes, fetchSiteStateExport, planSiteState, publishSiteState, uploadMediaAsset } from "../lib/site-state-client.mjs";
-import { diffTheme, fetchCanonicalSupport, fetchDevSession, fetchSiteStatus, publishInstance, pullTheme, pushTheme, renameInstance } from "../lib/theme-sync.mjs";
+import { diffTheme, fetchCanonicalSupport, fetchDevSession, fetchSiteStatus, findCliDraft, publishInstance, pullTheme, pushTheme, renameInstance } from "../lib/theme-sync.mjs";
 import { isAffirmative, livePushDecision, resolvePushMode } from "../lib/confirm.mjs";
 import { hyperlink, openUrl } from "../lib/term.mjs";
 import { isValidToken, isValidUrl, normalizeUrl } from "../lib/validate.mjs";
@@ -89,6 +105,8 @@ const KNOWN = {
   sitePlan: ["target", "mode", "accept-live-effects"],
   siteApply: ["target", "mode", "accept-live-effects"],
   sitePublish: ["target", "mode", "yes"],
+  translationsExport: ["locale", "out", "format", "only", "force"],
+  translationsImport: ["dry-run", "publish", "on-source-change"],
 };
 // CF-T1/T2: every command accepts the global `--context <name>` and `--json` (machine-readable refusals).
 function parseArgsOrExit(rest, known) {
@@ -160,14 +178,15 @@ Usage
       Show which site a command in [dir] would hit (verified), without writing anything.
 
   blocofy theme dev [dir] [--port <n>] [--no-sync] [--name <name>]
-      Start a dev server and print 3 auto-reloading views — Local, live-domain
-      Preview, and the theme Editor. Press l / p / e to open each, q to quit.
-      Edit a file and save → every open view reloads. Saves sync to a DRAFT theme
-      only (never the live site). (dir defaults to cwd)
+      Start a local dev server that renders your local theme files with the site's
+      live content. Press l to open it, q to quit. Edit a file and save → the view
+      reloads. Saves sync to a DRAFT theme only (never the live site). (dir defaults to cwd)
+      The platform's remote preview and editor views for this command are retired; to
+      share a draft page, create a preview link for it (v1 API / MCP create_preview_link).
       The target site is verified ONCE at start; a long session keeps that target (restart
       it after changing credentials, context or the project binding).
         --port <n>   local port (default 3030)
-        --no-sync    local preview only (skip draft sync + remote views)
+        --no-sync    local preview only (skip draft sync)
         --name <name>  name the draft when it is first created (ignored if it already exists)
 
   blocofy theme pull [dir] [--draft] [--instance <handle>]
@@ -270,6 +289,36 @@ Usage
       1 usage/auth/network/5xx; 2 the server refused (4xx) — the {error} JSON
       is printed to stderr.
 
+  blocofy translations export --locale <tag> --out <file> [--force] [--format json|xliff]
+                              [--only all|missing|stale|pending] [--json]
+      Write every text of one language that needs translating (pages, image texts, records,
+      menus, site settings, theme texts) to ONE file (v1 API). The export asks for every kind,
+      so the API key needs the read scopes of all of them: pages:read, content:read,
+      navigation:write (menus have no read scope), settings:read, themes:read and models:read.
+      The platform answers in windows; the command follows every window and merges them, then
+      lists what was left out and why. --format xliff writes XLIFF 1.2 for translation tools.
+        --only pending   only texts that are missing or need an update
+        --force          replace --out if it already exists (refused otherwise, before any request)
+
+  blocofy translations import <file.json|file.xlf> [--dry-run] [--publish]
+                              [--on-source-change skip|apply] [--json]
+      Import a translated package (v1 API; the write scopes of the kinds, and with --publish
+      also pages:write and content:write). Empty translations are skipped; the rest is sent in
+      chunks of at most 500 units (a page or record is never split, up to 5,000 units). Prints
+      the count per state. New pages and records are created as drafts and page content goes to
+      the draft; menus, site settings, theme texts, a live record's text and a live page's title
+      and SEO texts change at once.
+        --dry-run        write nothing; report what would change
+        --publish        also publish the pages and records this import wrote. A publishing
+                         chunk is never resent automatically: if it gets no definite answer (or a
+                         429) the command stops and says so; running it again is safe.
+        --on-source-change apply  also write texts whose source changed since the export
+                                  (default: skip)
+      If a chunk fails, the report of the chunks done before it is printed first (--json: one
+      object with "stopped": true on stdout).
+      Exit codes: 0 done; 1 usage/file/network/5xx (or a publishing chunk that was stopped);
+      2 the server refused (4xx) — the {error} JSON is printed to stderr.
+
   blocofy settings pull [dir]
   blocofy settings push [dir] (--instance <handle> | --live [--yes])
       Download / upload config/settings.json (theme tokens/settings + color schemes).
@@ -904,7 +953,7 @@ async function themePush(rest) {
   // CF-T2: `--diff` and `--dry-run` are reads; every other push is a remote mutation (binding required). The
   // target is verified (whoami, both pairs, binding) before the first theme request — no best-effort swallow.
   const readOnly = Boolean(flags.diff) || dryRun;
-  const opMode = flags.diff ? `read · diff vs ${instanceFlag ? `instance ${instanceFlag}` : "live"}` : dryRun ? `read · dry run (${mode === "instance" ? `instance ${instance}` : mode})` : mode === "instance" ? `instance ${instance}` : mode;
+  const opMode = flags.diff ? `read · diff vs ${instanceFlag ? `instance ${instanceFlag}` : mode === "draft" ? "CLI draft" : "live"}` : dryRun ? `read · dry run (${mode === "instance" ? `instance ${instance}` : mode})` : mode === "instance" ? `instance ${instance}` : mode;
   const target = await prepareTarget({ command: "theme push", commandClass: readOnly ? "read" : "remote-mutation", dir, flags, needs: "dev", mode: `${opMode}${flags.prune && !readOnly ? " · prune" : ""}` });
   const creds = target.dev;
   // 0.5.0: her push'a otomatik idempotency key — kanonik dal (protokol + key) ancak böyle seçilir; key
@@ -915,12 +964,18 @@ async function themePush(rest) {
   // ad-alanlar, önek EKLENMEZ.
   const idempotencyKey = typeof flags["idempotency-key"] === "string" ? flags["idempotency-key"] : `cli-${randomUUID()}`;
 
-  // `--diff`: read-only preview vs the LIVE theme (or --instance). No write; the draft target is not
-  // diffable (a draft GET would PROVISION the draft server-side — a read-only command must not mutate).
+  // `--diff`: read-only preview vs what the push would write to. PS-26: a draft push writes to the CLI draft, so
+  // that draft is found via `/api/dev/site` and diffed by handle — never via `?draft=1`, which PROVISIONS a draft
+  // server-side (a read-only command must not mutate). With no CLI draft yet the push would create one: vs live.
   if (flags.diff) {
     const diffTarget = ` of ${siteLabel(target.identity.site)}`;
-    const d = await diffTheme({ dir, url: creds.url, token: creds.token, instance: instanceFlag, onRetry });
-    console.log(instanceFlag ? `Diff vs theme ${instanceFlag}${diffTarget}:` : `Diff vs the LIVE theme${diffTarget} (push default writes to a DRAFT):`);
+    const cliDraft = mode === "draft" ? findCliDraft(await fetchSiteStatus({ url: creds.url, token: creds.token, onRetry })) : null;
+    const diffInstance = instanceFlag ?? cliDraft?.id ?? null;
+    const d = await diffTheme({ dir, url: creds.url, token: creds.token, instance: diffInstance, onRetry });
+    if (instanceFlag) console.log(`Diff vs theme ${instanceFlag}${diffTarget}:`);
+    else if (cliDraft) console.log(`Diff vs draft ${cliDraft.id}${cliDraft.name ? ` "${cliDraft.name}"` : ""}${diffTarget} (the CLI draft this push writes to):`);
+    else if (mode === "draft") console.log(`No CLI draft yet — this push would create one. Diff vs the LIVE theme${diffTarget}:`);
+    else console.log(`Diff vs the LIVE theme${diffTarget}:`);
     const total = d.added.length + d.changed.length + d.removed.length;
     if (total === 0) {
       console.log("No differences — local theme matches the target.");
@@ -1092,8 +1147,15 @@ async function themePush(rest) {
     }
     if (result.convergence === "converged") console.log("  (already applied by an earlier push with the same idempotency key)");
     if (mode === "draft") {
+      const h = typeof result.targetInstance === "string" ? result.targetInstance : null;
+      const label = result.targetName ? ` "${result.targetName}"` : "";
+      if (h) console.log(result.newDraft ? `Draft: ${h}${label} (new)` : `Draft: ${h}${label} (existing CLI draft, updated)`);
+      // PS-22: the server reuses the CLI draft whatever its name; --name only names a draft this push creates.
+      if (name && result.newDraft !== true) {
+        console.log(`Note: --name was not applied — this push updated the existing CLI draft${h ? ` ${h}` : ""}. Rename it with:  blocofy theme rename ${h ?? "<handle>"} "${name}"`);
+      }
       console.log("Preview & publish it in the admin panel: Theme -> Theme library -> \"Open in editor\".");
-      console.log("Publish it live with:  blocofy theme publish");
+      console.log(`Publish it live with:  blocofy theme publish${h ? ` --instance ${h}` : ""}`);
     }
     return;
   }
@@ -2129,6 +2191,169 @@ async function status(rest) {
   console.log("");
 }
 
+// ── translations (#925): one language's texts as a package file, and back ──────────────────────────────────
+
+const TRANSLATIONS_EXPORT_USAGE = "blocofy translations export --locale <tag> --out <file> [--force] [--format json|xliff] [--only all|missing|stale|pending] [--json]";
+const TRANSLATIONS_IMPORT_USAGE = "blocofy translations import <file.json|file.xlf> [--dry-run] [--publish] [--on-source-change skip|apply] [--json]";
+
+function usageExit(usage) {
+  console.error(`Usage: ${usage}`);
+  process.exit(1);
+}
+
+const outExists = (out) =>
+  Object.assign(new Error(`${out} already exists. Nothing was requested or written. Choose another --out file, or add --force to replace it.`), { code: "TRANSLATIONS_OUT_EXISTS", details: { file: out } });
+
+/** Write `text` to `out` through a temp file + rename, so `out` is never left half-written. */
+function writeOutFile(out, text, force) {
+  const temp = `${out}.${process.pid}.blocofy-tmp`;
+  try {
+    writeFileSync(temp, text, { flag: "wx" });
+    if (!force && existsSync(out)) throw outExists(out);
+    renameSync(temp, out);
+  } catch (error) {
+    rmSync(temp, { force: true });
+    throw error;
+  }
+}
+
+async function translationsExport(rest) {
+  const { flags, positionals } = parseArgsOrExit(rest, KNOWN.translationsExport);
+  const locale = typeof flags.locale === "string" ? flags.locale : null;
+  const out = typeof flags.out === "string" ? resolve(flags.out) : null;
+  const format = flags.format === undefined ? "json" : flags.format;
+  const only = flags.only === undefined ? "all" : flags.only;
+  const force = flags.force === true;
+  if (!locale || !out || positionals.length > 0 || (format !== "json" && format !== "xliff") || !TRANSLATION_ONLY.includes(only)) usageExit(TRANSLATIONS_EXPORT_USAGE);
+  // A file the customer may have filled in is never replaced silently.
+  if (!force && existsSync(out)) throw outExists(out);
+  // A read of the site; the package goes to --out, never into the project tree (so no binding is needed or written).
+  const { apiUrl, apiKey } = (await prepareTarget({ command: "translations export", commandClass: "read", dir: process.cwd(), flags, needs: "api", mode: `read · ${locale}` })).api;
+  const { pkg, skipped } = await exportAllTranslations({ apiUrl, apiKey, locale, only, onRetry, onPage: ({ page, units }) => console.error(`Export: request ${page}, ${units} unit(s) so far`) });
+  // toXliff refuses a text XML cannot carry BEFORE anything is written.
+  const text = format === "xliff" ? toXliff(pkg) : `${JSON.stringify(pkg, null, 2)}\n`;
+  writeOutFile(out, text, force);
+  if (format === "xliff" && text.length > XLIFF_MAX_CHARS) {
+    console.error(`Warning: this XLIFF file is over ${XLIFF_MAX_CHARS.toLocaleString("en-US")} characters and cannot be imported back. Export with --format json, or a smaller scope such as --only pending.`);
+  }
+  if (flags.json) {
+    console.log(JSON.stringify({ file: out, format, target_locale: pkg.target_locale, units: pkg.units.length, skipped }));
+    return;
+  }
+  console.log(`Exported ${pkg.units.length} unit(s) for ${pkg.target_locale} to ${out} (${format === "xliff" ? "XLIFF" : "JSON"}).`);
+  const skipLines = exportSkipLines(skipped);
+  if (skipLines.length > 0) {
+    console.log("Left out:");
+    for (const line of skipLines) console.log(`  - ${line}`);
+  }
+}
+
+/** The one `--json` shape of an import run: complete, stopped part-way, or with nothing to send. */
+function importJson(tally, { dryRun, publish, locale, chunks, chunksDone, caches, splitGroups, stopped }) {
+  return {
+    dry_run: dryRun,
+    target_locale: locale,
+    chunks,
+    chunks_done: chunksDone,
+    stopped,
+    counts: tally.counts,
+    created: tally.created,
+    stamped: tally.stamped,
+    publication: !dryRun && publish ? { published: tally.published, blocked: tally.publishBlocked } : null,
+    publish_skipped: tally.publishSkipped,
+    notes: tally.notes,
+    hints: tally.hints,
+    cache: caches,
+    split_groups: splitGroups,
+  };
+}
+
+async function translationsImport(rest) {
+  const { flags, positionals } = parseArgsOrExit(rest, KNOWN.translationsImport);
+  const onSourceChange = flags["on-source-change"] === undefined ? "skip" : flags["on-source-change"];
+  if (positionals.length !== 1 || (onSourceChange !== "skip" && onSourceChange !== "apply")) usageExit(TRANSLATIONS_IMPORT_USAGE);
+  const file = resolve(positionals[0]);
+  const dryRun = flags["dry-run"] === true;
+  const publish = flags.publish === true;
+  // Everything local is checked before the first request: the file, its chunks, every chunk's body size.
+  let pkg;
+  let chunked;
+  try {
+    pkg = readPackageFile(readFileSync(file, "utf8"), file);
+    chunked = chunkPackage(pkg);
+    chunked.chunks = fitChunksToBodyCap(chunked.chunks);
+  } catch (error) {
+    console.error(`Cannot read translation package ${file}: ${String(error?.message ?? error).replace(/\.?$/, ".")} Nothing was sent.`);
+    process.exit(1);
+  }
+  const { chunks, skippedEmpty, splitGroups } = chunked;
+  let tally = emptyImportTally();
+  tally.counts.skipped_empty += skippedEmpty;
+  const caches = [];
+  let done = 0;
+  const shape = { dryRun, publish, locale: pkg.target_locale, chunks: chunks.length, caches, splitGroups };
+  if (chunks.length === 0) {
+    if (flags.json) console.log(JSON.stringify(importJson(tally, { ...shape, chunksDone: 0, stopped: false })));
+    else console.log("Every translation in the file is empty; nothing to import. Nothing was sent.");
+    return;
+  }
+  const mode = `${dryRun ? "dry run" : publish ? "write + publish" : "write"} · ${pkg.target_locale}`;
+  const { apiUrl, apiKey } = (await prepareTarget({ command: "translations import", commandClass: dryRun ? "read" : "remote-mutation", dir: process.cwd(), flags, needs: "api", mode })).api;
+  try {
+    for (const chunk of chunks) {
+      const answer = await importTranslationChunk({ apiUrl, apiKey, chunk, dryRun, publish, onSourceChange, onRetry });
+      tally = addImportReport(tally, answer);
+      if (answer?.cache !== undefined && answer.cache !== null) caches.push(answer.cache);
+      done += 1;
+      if (chunks.length > 1) console.error(`${dryRun ? "Checked" : "Imported"} ${done} of ${chunks.length} chunks`);
+    }
+  } catch (error) {
+    // What the chunks before the failure did (published pages, held drafts, a failed cache flush) is reported in
+    // full: a rerun answers `unchanged` for them and could never tell it again.
+    if (done > 0) {
+      if (flags.json) console.log(JSON.stringify(importJson(tally, { ...shape, chunksDone: done, stopped: true })));
+      else {
+        console.log(`Report for the ${done} of ${chunks.length} chunks done before the stop:`);
+        for (const line of importSummaryLines(tally, { dryRun, publish, locale: pkg.target_locale, splitGroups })) console.log(line);
+      }
+    }
+    if (!JSON_MODE) {
+      const invalid = error instanceof CliRefusal && Array.isArray(error.error?.details?.units) ? error.error.details.units : [];
+      if (invalid.length > 0) {
+        console.error("These texts were refused; fix the file and import again:");
+        for (const u of invalid.slice(0, 20)) console.error(`  ${u.id}: ${u.message ?? u.reason ?? "refused"}`);
+        if (invalid.length > 20) console.error(`  …and ${invalid.length - 20} more.`);
+      }
+      if (!dryRun && done > 0) {
+        console.error(`Import stopped after ${done} of ${chunks.length} chunks. The chunks before it were saved; running the same command again is safe (units already applied report as unchanged).`);
+      }
+    }
+    const details = { chunk: done + 1, chunks: chunks.length, reason: error?.reason };
+    if (error instanceof ImportOutcomeUnknown) {
+      throw Object.assign(
+        new Error(
+          `The import of chunk ${done + 1} of ${chunks.length} got no definite answer (${error.reason}) and was not resent, because it publishes: that chunk may or may not have been applied and published. Running the same command again is safe (units already applied report as unchanged).`,
+        ),
+        { code: "TRANSLATIONS_IMPORT_OUTCOME_UNKNOWN", details },
+      );
+    }
+    if (error instanceof ImportNotApplied) {
+      throw Object.assign(
+        new Error(
+          `The import of chunk ${done + 1} of ${chunks.length} was refused (${error.reason}, too many requests) and was not applied; it was not resent, because it publishes. Wait a moment and run the same command again (units already applied report as unchanged).`,
+        ),
+        { code: "TRANSLATIONS_IMPORT_NOT_APPLIED", details },
+      );
+    }
+    throw error;
+  }
+  if (flags.json) {
+    console.log(JSON.stringify(importJson(tally, { ...shape, chunksDone: done, stopped: false })));
+    return;
+  }
+  for (const line of importSummaryLines(tally, { dryRun, publish, locale: pkg.target_locale, splitGroups })) console.log(line);
+}
+
 const [first, ...rest] = args;
 
 function commandKey(a, b) {
@@ -2163,6 +2388,8 @@ const COMMANDS = {
   "site plan": sitePlan,
   "site apply": siteApply,
   "site publish": sitePublish,
+  "translations export": translationsExport,
+  "translations import": translationsImport,
 };
 
 if (first === "--version" || first === "-v") {

package/lib/args.mjs

@@ -8,8 +8,9 @@
  * Sonraki token'ı değer olarak almayan flag'ler. 0.8.0: `api-key` de boolean'dır — `login --api-key`
  * gizli prompt açar; `--api-key <değer>` sözdizimi bilerek YOKTUR (sır argv'ye ve shell geçmişine girmez).
  * CF-T1: `--keychain` (login) ve `--adopt` (link) de değersizdir. CF-T3: `--force` (pages push) da; gerekçesi `--reason <text>`.
+ * #925: `--publish` (translations import) da değersizdir.
  */
-const BOOLEAN_FLAGS = new Set(["draft", "live", "yes", "confirm", "no-sync", "dry", "dry-run", "validate", "diff", "help", "version", "api-key", "json", "strict", "write", "keychain", "adopt", "force"]);
+const BOOLEAN_FLAGS = new Set(["draft", "live", "yes", "confirm", "no-sync", "dry", "dry-run", "validate", "diff", "help", "version", "api-key", "json", "strict", "write", "keychain", "adopt", "force", "publish"]);
 
 /**
  * `known`: bu komutun kabul ettiği bayrak adları (Set). Verildiğinde bilinmeyen bir `--x`

package/lib/target.mjs

@@ -217,13 +217,16 @@ function isEmptyOrMissing(dir) {
  * Command-class policy (before any credential or network use). Returns `{ newBinding }`: true when a local-write
  * into a missing/empty unbound dir will record provenance after it succeeds.
  */
+/** PS-22 note: with env credentials there is no context to name — `link` binds to the site those credentials reach. */
+const ENV_LINK_HINT = (dir) => `; with BLOCOFY_URL + BLOCOFY_TOKEN set: blocofy link ${dir}`;
+
 export function enforceBindingPolicy({ commandClass, binding, dir, command }) {
   if (!COMMAND_CLASSES.has(commandClass)) throw new Error(`internal: unknown command class ${commandClass}`);
   if (binding) return { newBinding: false };
   if (commandClass === "remote-mutation") {
     throw new TargetError(
       "TARGET_BINDING_REQUIRED",
-      `\`${command}\` changes a site, but ${dir} is not bound to one. Nothing was sent. Bind it first: blocofy link ${dir} --context <name>`,
+      `\`${command}\` changes a site, but ${dir} is not bound to one. Nothing was sent. Bind it first: blocofy link ${dir} --context <name>${ENV_LINK_HINT(dir)}`,
       { dir },
     );
   }
@@ -231,7 +234,7 @@ export function enforceBindingPolicy({ commandClass, binding, dir, command }) {
     if (isEmptyOrMissing(dir)) return { newBinding: true };
     throw new TargetError(
       "TARGET_BINDING_REQUIRED",
-      `${dir} is not empty and not bound to a site. Nothing was written. Bind it first (blocofy link ${dir} --context <name>) or pull into an empty directory.`,
+      `${dir} is not empty and not bound to a site. Nothing was written. Bind it first (blocofy link ${dir} --context <name>${ENV_LINK_HINT(dir)}) or pull into an empty directory.`,
       { dir },
     );
   }

package/lib/theme-sync.mjs

@@ -322,9 +322,10 @@ export async function pushTheme({ dir, url, token, draft = false, instance = nul
   const remoteOnlyKept = [];
   const remoteOnlyRemoved = [];
   let probeInstance = instance;
+  let cliDraft = null;
   if (!instance && draft) {
-    const status = await fetchSiteStatus({ url, token, onRetry });
-    probeInstance = (status?.drafts ?? []).find((d) => d.source === "import")?.id ?? null;
+    cliDraft = findCliDraft(await fetchSiteStatus({ url, token, onRetry }));
+    probeInstance = cliDraft?.id ?? null;
   }
   let remote = {};
   if (probeInstance || !draft) {
@@ -391,7 +392,22 @@ export async function pushTheme({ dir, url, token, draft = false, instance = nul
     throw applyError(error);
   }
   if (!res.ok) throw applyError(await httpError(res));
-  return { ...(await res.json()), ...extras };
+  const applied = await res.json();
+  // PS-22: which theme received the files. A current server names it on the apply; an older one only in the plan
+  // (null for "a new draft"); oldest of all, the CLI draft looked up before the push is the one reused.
+  // A server whose plan carries no `newDraft` created one exactly when a draft push found no CLI draft to reuse.
+  const newDraft = typeof plan.newDraft === "boolean" ? plan.newDraft : Boolean(draft && !instance && cliDraft == null);
+  const targetInstance = applied.targetInstance ?? plan.targetInstance ?? (newDraft ? null : probeInstance) ?? null;
+  const targetName = newDraft ? name : cliDraft && cliDraft.id === targetInstance ? cliDraft.name ?? null : null;
+  return { ...applied, ...extras, targetInstance, newDraft, targetName };
+}
+
+/**
+ * The CLI draft a draft push writes into: the first `source: "import"` draft — `/api/dev/site` lists drafts by id,
+ * the server's `ensureDraftInstance` reuses the first non-live import instance by id. `null` = a push would create one.
+ */
+export function findCliDraft(status) {
+  return (status?.drafts ?? []).find((d) => d.source === "import") ?? null;
 }
 
 /**