@meterapp/glossa 0.6.0 → 0.7.1

package/README.md

@@ -6,6 +6,8 @@ The Glossa CLI. Push and pull translation files in any format, work the AI revie
 npx @meterapp/glossa login
 npx @meterapp/glossa push locales/en.json --project web
 npx @meterapp/glossa pull --project web --locale es,fr,de
+npx @meterapp/glossa sync --wait 10m    # push .glossa.json's files, wait for AI translation, pull every locale
+npx @meterapp/glossa check --wait 10m   # release gate: exit 1 unless this commit is fully translated
 npx @meterapp/glossa tasks
 npx @meterapp/glossa missing --locale es --out missing.json   # what an agent should translate, with keys and file paths
 npx @meterapp/glossa fill translations.json                   # write [{"unit","locale","text"}] back
@@ -40,6 +42,47 @@ an existing key instead, run `login --key gls_…`.
 
 In CI set `GLOSSA_API_KEY` (a workspace key, `gls_…`).
 
+### Sync
+
+`glossa sync` pushes every source file listed in `.glossa.json`, waits for the
+translate jobs those pushes started when the project is in `translation_mode`
+`ai` (up to `--wait`, default `10m`), then pulls every target locale of those
+files to its path and prints a summary (keys pushed, strings translated and
+flagged for review per locale, files written and changed). In `agent` mode it
+pulls what is there and tells you how many new strings wait for `missing` and
+`fill`.
+
+```json
+{ "project": "web", "files": ["messages/en.json"] }
+```
+
+It exits 1 when a push fails, Glossa can't read a file yet (a `learn_format`
+task is open), a translate job fails, or jobs are still running at the
+deadline; whatever was translated is written either way. `--no-pull` skips the
+pull, `--locale` and `--out` work as for `pull`, `--json` prints the result.
+In CI, run `sync` on each pull request, commit the locale files it changed, then
+run `check`.
+
+### Release gate
+
+`glossa check` blocks a deploy until it is safe to ship. It sends this commit's
+source files (the `files` in `.glossa.json`) and fails (exit 1) when any of
+their strings lacks a translation in a target locale, when strings were never
+pushed, or when a locale file in the tree differs from what `pull` writes now
+(compared by SHA-256, so no translation is downloaded). Only the commit's own
+strings count, so strings pushed later from other branches never block it.
+`--wait 10m` re-checks until running translation jobs finish. Set the policy
+in `.glossa.json`:
+
+```json
+{ "check": { "max_missing": 0, "min_coverage": 100, "require_reviewed": false, "stale": "fail" } }
+```
+
+Flags override it: `--max-missing n|none`, `--min-coverage pct`,
+`--require-reviewed`, `--stale fail|warn|ignore`, `--allow-pending`,
+`--locale es,fr`, `--out dir`, `--json`. In GitHub Actions it also writes a
+job summary. Details: https://getglossa.dev/docs/release-gate
+
 ### Cancel a background job
 
 `glossa cancel <job-id>` cancels queued or running work. `glossa cancel_job --job <job-id>`
@@ -48,3 +91,8 @@ cancellation is safe. An in-flight model request may finish; translation workers
 check cancellation before storing its results or beginning the next batch.
 Use `glossa get_job --job <job-id>` to inspect progress and final status, or
 `glossa list_jobs --status cancelled` to list cancelled jobs.
+
+Command help (`glossa sync --help`, `glossa check -h`, or any built-in command
+with `--help`) prints usage without running the command, calling the API, or
+writing files. Help for an API op reads only the public op catalog. Unknown
+commands and failed API calls exit with status 1.

package/bin/glossa.mjs

@@ -3,13 +3,14 @@
 // (`glossa <op> --field value` or `--json '{…}'`), read live from GET /api/v1,
 // so the CLI never lags the dashboard. push/pull/tasks/mcp are conveniences on top.
 import { spawn } from "node:child_process";
-import { readFileSync, writeFileSync, mkdirSync, existsSync, statSync, readdirSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { appendFileSync, readFileSync, writeFileSync, mkdirSync, existsSync, statSync, readdirSync } from "node:fs";
 import { homedir, hostname } from "node:os";
 import { dirname, join, relative, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { brotliCompressSync, brotliDecompressSync, constants as zlib } from "node:zlib";
 
-const VERSION = "0.6.0";
+const VERSION = "0.7.1";
 const DEFAULT_HOST = "https://getglossa.dev";
 const CONFIG_PATH = join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "glossa", "config.json");
 /** The last failed call, so `glossa feedback report --last` can attach it. */
@@ -109,7 +110,9 @@ export function parseArgs(argv) {
       positional.push(...argv.slice(i + 1));
       break;
     }
-    if (arg.startsWith("--")) {
+    if (arg === "--help" || arg === "-h") {
+      flags.help = true;
+    } else if (arg.startsWith("--")) {
       const [name, inline] = arg.slice(2).split(/=(.*)/s, 2);
       if (inline !== undefined) flags[name] = inline;
       else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) flags[name] = argv[++i];
@@ -381,54 +384,317 @@ export function fileText(out) {
   return out.content_brotli !== undefined ? brotliDecompressSync(Buffer.from(out.content_brotli, "base64")).toString("utf8") : out.content;
 }
 
-async function push(positional, flags) {
+/** One line about a push_file result, as push and sync print it. */
+function pushLine(path, result) {
+  if (result.status === "needs_format") return `${bold(path)}  ${red("unknown format")} — AI is learning it (task ${result.learn_format_task_id ?? "queued"}).`;
+  return (
+    `${bold(path)}  ${dim(result.format)}  +${result.keys.added} keys, ${result.keys.updated} updated, ${result.keys.removed} removed · ` +
+    `${result.units.created} new strings, ${result.units.merged_into_existing} deduped · ${result.translations_imported} translations imported` +
+    (result.keys_split ? ` · ${result.keys_split} keys split (their translations differed)` : "") +
+    (result.stale?.keys ? ` · ${result.stale.keys} source strings changed` +
+      (result.stale.retranslating ? dim(`, ${result.stale.retranslating} translations redone`) : "") +
+      (result.stale.kept_for_review ? dim(`, ${result.stale.kept_for_review} kept for review`) : "") : "") +
+    (result.translate_job_id ? dim(`  · translating (job ${result.translate_job_id.slice(0, 8)})`) : "") +
+    (result.translation_mode === "agent" && result.units.created > 0 ? dim("  · waiting for your agent: glossa missing") : "")
+  );
+}
+
+/** The project and source files push and sync work on: flags first, then .glossa.json. */
+function pushTarget(positional, flags) {
   const { root, config } = projectConfig();
   const project = flags.project ?? config.project;
   if (!project) fail("which project? Pass --project <slug> or add {\"project\": \"…\"} to .glossa.json.");
   const sources = positional.length ? positional : (config.files ?? []).map((f) => (typeof f === "string" ? f : f.source));
   if (!sources.length) fail("nothing to push. Pass files, or list them under \"files\" in .glossa.json.");
-  for (const file of expandFiles(sources, root)) {
-    const path = relative(root, file);
-    const result = await call("push_file", { project, path, ...fileBody(readFileSync(file, "utf8")), ...(flags.locale ? { locale: flags.locale } : {}), ...(flags.format ? { format: flags.format } : {}) });
+  return { root, config, project, files: expandFiles(sources, root) };
+}
+
+async function pushFile(project, root, file, flags) {
+  const path = relative(root, file);
+  const result = await call("push_file", { project, path, ...fileBody(readFileSync(file, "utf8")), ...(flags.locale ? { locale: flags.locale } : {}), ...(flags.format ? { format: flags.format } : {}) });
+  return { path, result };
+}
+
+async function push(positional, flags) {
+  const { root, project, files } = pushTarget(positional, flags);
+  for (const file of files) {
+    const { path, result } = await pushFile(project, root, file, flags);
     if (flags.json || !isTTY) {
       print(result, flags);
       continue;
     }
-    if (result.status === "needs_format") {
-      console.log(`${bold(path)}  ${red("unknown format")} — AI is learning it (task ${result.learn_format_task_id ?? "queued"}).`);
-    } else {
-      console.log(
-        `${bold(path)}  ${dim(result.format)}  +${result.keys.added} keys, ${result.keys.updated} updated, ${result.keys.removed} removed · ` +
-          `${result.units.created} new strings, ${result.units.merged_into_existing} deduped · ${result.translations_imported} translations imported` +
-          (result.keys_split ? ` · ${result.keys_split} keys split (their translations differed)` : "") +
-          (result.translate_job_id ? dim(`  · translating (job ${result.translate_job_id.slice(0, 8)})`) : "") +
-          (result.translation_mode === "agent" && result.units.created > 0 ? dim("  · waiting for your agent: glossa missing") : "")
-      );
-    }
+    console.log(pushLine(path, result));
     for (const warning of result.warnings ?? []) console.log(dim(`  ! ${warning}`));
   }
 }
 
-async function pull(positional, flags) {
-  const { root, config } = projectConfig();
-  const project = flags.project ?? config.project;
-  if (!project) fail("which project? Pass --project <slug> or add it to .glossa.json.");
+/** Writes every target locale of the project's parsed files (only `paths` when given); returns what it wrote. */
+async function pullFiles({ project, root, config, flags, paths = [], log = (line) => console.log(line) }) {
   const { files } = await call("list_files", { project });
   const projects = (await call("list_projects")).projects;
   const meta = projects.find((p) => p.slug === project || p.id === project);
   const locales = flags.locale ? String(flags.locale).split(",") : (config.locales ?? meta?.target_locales ?? []);
   if (!locales.length) fail("no locales: pass --locale es,fr or set target locales on the project.");
-  const outRoot = resolve(root, flags.out ?? ".");
-  for (const file of files.filter((f) => f.status === "parsed" && (!positional.length || positional.includes(f.path)))) {
+  const outRoot = resolve(root, flags.out ?? config.out ?? ".");
+  const written = [];
+  for (const file of files.filter((f) => f.status === "parsed" && (!paths.length || paths.includes(f.path)))) {
     for (const locale of locales) {
-      const out = await call("pull_file", { project, path: file.path, locale, missing: flags.missing ?? "source", approved_only: Boolean(flags["approved-only"]), compress: true });
+      const out = await call("pull_file", { project, path: file.path, locale, missing: flags.missing ?? config.missing ?? "source", approved_only: Boolean(flags["approved-only"] ?? config.approved_only), compress: true });
       const target = join(outRoot, out.path);
+      const text = fileText(out);
+      const changed = !existsSync(target) || readFileSync(target, "utf8") !== text;
       mkdirSync(dirname(target), { recursive: true });
-      writeFileSync(target, fileText(out));
-      console.log(`${green("wrote")} ${relative(process.cwd(), target)} ${dim(`(${out.keys} keys)`)}`);
+      writeFileSync(target, text);
+      written.push({ path: relative(process.cwd(), target), keys: out.keys, changed });
+      log(`${green("wrote")} ${relative(process.cwd(), target)} ${dim(`(${out.keys} keys${changed ? "" : ", unchanged"})`)}`);
       if (file.formats && /xcstrings|csv|xliff/.test(file.formats.slug ?? "")) break; // multi-locale: one write covers all
     }
   }
+  return { locales, written };
+}
+
+async function pull(positional, flags) {
+  const { root, config } = projectConfig();
+  const project = flags.project ?? config.project;
+  if (!project) fail("which project? Pass --project <slug> or add it to .glossa.json.");
+  await pullFiles({ project, root, config, flags, paths: positional });
+}
+
+// -------------------------------------------------------------------- sync
+const FINISHED = new Set(["done", "failed", "cancelled"]);
+
+/**
+ * Polls jobs until each has finished or the deadline passes. Returns them by outcome; `job`
+ * holds the last state read. A job that can't be read counts as failed.
+ */
+export async function waitForJobs(ids, { getJob, deadline, interval = 5_000, wait = sleep, now = Date.now, onProgress = () => undefined }) {
+  const state = new Map(ids.map((id) => [id, null]));
+  for (;;) {
+    for (const id of ids) {
+      if (state.get(id) && FINISHED.has(state.get(id).status)) continue;
+      try {
+        state.set(id, await getJob(id));
+      } catch (error) {
+        state.set(id, { id, status: "failed", error: error.message });
+      }
+    }
+    const open = ids.filter((id) => !FINISHED.has(state.get(id).status));
+    if (!open.length || now() + interval > deadline) {
+      const by = (pick) => ids.filter(pick).map((id) => state.get(id));
+      return { done: by((id) => state.get(id).status === "done"), failed: by((id) => ["failed", "cancelled"].includes(state.get(id).status)), pending: by((id) => !FINISHED.has(state.get(id).status)) };
+    }
+    onProgress(open.map((id) => state.get(id)));
+    await wait(interval);
+  }
+}
+
+/** Strings translated and flagged for review per locale, summed over translate jobs' output totals. */
+export function jobTotals(jobs) {
+  const totals = {};
+  for (const job of jobs) {
+    for (const [locale, t] of Object.entries(job?.output?.totals ?? {})) {
+      totals[locale] ??= { translated: 0, flagged: 0 };
+      totals[locale].translated += t.translated ?? 0;
+      totals[locale].flagged += t.flagged ?? 0;
+    }
+  }
+  return totals;
+}
+
+/**
+ * The verdict of a sync: exit code and the summary lines after the pull. Failed pushes stop
+ * before this; here a file Glossa can't read yet, a failed job or a job still running at the
+ * deadline makes the run fail (the pulled files hold what was done).
+ */
+export function syncVerdict({ pushed, jobs, waitedMs, written, agentStrings }) {
+  const problems = [];
+  const unreadable = pushed.filter((p) => p.result.status === "needs_format").map((p) => p.path);
+  if (unreadable.length) problems.push(`Glossa can't read ${unreadable.join(", ")} yet; resolve its learn_format task (glossa tasks --kind learn_format) and run sync again.`);
+  for (const job of jobs.failed) problems.push(`translate job ${String(job.id).slice(0, 8)} ${job.status}${job.error ? `: ${job.error}` : ""}.`);
+  if (jobs.pending.length) problems.push(`${jobs.pending.length} translate ${jobs.pending.length === 1 ? "job is" : "jobs are"} still running after ${Math.round(waitedMs / 1000)}s; run glossa sync again (or pass a longer --wait) to pull the rest.`);
+  const totals = jobTotals([...jobs.done, ...jobs.failed, ...jobs.pending]);
+  const translated = Object.values(totals).reduce((sum, t) => sum + t.translated, 0);
+  const flagged = Object.values(totals).reduce((sum, t) => sum + t.flagged, 0);
+  const keys = pushed.reduce((sum, p) => ({ added: sum.added + (p.result.keys?.added ?? 0), updated: sum.updated + (p.result.keys?.updated ?? 0), removed: sum.removed + (p.result.keys?.removed ?? 0) }), { added: 0, updated: 0, removed: 0 });
+  const changed = written.filter((w) => w.changed).length;
+  const lines = [
+    `pushed ${pushed.length} ${pushed.length === 1 ? "file" : "files"} (+${keys.added} keys, ${keys.updated} updated, ${keys.removed} removed)`,
+    ...(jobs.done.length + jobs.failed.length + jobs.pending.length
+      ? [`translated ${translated} strings in ${Object.keys(totals).length} locales${flagged ? `, ${flagged} flagged for review (glossa tasks)` : ""}`]
+      : []),
+    ...(agentStrings ? [`${agentStrings} new strings wait for your agent (agent mode): glossa missing, then glossa fill`] : []),
+    `wrote ${written.length} locale ${written.length === 1 ? "file" : "files"}, ${changed} changed`,
+  ];
+  return { ok: problems.length === 0, problems, lines, totals };
+}
+
+async function sync(positional, flags) {
+  const { root, config, project, files } = pushTarget(positional, flags);
+  const human = !flags.json;
+  const log = (line) => (human ? console.log(line) : undefined);
+  const pushed = [];
+  for (const file of files) {
+    const entry = await pushFile(project, root, file, flags);
+    pushed.push(entry);
+    log(pushLine(entry.path, entry.result));
+    for (const warning of entry.result.warnings ?? []) log(dim(`  ! ${warning}`));
+  }
+
+  const ids = [...new Set(pushed.map((p) => p.result.translate_job_id).filter(Boolean))];
+  const started = Date.now();
+  let waitMs;
+  try {
+    waitMs = parseDuration(flags.wait ?? "10m");
+  } catch (error) {
+    fail(error.message);
+  }
+  const jobs = ids.length
+    ? await waitForJobs(ids, {
+        getJob: (job) => call("get_job", { job }),
+        deadline: started + waitMs,
+        interval: flags.interval ? parseDuration(flags.interval) : 5_000,
+        onProgress: (open) => human && console.error(dim(`translating: ${open.length} ${open.length === 1 ? "job" : "jobs"} running · ${Math.max(0, Math.round((started + waitMs - Date.now()) / 1000))}s left`)),
+      })
+    : { done: [], failed: [], pending: [] };
+
+  // Glossa stores a file under its pattern (messages/{locale}.json), which pull_file takes.
+  const readable = pushed.filter((p) => p.result.status !== "needs_format").map((p) => p.result.path_pattern ?? p.path);
+  const { written } = flags["no-pull"] || !readable.length ? { written: [] } : await pullFiles({ project, root, config, flags, paths: readable, log });
+  const agentStrings = pushed.filter((p) => p.result.translation_mode === "agent").reduce((sum, p) => sum + (p.result.units?.created ?? 0), 0);
+  const verdict = syncVerdict({ pushed, jobs, waitedMs: Date.now() - started, written, agentStrings });
+  if (flags.json) print({ ok: verdict.ok, project, problems: verdict.problems, pushed: pushed.map((p) => ({ path: p.path, ...p.result })), jobs, totals: verdict.totals, written }, flags);
+  else {
+    console.log(bold(verdict.ok ? green(`✓ ${project} synced`) : red(`✗ ${project} sync incomplete`)));
+    for (const line of verdict.lines) console.log(`  ${line}`);
+    for (const problem of verdict.problems) console.log(red(`  ✗ ${problem}`));
+  }
+  if (!verdict.ok) process.exitCode = 1;
+}
+
+// ------------------------------------------------------------ release gate
+/** The digest check_sync compares by: sha256 of the UTF-8 text, CRLF read as LF. */
+export const syncHash = (text) => createHash("sha256").update(text.replace(/\r\n/g, "\n"), "utf8").digest("hex");
+
+/** "10m", "90s", "1h" or plain seconds, as milliseconds. */
+export function parseDuration(value) {
+  const match = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/.exec(String(value).trim());
+  if (!match) throw new Error(`--wait takes a duration like 90s, 10m or 1h (got "${value}").`);
+  return Number(match[1]) * { ms: 1, s: 1000, m: 60_000, h: 3_600_000 }[match[2] ?? "s"];
+}
+
+/**
+ * check_sync input from flags, then .glossa.json's "check" block, then the op's defaults, so a
+ * repository keeps its release policy next to its files and CI only adds what differs.
+ */
+export function checkInput(flags, config, sources) {
+  const policy = config.check ?? {};
+  const pick = (flag, key) => (flags[flag] !== undefined ? flags[flag] : policy[key]);
+  const maxMissing = pick("max-missing", "max_missing");
+  const minCoverage = pick("min-coverage", "min_coverage");
+  const locales = flags.locale ? String(flags.locale).split(",") : (policy.locales ?? config.locales);
+  const stale = pick("stale", "stale") ?? "fail";
+  if (!["fail", "warn", "ignore"].includes(stale)) throw new Error("--stale is fail, warn or ignore.");
+  return {
+    project: flags.project ?? config.project,
+    ...(locales?.length ? { locales: locales.map((l) => String(l).trim()).filter(Boolean) } : {}),
+    ...(sources.length ? { sources } : {}),
+    missing: flags.missing ?? config.missing ?? "source",
+    approved_only: Boolean(flags["approved-only"] ?? config.approved_only),
+    compare_files: stale !== "ignore",
+    ...(maxMissing !== undefined ? { max_missing: maxMissing === "none" || maxMissing === null ? null : Number(maxMissing) } : {}),
+    ...(minCoverage !== undefined ? { min_coverage: Number(minCoverage) } : {}),
+    ...(pick("require-reviewed", "require_reviewed") ? { require_reviewed: true } : {}),
+    stale,
+    ...(pick("allow-pending", "allow_pending") ? { allow_pending: true } : {}),
+  };
+}
+
+/**
+ * Compares the locale files in the tree with what pull writes now (the hashes check_sync returns)
+ * and folds the result into the verdict. A file whose source differs from Glossa's isn't compared.
+ */
+export function compareLocal(result, stale, hashOf) {
+  const differ = [];
+  for (const file of result.files) {
+    for (const out of file.outputs) {
+      if (file.source === "changed") out.status = "not_comparable";
+      else {
+        const local = hashOf(out.path);
+        out.status = local === null ? "missing" : local === out.sha256 ? "in_sync" : "stale";
+        if (out.status !== "in_sync") differ.push(out.path);
+      }
+    }
+  }
+  const failures = [...result.failures];
+  const warnings = [...result.warnings];
+  if (differ.length && stale !== "ignore") {
+    const message = `${differ.length} locale files differ from what \`glossa pull\` writes now: ${differ.slice(0, 5).join(", ")}${differ.length > 5 ? ", …" : ""}.`;
+    if (stale === "fail") failures.push({ code: "stale_files", message });
+    else warnings.push(message);
+  }
+  return { ...result, ok: failures.length === 0, failures, warnings, totals: { ...result.totals, stale: differ.length } };
+}
+
+/** GitHub Actions job summary, so a blocked deploy says why on the run page. */
+function checkSummary(result) {
+  const rows = result.locales.map((l) => `| ${l.locale} | ${l.strings} | ${l.translated} | ${l.reviewed} | ${l.missing} | ${l.coverage}% |`);
+  return [
+    `### Glossa: ${result.ok ? "✅ release is fully translated" : "❌ release blocked"} (${result.project})`,
+    "",
+    "| Locale | Strings | Translated | Reviewed | Missing | Coverage |",
+    "| --- | ---: | ---: | ---: | ---: | ---: |",
+    ...rows,
+    "",
+    ...result.failures.map((f) => `- **${f.code}**: ${f.message}`),
+    ...result.warnings.map((w) => `- ${w}`),
+    result.digest ? `\nTranslations digest \`${result.digest}\`` : "",
+    "",
+  ].join("\n");
+}
+
+async function check(flags) {
+  const { root, config } = projectConfig();
+  if (!(flags.project ?? config.project)) fail("which project? Pass --project <slug> or add it to .glossa.json.");
+  const sourceList = (config.files ?? []).map((f) => (typeof f === "string" ? f : f.source));
+  const sources = flags["no-sources"] ? [] : expandFiles(sourceList, root).map((file) => ({ path: relative(root, file), ...fileBody(readFileSync(file, "utf8")) }));
+  let input;
+  try {
+    input = checkInput(flags, config, sources);
+  } catch (error) {
+    fail(error.message);
+  }
+  const outRoot = resolve(root, flags.out ?? config.out ?? ".");
+  const hashOf = (path) => {
+    const full = join(outRoot, path);
+    return existsSync(full) ? syncHash(readFileSync(full, "utf8")) : null;
+  };
+  const deadline = flags.wait ? Date.now() + parseDuration(flags.wait) : 0;
+  const interval = flags.interval ? parseDuration(flags.interval) : 15_000;
+  let result;
+  for (;;) {
+    result = compareLocal(await call("check_sync", input), input.stale, hashOf);
+    // Waiting helps only what Glossa can still change: running jobs, translators, a push from another job.
+    if (result.ok || Date.now() + interval > deadline || result.failures.some((f) => f.code === "files_not_ready" || f.code === "stale_files")) break;
+    if (isTTY && !flags.json) console.error(dim(`waiting: ${result.failures.map((f) => f.code).join(", ")} · ${Math.round((deadline - Date.now()) / 1000)}s left`));
+    await sleep(interval);
+  }
+  if (process.env.GITHUB_STEP_SUMMARY) {
+    try {
+      appendFileSync(process.env.GITHUB_STEP_SUMMARY, checkSummary(result));
+    } catch {
+      // The summary is a convenience; the exit code is the gate.
+    }
+  }
+  if (!sources.length && sourceList.length === 0) result.warnings.push('No source files in .glossa.json "files": checked the source Glossa last received, not this commit.');
+  if (flags.json || !isTTY) print(result, flags);
+  else {
+    console.log(bold(result.ok ? green(`✓ ${result.project} is ready to release`) : red(`✗ ${result.project} is not ready to release`)));
+    for (const l of result.locales) console.log(`  ${l.locale.padEnd(8)} ${String(l.coverage).padStart(6)}%  ${l.missing ? red(`${l.missing} missing`) : green("complete")}${dim(` · ${l.translated}/${l.strings} translated, ${l.reviewed} reviewed`)}`);
+    for (const f of result.failures) console.log(red(`  ✗ ${f.message}`));
+    for (const w of result.warnings) console.log(dim(`  ! ${w}`));
+    if (result.digest) console.log(dim(`  digest ${result.digest}`));
+  }
+  if (!result.ok) process.exitCode = 1;
 }
 
 // ------------------------------------------------- agent-written translations
@@ -720,6 +986,15 @@ ${bold("Usage")}
   glossa logout                             forget the saved key
   glossa push [files…] [--project p] [--locale l]
   glossa pull [paths…] [--project p] [--locale es,fr] [--out dir] [--approved-only]
+  glossa sync [files…] [--wait 10m] [--no-pull] [--locale es,fr] [--out dir]
+                                            push the source files, wait for AI translation
+                                            (ai mode), pull every locale file; exits 1 if a
+                                            push or job fails or jobs outlast --wait
+  glossa check [--max-missing n] [--min-coverage pct] [--require-reviewed]
+              [--stale fail|warn|ignore] [--allow-pending] [--wait 10m] [--out dir]
+                                            release gate: exits 1 unless this commit's
+                                            strings are translated and its locale files
+                                            match what pull writes (docs: /docs/release-gate)
   glossa missing [--project p] [--locale es,fr] [--out file]
                                             strings still missing a translation, with
                                             their keys and file paths, for an agent
@@ -749,9 +1024,21 @@ ${bold("Config")}  .glossa.json: {"project": "my-app", "files": ["locales/en.jso
 ${bold("Env")}     GLOSSA_API_KEY, GLOSSA_HOST (default ${DEFAULT_HOST})`);
 }
 
+// Help must return before any command can read project files, write credentials,
+// start a browser or MCP bridge, or make a mutating request. Dynamic op help
+// still reads the public catalog below so it uses the current server schema.
+const BUILTIN_COMMANDS = new Set([
+  "login", "logout", "whoami", "push", "pull", "sync", "missing", "check",
+  "fill", "cancel", "tasks", "mcp", "pricing", "billing", "account",
+  "subscribe", "upgrade", "feedback", "review", "reviews", "ops",
+]);
+
 async function main() {
   const [command, ...rest] = process.argv.slice(2);
   const { positional, flags } = parseArgs(rest);
+  if (flags.help && BUILTIN_COMMANDS.has(command)) {
+    return command === "feedback" ? console.log(FEEDBACK_USAGE) : help();
+  }
   if (flags.host && command !== "login") process.env.GLOSSA_HOST = String(flags.host);
   switch (command) {
     case undefined:
@@ -772,8 +1059,12 @@ async function main() {
       return push(positional, flags);
     case "pull":
       return pull(positional, flags);
+    case "sync":
+      return sync(positional, flags);
     case "missing":
       return missing(flags);
+    case "check":
+      return check(flags);
     case "fill":
       return fill(positional, flags);
     case "cancel":
@@ -792,7 +1083,6 @@ async function main() {
     case "upgrade":
       return subscribe(positional, flags);
     case "feedback":
-      if (flags.help) return console.log(FEEDBACK_USAGE);
       return feedback(positional, flags);
     case "review":
       return review(flags);

package/bin/glossa.test.mjs

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { cancelJobInput, coerceFlags, deviceLogin, feedbackCall, fileBody, fileText, parseArgs, readJsonArg, fillBatches, pricingLines, reportInput, reviewInput, subscribeInput } from "./glossa.mjs";
+import { cancelJobInput, checkInput, jobTotals, syncVerdict, waitForJobs, coerceFlags, compareLocal, parseDuration, syncHash, deviceLogin, feedbackCall, fileBody, fileText, parseArgs, readJsonArg, fillBatches, pricingLines, reportInput, reviewInput, subscribeInput } from "./glossa.mjs";
 import { pricingDocument } from "../../../lib/billing/pricing";
 
 describe("cli args", () => {
@@ -159,3 +159,125 @@ describe("cancel", () => {
     for (const ids of [[], ["invalid"], [job, job]]) expect(() => cancelJobInput(ids, {})).toThrow(/Usage/);
   });
 });
+
+describe("check", () => {
+  it("hashes like check_sync: sha256 of UTF-8, CRLF read as LF", () => {
+    expect(syncHash("")).toBe("e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855");
+    expect(syncHash("a\r\nb")).toBe(syncHash("a\nb"));
+  });
+
+  it("parses --wait durations", () => {
+    expect(parseDuration("90")).toBe(90_000);
+    expect(parseDuration("10m")).toBe(600_000);
+    expect(parseDuration("1h")).toBe(3_600_000);
+    expect(() => parseDuration("soon")).toThrow(/duration/);
+  });
+
+  it("takes the policy from flags over .glossa.json's check block", () => {
+    const config = { project: "web", locales: ["es"], check: { max_missing: 10, min_coverage: 95, stale: "warn", require_reviewed: true } };
+    expect(checkInput({}, config, [])).toEqual({
+      project: "web",
+      locales: ["es"],
+      missing: "source",
+      approved_only: false,
+      compare_files: true,
+      max_missing: 10,
+      min_coverage: 95,
+      require_reviewed: true,
+      stale: "warn",
+    });
+    expect(checkInput({ "max-missing": "none", stale: "ignore", locale: "de,fr", "allow-pending": true }, config, [{ path: "en.json", content: "{}" }])).toMatchObject({
+      locales: ["de", "fr"],
+      sources: [{ path: "en.json", content: "{}" }],
+      compare_files: false,
+      max_missing: null,
+      allow_pending: true,
+    });
+    expect(() => checkInput({ stale: "maybe" }, config, [])).toThrow(/--stale/);
+  });
+
+  it("compares the tree with pull's output and skips files whose source changed", () => {
+    const result = {
+      ok: true,
+      failures: [],
+      warnings: [],
+      totals: { strings: 2, missing: 0, unpushed: 0, stale: 0 },
+      files: [
+        { source: "current", outputs: [{ path: "es.json", sha256: syncHash("es") }, { path: "fr.json", sha256: syncHash("fr") }, { path: "de.json", sha256: syncHash("de") }] },
+        { source: "changed", outputs: [{ path: "other/es.json", sha256: syncHash("x") }] },
+      ],
+    };
+    const tree = { "es.json": syncHash("es"), "fr.json": syncHash("old") };
+    const out = compareLocal(result, "fail", (path) => tree[path] ?? null);
+    expect(out.files.flatMap((f) => f.outputs.map((o) => o.status))).toEqual(["in_sync", "stale", "missing", "not_comparable"]);
+    expect(out).toMatchObject({ ok: false, totals: { stale: 2 }, failures: [{ code: "stale_files" }] });
+    expect(compareLocal(result, "warn", (path) => tree[path] ?? null)).toMatchObject({ ok: true, warnings: [expect.stringContaining("2 locale files")] });
+  });
+});
+
+describe("sync", () => {
+  const job = (id, status, totals = {}) => ({ id, status, output: { totals } });
+
+  it("waits until every job finishes, then sorts them by outcome", async () => {
+    let t = 0;
+    const reads = { a: [job("a", "running"), job("a", "done", { es: { translated: 3, flagged: 1 } })], b: [job("b", "queued"), job("b", "running"), job("b", "failed")] };
+    const progress = [];
+    const out = await waitForJobs(["a", "b"], {
+      getJob: async (id) => reads[id].shift() ?? reads[id].at(-1),
+      deadline: 60_000,
+      interval: 1_000,
+      wait: async (ms) => { t += ms; },
+      now: () => t,
+      onProgress: (open) => progress.push(open.map((j) => j.id)),
+    });
+    expect(out.done.map((j) => j.id)).toEqual(["a"]);
+    expect(out.failed.map((j) => j.id)).toEqual(["b"]);
+    expect(out.pending).toEqual([]);
+    expect(progress).toEqual([["a", "b"], ["b"]]);
+  });
+
+  it("stops at the deadline with what is still running, and counts an unreadable job as failed", async () => {
+    let t = 0;
+    const out = await waitForJobs(["a", "b"], {
+      getJob: async (id) => { if (id === "b") throw new Error("Job b not found"); return job("a", "running"); },
+      deadline: 2_500,
+      interval: 1_000,
+      wait: async (ms) => { t += ms; },
+      now: () => t,
+    });
+    expect(out.pending.map((j) => j.id)).toEqual(["a"]);
+    expect(out.failed).toEqual([{ id: "b", status: "failed", error: "Job b not found" }]);
+  });
+
+  const pushed = (overrides = {}) => ({ path: "messages/en.json", result: { status: "parsed", keys: { added: 2, updated: 1, removed: 0 }, units: { created: 2 }, translation_mode: "ai", ...overrides } });
+
+  it("summarizes a clean run", () => {
+    const v = syncVerdict({
+      pushed: [pushed()],
+      jobs: { done: [job("a", "done", { es: { translated: 2, flagged: 0 }, ja: { translated: 2, flagged: 1 } })], failed: [], pending: [] },
+      waitedMs: 30_000,
+      written: [{ path: "messages/es.json", changed: true }, { path: "messages/ja.json", changed: false }],
+      agentStrings: 0,
+    });
+    expect(v.ok).toBe(true);
+    expect(v.lines).toEqual(["pushed 1 file (+2 keys, 1 updated, 0 removed)", "translated 4 strings in 2 locales, 1 flagged for review (glossa tasks)", "wrote 2 locale files, 1 changed"]);
+    expect(jobTotals([job("x", "done", { es: { translated: 1, flagged: 0 } }), job("y", "done", { es: { translated: 2, flagged: 1 } })])).toEqual({ es: { translated: 3, flagged: 1 } });
+  });
+
+  it("fails on unreadable files, failed jobs and jobs that outlast --wait, and points agent mode at glossa missing", () => {
+    const v = syncVerdict({
+      pushed: [pushed({ status: "needs_format", keys: undefined }), pushed({ translation_mode: "agent" })],
+      jobs: { done: [], failed: [{ id: "12345678-aaaa", status: "failed", error: "model error" }], pending: [job("b", "running")] },
+      waitedMs: 600_000,
+      written: [],
+      agentStrings: 2,
+    });
+    expect(v.ok).toBe(false);
+    expect(v.problems).toEqual([
+      "Glossa can't read messages/en.json yet; resolve its learn_format task (glossa tasks --kind learn_format) and run sync again.",
+      "translate job 12345678 failed: model error.",
+      "1 translate job is still running after 600s; run glossa sync again (or pass a longer --wait) to pull the rest.",
+    ]);
+    expect(v.lines).toContain("2 new strings wait for your agent (agent mode): glossa missing, then glossa fill");
+  });
+});

package/bin/help.test.mjs

@@ -0,0 +1,101 @@
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { mkdtempSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+const cli = fileURLToPath(new URL("./glossa.mjs", import.meta.url));
+const builtins = ["login", "logout", "whoami", "push", "pull", "sync", "missing", "check", "fill", "cancel", "tasks", "mcp", "pricing", "billing", "account", "subscribe", "upgrade", "feedback", "review", "reviews", "ops"];
+
+describe("CLI help and exit status", () => {
+  let root, server, base, requests;
+  const snapshot = () => Object.fromEntries(readdirSync(root, { recursive: true, withFileTypes: true }).filter((entry) => entry.isFile()).map((entry) => {
+    const path = join(entry.parentPath, entry.name);
+    return [path, readFileSync(path, "utf8")];
+  }));
+  beforeEach(async () => {
+    root = mkdtempSync(join(tmpdir(), "glossa-cli-help-"));
+    mkdirSync(join(root, "glossa"));
+    writeFileSync(join(root, "glossa", "config.json"), JSON.stringify({ api_key: "gls_test_local_only" }));
+    writeFileSync(join(root, ".glossa.json"), JSON.stringify({ project: "test", files: ["en.json"], locales: ["es"] }));
+    writeFileSync(join(root, "en.json"), '{"hello":"Hello"}');
+    requests = [];
+    server = createServer((request, response) => {
+      requests.push(`${request.method} ${request.url}`);
+      response.setHeader("content-type", "application/json");
+      if (request.url === "/api/v1") response.end(JSON.stringify({ ops: [{ name: "test_op", description: "Test operation", input_schema: { type: "object" } }] }));
+      else {
+        response.statusCode = 400;
+        response.end(JSON.stringify({ detail: "Test API rejection", request_id: "req_test" }));
+      }
+    });
+    await new Promise((done) => server.listen(0, "127.0.0.1", done));
+    base = `http://127.0.0.1:${server.address().port}`;
+  });
+  afterEach(async () => {
+    await new Promise((done) => server.close(done));
+    rmSync(root, { recursive: true, force: true });
+  });
+  const run = (args) => new Promise((done) => {
+    const child = spawn(process.execPath, [cli, ...args], { cwd: root, env: { ...process.env, XDG_CONFIG_HOME: root, GLOSSA_HOST: base, GLOSSA_API_KEY: "gls_test_local_only" }, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "", stderr = "";
+    child.stdout.on("data", (data) => { stdout += data; });
+    child.stderr.on("data", (data) => { stderr += data; });
+    const timeout = setTimeout(() => child.kill(), 2000);
+    child.on("close", (code) => { clearTimeout(timeout); done({ code, stdout, stderr }); });
+  });
+
+  it.each(builtins)("%s --help has no API calls or file writes", async (command) => {
+    const before = snapshot();
+    const result = await run([command, "--help"]);
+    expect(result.code, result.stderr).toBe(0);
+    expect(result.stdout).toContain("glossa");
+    expect(requests).toEqual([]);
+    expect(snapshot()).toEqual(before);
+  });
+
+  it("accepts -h without executing sync", async () => {
+    const result = await run(["sync", "-h"]);
+    expect(result.code, result.stderr).toBe(0);
+    expect(result.stdout).toContain("Usage");
+    expect(requests).toEqual([]);
+  });
+
+  it("ignores credential and purchase flags when help is requested", async () => {
+    const before = snapshot();
+    for (const args of [
+      ["login", "--help", "--host", base, "--key", "gls_replacement"],
+      ["upgrade", "--plan", "pro", "--confirm", "--help"],
+      ["feedback", "report", "A test report", "-h"],
+    ]) {
+      const result = await run(args);
+      expect(result.code, result.stderr).toBe(0);
+    }
+    expect(requests).toEqual([]);
+    expect(snapshot()).toEqual(before);
+  });
+
+  it("only reads the catalog for dynamic op help", async () => {
+    const before = snapshot();
+    const result = await run(["test-op", "--help", "--json", "@missing.json"]);
+    expect(result.code, result.stderr).toBe(0);
+    expect(result.stdout).toContain("Test operation");
+    expect(requests).toEqual(["GET /api/v1"]);
+    expect(snapshot()).toEqual(before);
+  });
+
+  it("exits nonzero for unknown commands", async () => {
+    const result = await run(["not-a-command"]);
+    expect(result.code).toBe(1);
+    expect(result.stderr).toContain("unknown command");
+    expect(requests).toEqual(["GET /api/v1"]);
+  });
+
+  it("exits nonzero for API errors", async () => {
+    const result = await run(["whoami"]);
+    expect(result.code).toBe(1);
+    expect(result.stderr).toContain("Test API rejection");
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meterapp/glossa",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Glossa CLI: push and pull translation files, run the AI review queue, and every other Glossa op from your terminal or CI. Includes a stdio MCP bridge.",
   "type": "module",
   "bin": { "glossa": "bin/glossa.mjs" },