@meterapp/glossa 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+# @meterapp/glossa
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Glossa CLI. Push and pull translation files in any format, work the AI review queue, and run every op the Glossa dashboard can do, from your terminal, CI or an agent.
+
+```bash
+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 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
+npx @meterapp/glossa run_audit --locale es --question "Are brand names consistent?"
+npx @meterapp/glossa ops          # every op, live from the API
+npx @meterapp/glossa mcp          # stdio MCP bridge for hosts without HTTP MCP
+npx @meterapp/glossa pricing      # plans and prices, no key needed
+npx @meterapp/glossa billing      # this workspace's plan and usage
+npx @meterapp/glossa subscribe pro --interval year --open   # Stripe Checkout link for a human
+```
+
+`subscribe` prints a Stripe Checkout link and charges nothing; a human pays in
+the browser. With `--confirm` it subscribes on the card already saved for the
+workspace instead, so pass it only after a human approved the plan and price.
+
+For a project in `translation_mode` `agent`, pushes do not queue AI
+translation: a coding agent reads `missing`, looks up each key in the code and
+writes the translations with `fill`. Any op takes `--json @file.json` or
+`--json -` (stdin) for large input.
+
+`.glossa.json` at your repo root:
+
+```json
+{ "project": "web", "files": ["locales/en.json"], "locales": ["es", "fr", "de"] }
+```
+
+`login` opens your browser: confirm the code your terminal shows at
+getglossa.dev/activate and the CLI saves a new workspace API key. Over SSH,
+open the printed URL on any device (`--no-browser` skips opening one). To save
+an existing key instead, run `login --key gls_…`.
+
+In CI set `GLOSSA_API_KEY` (a workspace key, `gls_…`).

package/bin/glossa.mjs

@@ -0,0 +1,563 @@
+#!/usr/bin/env node
+// Glossa CLI. Zero dependencies. Every op the API offers is a command
+// (`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 { 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.3.0";
+const DEFAULT_HOST = "https://getglossa.dev";
+const CONFIG_PATH = join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "glossa", "config.json");
+const PROJECT_CONFIG = ".glossa.json";
+
+// ------------------------------------------------------------------ config
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+const userConfig = () => readJson(CONFIG_PATH) ?? {};
+function saveUserConfig(next) {
+  mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+  writeFileSync(CONFIG_PATH, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+}
+const host = () => (process.env.GLOSSA_HOST || userConfig().host || DEFAULT_HOST).replace(/\/$/, "");
+const apiKey = () => process.env.GLOSSA_API_KEY || userConfig().api_key || null;
+
+function projectConfig() {
+  let dir = process.cwd();
+  for (;;) {
+    const path = join(dir, PROJECT_CONFIG);
+    if (existsSync(path)) return { root: dir, config: readJson(path) ?? {} };
+    const parent = dirname(dir);
+    if (parent === dir) return { root: process.cwd(), config: {} };
+    dir = parent;
+  }
+}
+
+// ---------------------------------------------------------------- output
+const isTTY = process.stdout.isTTY;
+const dim = (s) => (isTTY ? `\x1b[2m${s}\x1b[0m` : s);
+const bold = (s) => (isTTY ? `\x1b[1m${s}\x1b[0m` : s);
+const red = (s) => (isTTY ? `\x1b[31m${s}\x1b[0m` : s);
+const green = (s) => (isTTY ? `\x1b[32m${s}\x1b[0m` : s);
+function fail(message, code = 1) {
+  console.error(red(`error: ${message}`));
+  process.exit(code);
+}
+
+// ------------------------------------------------------------------- http
+async function call(op, input = {}, { method = "POST" } = {}) {
+  const key = apiKey();
+  if (!key) fail("not signed in. Run `glossa login` or set GLOSSA_API_KEY.");
+  const response = await fetch(`${host()}/api/v1/${op}`, {
+    method,
+    headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json", "X-Glossa-Integration": "cli", "User-Agent": `glossa-cli/${VERSION}` },
+    body: JSON.stringify(input),
+  });
+  const text = await response.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    body = { detail: text };
+  }
+  if (!response.ok) {
+    const error = new Error(body.detail || `${op} failed with HTTP ${response.status}`);
+    error.status = response.status;
+    error.body = body;
+    throw error;
+  }
+  return body;
+}
+
+async function manifest() {
+  const response = await fetch(`${host()}/api/v1`, { headers: { "User-Agent": `glossa-cli/${VERSION}` } });
+  if (!response.ok) fail(`could not read the op catalog from ${host()}/api/v1 (HTTP ${response.status}).`);
+  return (await response.json()).ops;
+}
+
+// ------------------------------------------------------------------- args
+export function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--") {
+      positional.push(...argv.slice(i + 1));
+      break;
+    }
+    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];
+      else flags[name] = true;
+    } else positional.push(arg);
+  }
+  return { positional, flags };
+}
+
+/** Turns --flag strings into the types the op's JSON schema asks for. */
+export function coerceFlags(flags, schema) {
+  const props = schema?.properties ?? {};
+  const out = {};
+  for (const [rawName, value] of Object.entries(flags)) {
+    if (["json", "host", "pretty", "help"].includes(rawName)) continue;
+    const name = rawName.replace(/-/g, "_");
+    const type = props[name]?.type;
+    if (type === "number" || type === "integer") out[name] = Number(value);
+    else if (type === "boolean") out[name] = value === true || value === "true";
+    else if (type === "array") out[name] = String(value).split(",").map((s) => s.trim()).filter(Boolean);
+    else if (type === "object") out[name] = JSON.parse(String(value));
+    else out[name] = value === true ? "" : String(value);
+  }
+  return out;
+}
+
+/** `--json` takes inline JSON, `@path` to read a file, or `-` to read stdin. */
+export function readJsonArg(value, { readFile = (path) => readFileSync(path, "utf8") } = {}) {
+  const text = String(value);
+  if (text === "-") return JSON.parse(readFileSync(0, "utf8"));
+  if (text.startsWith("@")) return JSON.parse(readFile(text.slice(1)));
+  return JSON.parse(text);
+}
+
+function print(value, flags) {
+  if (flags.pretty === false || (!isTTY && !flags.pretty)) process.stdout.write(JSON.stringify(value) + "\n");
+  else process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+}
+
+// ----------------------------------------------------------------- billing
+const money = (cents) => (cents === null || cents === undefined ? "custom" : `$${(cents / 100).toLocaleString("en-US")}`);
+
+/** `subscribe <plan> [--interval year | --yearly] [--confirm]` as op input. */
+export function subscribeInput(positional, flags) {
+  const plan = String(positional[0] ?? flags.plan ?? "").toLowerCase();
+  if (!["pro", "team"].includes(plan)) throw new Error('name a plan: `glossa subscribe pro` or `glossa subscribe team` (see `glossa pricing`).');
+  const interval = flags.yearly || flags.interval === "year" || flags.interval === "yearly" ? "year" : "month";
+  return { plan, interval, ...(flags.confirm ? { confirm: true } : {}) };
+}
+
+function openUrl(url) {
+  const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer" : "xdg-open";
+  spawn(command, [url], { stdio: "ignore", detached: true }).on("error", () => undefined).unref();
+}
+
+async function pricing(flags) {
+  const response = await fetch(`${host()}/api/v1/get_pricing`, { headers: { "User-Agent": `glossa-cli/${VERSION}`, "X-Glossa-Integration": "cli" } });
+  if (!response.ok) fail(`could not read pricing (HTTP ${response.status}).`);
+  const catalog = await response.json();
+  if (flags.json || !isTTY) return print(catalog, flags);
+  for (const plan of catalog.plans) {
+    const price = plan.monthly_cents === null ? "custom" : plan.monthly_cents === 0 ? "free" : `${money(plan.monthly_cents)}/mo · ${money(plan.yearly_cents)}/yr`;
+    const allowance = plan.ai_translations_per_month === null ? "volume" : plan.ai_translations_per_month.toLocaleString("en-US");
+    console.log(`${bold(plan.name.padEnd(11))} ${price.padEnd(22)} ${allowance} AI translations/mo, ${plan.members} members`);
+  }
+  console.log(dim(`\n${catalog.unit}\nBuy: glossa subscribe pro [--interval year] [--open]`));
+}
+
+async function billing(flags) {
+  const state = await call("get_billing", flags.refresh ? { refresh: true } : {});
+  if (flags.json || !isTTY) return print(state, flags);
+  const when = state.ends_at ? `ends ${state.ends_at.slice(0, 10)}` : state.renews_at ? `renews ${state.renews_at.slice(0, 10)}` : "";
+  console.log(`${bold(state.plan_name)} ${dim(state.status === "none" ? "" : state.status)} ${state.interval ? `${money(state.price_cents)}/${state.interval}` : ""} ${dim(when)}`.trim());
+  for (const [label, usage] of [["AI translations", state.usage.ai_translations], ["members", state.usage.members], ["projects", state.usage.projects]]) {
+    console.log(`  ${label.padEnd(16)} ${usage.used.toLocaleString("en-US")} of ${usage.included === null ? "unlimited" : usage.included.toLocaleString("en-US")}`);
+  }
+  console.log(dim(`  card saved: ${state.payment_method_saved ? "yes" : "no"} · ${state.manage_url}`));
+}
+
+/**
+ * Without --confirm: a Stripe Checkout link for a human (nothing is charged).
+ * With --confirm: subscribe on the saved card, which a human must have approved.
+ */
+async function subscribe(positional, flags) {
+  let input;
+  try {
+    input = subscribeInput(positional, flags);
+  } catch (error) {
+    fail(error.message);
+  }
+  const result = input.confirm ? await call("subscribe", input) : await call("create_checkout_link", input);
+  const url = result.url ?? result.checkout_url ?? null;
+  if (flags.json || !isTTY) {
+    print(result, flags);
+  } else if (url) {
+    console.log(`${bold(`${input.plan} · ${money(result.amount_cents)}/${input.interval}`)}: ${result.reason ?? "complete the purchase in Stripe Checkout (nothing is charged until you do)."}`);
+    console.log(url);
+  } else {
+    console.log(green(`✓ ${result.status}: ${result.billing?.plan_name ?? input.plan} (${input.interval}ly)`));
+  }
+  if (url && flags.open) openUrl(url);
+}
+
+// ------------------------------------------------------------------ login
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+
+/**
+ * Browser sign-in (RFC 8628 device flow): print a code and a URL, open the
+ * browser, poll until the person approves at /activate. Works over SSH and for
+ * agents, who relay the URL and code to their human. Resolves to
+ * {api_key, email, workspace}.
+ */
+export async function deviceLogin({ base, browser = true, fetchImpl = fetch, wait = sleep, log = (line) => console.error(line), open = openUrl, now = Date.now } = {}) {
+  const post = async (path, body) => {
+    const response = await fetchImpl(`${base}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-Glossa-Integration": "cli", "User-Agent": `glossa-cli/${VERSION}` },
+      body: JSON.stringify(body),
+    });
+    const text = await response.text();
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      parsed = { detail: text };
+    }
+    return { status: response.status, ok: response.ok, body: parsed };
+  };
+  const start = await post("/api/v1/auth/device", { client_name: `glossa CLI on ${hostname()}`.slice(0, 80) });
+  if (!start.ok) {
+    const error = new Error(start.body.detail || `could not start sign-in (HTTP ${start.status})`);
+    error.body = start.body;
+    throw error;
+  }
+  const { device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval } = start.body;
+  log(`Open ${bold(verification_uri)} and enter the code ${bold(user_code)}`);
+  log(dim(`(or go straight to ${verification_uri_complete})`));
+  if (browser) open(verification_uri_complete);
+  log("Waiting for approval in the browser…");
+  const deadline = now() + expires_in * 1000;
+  let delay = Math.max(1, interval ?? 3) * 1000;
+  while (now() < deadline) {
+    await wait(delay);
+    let poll;
+    try {
+      poll = await post("/api/v1/auth/device/token", { device_code });
+    } catch {
+      delay += 2000; // network blip: back off and keep waiting
+      continue;
+    }
+    if (poll.ok) return poll.body;
+    if (poll.body.code === "authorization_pending") continue;
+    if (poll.status === 429 || poll.status >= 500) {
+      delay += 2000;
+      continue;
+    }
+    const error = new Error(poll.body.detail || `sign-in failed (HTTP ${poll.status})`);
+    error.body = poll.body;
+    throw error;
+  }
+  throw new Error("the code expired before it was approved. Run `glossa login` again.");
+}
+
+// ---------------------------------------------------------------- commands
+async function login(flags) {
+  if (flags.host) saveUserConfig({ ...userConfig(), host: String(flags.host) });
+  // --key gls_… (CI, scripts) or --key alone to paste one; otherwise sign in with the browser.
+  if (flags.key !== undefined) {
+    let value = typeof flags.key === "string" ? flags.key : null;
+    if (!value) {
+      console.log(`Create an API key at ${bold(`${host()}/dashboard/settings`)} (Settings → API keys), then paste it here.`);
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      value = await new Promise((done) => rl.question("API key: ", (answer) => (rl.close(), done(answer.trim()))));
+    }
+    if (!value?.startsWith("gls_")) fail("that does not look like a Glossa API key (gls_…).");
+    saveUserConfig({ ...userConfig(), api_key: value });
+  } else {
+    const result = await deviceLogin({ base: host(), browser: !flags["no-browser"] });
+    saveUserConfig({ ...userConfig(), api_key: result.api_key, ...(result.email ? { email: result.email } : {}) });
+  }
+  const workspace = await call("get_workspace");
+  console.log(green(`Signed in to ${workspace.name} (${workspace.slug}). Key saved to ${CONFIG_PATH}.`));
+}
+
+function logout() {
+  const config = userConfig();
+  if (!config.api_key) return console.log("Not signed in.");
+  delete config.api_key;
+  delete config.email;
+  saveUserConfig(config);
+  console.log(`Signed out. The key still works until you revoke it (Settings → API keys).`);
+}
+
+function expandFiles(patterns, root) {
+  const files = [];
+  for (const pattern of patterns) {
+    const path = resolve(root, pattern);
+    if (existsSync(path) && statSync(path).isDirectory()) {
+      for (const entry of readdirSync(path, { recursive: true })) {
+        const full = join(path, String(entry));
+        if (statSync(full).isFile()) files.push(full);
+      }
+    } else if (existsSync(path)) files.push(path);
+    else fail(`no such file: ${pattern}`);
+  }
+  return files;
+}
+
+/** Files over 1 MB travel brotli-compressed: request and response bodies are capped at 4.5 MB. */
+export function fileBody(text) {
+  if (Buffer.byteLength(text, "utf8") <= 1_000_000) return { content: text };
+  const bytes = Buffer.from(text, "utf8");
+  return { content_brotli: brotliCompressSync(bytes, { params: { [zlib.BROTLI_PARAM_QUALITY]: 9, [zlib.BROTLI_PARAM_SIZE_HINT]: bytes.length } }).toString("base64") };
+}
+
+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) {
+  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 } : {}) });
+    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") : "")
+      );
+    }
+    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.");
+  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)))) {
+    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 target = join(outRoot, out.path);
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, fileText(out));
+      console.log(`${green("wrote")} ${relative(process.cwd(), target)} ${dim(`(${out.keys} keys)`)}`);
+      if (file.formats && /xcstrings|csv|xliff/.test(file.formats.slug ?? "")) break; // multi-locale: one write covers all
+    }
+  }
+}
+
+// ------------------------------------------------- agent-written translations
+/** Splits `fill` input (an array, or {translations: […]}) into submit_translations batches of 200. */
+export function fillBatches(parsed, size = 200) {
+  const items = Array.isArray(parsed) ? parsed : parsed?.translations;
+  if (!Array.isArray(items) || !items.length) throw new Error('expected a JSON array of {"unit", "locale", "text"} (or {"translations": […]}).');
+  for (const [i, item] of items.entries()) {
+    if (!item?.unit || !item?.locale || typeof item?.text !== "string") throw new Error(`item ${i} needs unit, locale and text.`);
+  }
+  const batches = [];
+  for (let i = 0; i < items.length; i += size) batches.push(items.slice(i, i + size));
+  return batches;
+}
+
+/** The worklist an agent translates from: missing strings with keys, paths and glossary. */
+async function missing(flags) {
+  const { config } = projectConfig();
+  const project = flags.project ?? config.project;
+  const input = {
+    ...(project ? { project } : {}),
+    ...(flags.locale ? { locales: String(flags.locale).split(",").map((s) => s.trim()).filter(Boolean) } : {}),
+    ...(flags.limit ? { limit: Number(flags.limit) } : {}),
+    ...(flags.offset ? { offset: Number(flags.offset) } : {}),
+  };
+  const result = await call("list_missing_translations", input);
+  if (flags.out) {
+    writeFileSync(resolve(String(flags.out)), JSON.stringify(result, null, 2) + "\n");
+    console.error(`${green("wrote")} ${flags.out} ${dim(`(${result.units.length} of ${result.total_units} strings, ${result.total_missing} translations missing)`)}`);
+    return;
+  }
+  if (flags.json || !isTTY) return print(result, flags);
+  console.log(bold(`${result.total_units} strings missing ${result.total_missing} translations${project ? ` in ${project}` : ""}`));
+  for (const unit of result.units) {
+    const where = unit.keys.map((k) => `${k.key}${k.path ? dim(` (${k.path})`) : ""}`).join(", ");
+    console.log(`${dim(unit.unit_id.slice(0, 8))}  ${JSON.stringify(unit.source_text)}  → ${unit.missing_locales.join(", ")}`);
+    if (where) console.log(dim(`          ${where}`));
+  }
+  if (result.total_units > result.units.length) console.log(dim(`… ${result.total_units - result.units.length} more (--limit, --offset)`));
+  console.log(dim(`\nFull context: glossa missing --out missing.json · write back: glossa fill translations.json`));
+}
+
+async function fill(positional, flags) {
+  const source = positional[0] ?? (flags.file ? String(flags.file) : null);
+  if (!source) fail('pass a JSON file of [{"unit", "locale", "text"}] (or - for stdin): glossa fill translations.json');
+  let batches;
+  try {
+    batches = fillBatches(source === "-" ? readJsonArg("-") : readJsonArg(`@${source}`));
+  } catch (error) {
+    fail(error.message);
+  }
+  const options = { ...(flags.status ? { status: String(flags.status) } : {}), ...(flags.overwrite ? { overwrite: String(flags.overwrite) } : {}) };
+  const totals = { written: 0, skipped: [], rejected: [], tasks_created: 0 };
+  for (const batch of batches) {
+    const result = await call("submit_translations", { translations: batch, ...options });
+    totals.written += result.written;
+    totals.skipped.push(...result.skipped);
+    totals.rejected.push(...result.rejected);
+    totals.tasks_created += result.tasks_created ?? 0;
+  }
+  if (flags.json || !isTTY) return print(totals, flags);
+  console.log(green(`✓ wrote ${totals.written} translations`) + dim(` · ${totals.skipped.length} skipped · ${totals.rejected.length} rejected · ${totals.tasks_created} review tasks`));
+  for (const r of [...totals.rejected, ...totals.skipped]) console.log(dim(`  ${r.unit.slice(0, 8)} ${r.locale}: ${r.reason}`));
+  if (totals.rejected.length) process.exitCode = 1;
+}
+
+async function tasks(flags) {
+  const { tasks: list, total } = await call("list_tasks", coerceFlags(flags, { properties: { limit: { type: "integer" }, kind: { type: "string" }, status: { type: "string" } } }));
+  if (flags.json || !isTTY) return print({ total, tasks: list }, flags);
+  console.log(bold(`${total} ${flags.status ?? "open"} tasks`));
+  for (const t of list) console.log(`${dim(t.id.slice(0, 8))}  ${t.kind.padEnd(19)} ${t.title}`);
+  if (total > list.length) console.log(dim(`… ${total - list.length} more (--limit, --offset)`));
+}
+
+/** stdio ⇄ HTTP: lets any MCP host that only speaks stdio use the hosted server. */
+async function mcp() {
+  const key = apiKey();
+  if (!key) fail("set GLOSSA_API_KEY (or run `glossa login`) before starting the MCP bridge.");
+  const rl = createInterface({ input: process.stdin });
+  let queue = Promise.resolve();
+  rl.on("line", (line) => {
+    if (!line.trim()) return;
+    queue = queue.then(async () => {
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        return;
+      }
+      const response = await fetch(`${host()}/api/mcp`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream", "X-Glossa-Integration": "cli-mcp" },
+        body: JSON.stringify(message),
+      }).catch((error) => ({ ok: false, status: 0, text: async () => String(error) }));
+      const text = await response.text();
+      if (!text.trim()) return; // notifications get 202 with no body
+      try {
+        process.stdout.write(JSON.stringify(JSON.parse(text)) + "\n");
+      } catch {
+        if (message.id !== undefined) {
+          process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id: message.id, error: { code: -32603, message: `HTTP ${response.status}: ${text.slice(0, 300)}` } }) + "\n");
+        }
+      }
+    });
+  });
+}
+
+async function help() {
+  console.log(`${bold("glossa")} ${VERSION} — localization your AI agents can run
+
+${bold("Usage")}
+  glossa login [--no-browser] [--host URL]  sign in with your browser
+  glossa login --key gls_…                  save an API key instead (CI, scripts)
+  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 missing [--project p] [--locale es,fr] [--out file]
+                                            strings still missing a translation, with
+                                            their keys and file paths, for an agent
+  glossa fill <file.json|->                 write translations: [{"unit","locale","text"}]
+                                            [--status reviewed|needs_review] [--overwrite missing|machine|all]
+  glossa tasks [--kind k] [--limit n]       the review queue
+  glossa mcp                                stdio MCP bridge to the hosted server
+  glossa pricing                            plans and prices (no key needed)
+  glossa billing [--refresh]                this workspace's plan and usage
+  glossa subscribe pro|team [--interval year] [--open]
+                                            Stripe Checkout link for a human; --confirm
+                                            charges the saved card (only once approved)
+  glossa <op> [--field value…] [--json '{…}' | @file | -]  run any op (glossa ops lists them)
+  glossa ops                                list every op
+
+${bold("Config")}  .glossa.json: {"project": "my-app", "files": ["locales/en.json"], "locales": ["es", "fr"]}
+${bold("Env")}     GLOSSA_API_KEY, GLOSSA_HOST (default ${DEFAULT_HOST})`);
+}
+
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  const { positional, flags } = parseArgs(rest);
+  if (flags.host && command !== "login") process.env.GLOSSA_HOST = String(flags.host);
+  switch (command) {
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      return help();
+    case "--version":
+    case "-v":
+      return console.log(VERSION);
+    case "login":
+      return login(flags);
+    case "logout":
+      return logout();
+    case "whoami":
+      return print(await call("get_workspace"), flags);
+    case "push":
+      return push(positional, flags);
+    case "pull":
+      return pull(positional, flags);
+    case "missing":
+      return missing(flags);
+    case "fill":
+      return fill(positional, flags);
+    case "tasks":
+      return tasks(flags);
+    case "mcp":
+      return mcp();
+    case "pricing":
+      return pricing(flags);
+    case "billing":
+      return billing(flags);
+    case "subscribe":
+    case "upgrade":
+      return subscribe(positional, flags);
+    case "ops": {
+      const ops = await manifest();
+      if (flags.json || !isTTY) return print(ops, flags);
+      for (const op of ops) console.log(`${bold(op.name.padEnd(22))} ${dim(op.read_only ? "read " : "write")} ${op.title}`);
+      return;
+    }
+    default: {
+      const ops = await manifest();
+      const op = ops.find((o) => o.name === command || o.name === command.replace(/-/g, "_"));
+      if (!op) fail(`unknown command "${command}". Run \`glossa ops\` for the list.`);
+      if (flags.help) {
+        console.log(`${bold(op.name)} — ${op.description}\n\n${JSON.stringify(op.input_schema, null, 2)}`);
+        return;
+      }
+      const input = { ...(flags.json ? readJsonArg(flags.json) : {}), ...coerceFlags(flags, op.input_schema) };
+      return print(await call(op.name, input), flags);
+    }
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("/glossa") || process.argv[1]?.endsWith("glossa.mjs")) {
+  main().catch((error) => {
+    if (error.body) console.error(red(`error: ${error.body.detail ?? error.message}`) + (error.body.request_id ? dim(` (request ${error.body.request_id})`) : ""));
+    else console.error(red(`error: ${error.message}`));
+    process.exit(1);
+  });
+}

package/bin/glossa.test.mjs

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest";
+import { coerceFlags, deviceLogin, fileBody, fileText, parseArgs, readJsonArg, fillBatches, subscribeInput } from "./glossa.mjs";
+
+describe("cli args", () => {
+  it("parses flags and positionals", () => {
+    expect(parseArgs(["a.json", "--project", "app", "--dry", "--locale=es"])).toEqual({ positional: ["a.json"], flags: { project: "app", dry: true, locale: "es" } });
+  });
+  it("coerces by schema", () => {
+    const schema = { properties: { limit: { type: "integer" }, locales: { type: "array" }, auto_translate: { type: "boolean" } } };
+    expect(coerceFlags({ limit: "5", locales: "es, fr", "auto-translate": "false", json: "{}" }, schema)).toEqual({ limit: 5, locales: ["es", "fr"], auto_translate: false });
+  });
+});
+
+describe("subscribe", () => {
+  it("asks for a checkout link unless --confirm", () => {
+    expect(subscribeInput(["pro"], {})).toEqual({ plan: "pro", interval: "month" });
+    expect(subscribeInput(["Team"], { yearly: true })).toEqual({ plan: "team", interval: "year" });
+    expect(subscribeInput([], { plan: "pro", interval: "year", confirm: true })).toEqual({ plan: "pro", interval: "year", confirm: true });
+  });
+  it("rejects unknown plans", () => {
+    expect(() => subscribeInput(["enterprise"], {})).toThrow(/name a plan/);
+  });
+});
+
+describe("--json", () => {
+  it("reads inline JSON or @file", () => {
+    expect(readJsonArg('{"a":1}')).toEqual({ a: 1 });
+    expect(readJsonArg("@t.json", { readFile: (path) => (path === "t.json" ? '{"b":2}' : "") })).toEqual({ b: 2 });
+  });
+});
+
+describe("fill", () => {
+  const item = { unit: "u1", locale: "es", text: "Hola" };
+  it("accepts an array or {translations} and batches by 200", () => {
+    expect(fillBatches([item])).toEqual([[item]]);
+    expect(fillBatches({ translations: [item, item] }, 1)).toEqual([[item], [item]]);
+    expect(fillBatches(Array(450).fill(item)).map((b) => b.length)).toEqual([200, 200, 50]);
+  });
+  it("rejects empty input and items without unit, locale or text", () => {
+    expect(() => fillBatches([])).toThrow(/expected a JSON array/);
+    expect(() => fillBatches([{ unit: "u1", locale: "es" }])).toThrow(/item 0/);
+  });
+});
+
+describe("deviceLogin", () => {
+  const start = { device_code: "dc_secret", user_code: "ABCD-EFGH", verification_uri: "https://x.test/activate", verification_uri_complete: "https://x.test/activate?code=ABCD-EFGH", expires_in: 900, interval: 3 };
+  const reply = (status, body) => ({ ok: status < 300, status, text: async () => JSON.stringify(body) });
+
+  function harness(polls) {
+    const calls = [];
+    const opened = [];
+    const lines = [];
+    let clock = 0;
+    const fetchImpl = async (url, init) => {
+      calls.push({ url, body: JSON.parse(init.body) });
+      if (url.endsWith("/api/v1/auth/device")) return reply(200, start);
+      const next = polls.shift();
+      if (next instanceof Error) throw next;
+      return next;
+    };
+    const opts = { base: "https://x.test", fetchImpl, wait: async (ms) => void (clock += ms), log: (l) => lines.push(l), open: (u) => opened.push(u), now: () => clock };
+    return { calls, opened, lines, opts, waited: () => clock };
+  }
+
+  it("opens the browser, polls while pending and returns the key", async () => {
+    const h = harness([reply(428, { code: "authorization_pending" }), new Error("offline"), reply(200, { api_key: "gls_new", email: "a@b.co" })]);
+    await expect(deviceLogin(h.opts)).resolves.toEqual({ api_key: "gls_new", email: "a@b.co" });
+    expect(h.opened).toEqual([start.verification_uri_complete]);
+    expect(h.lines.join("\n")).toContain("ABCD-EFGH");
+    expect(h.calls[0].body.client_name).toMatch(/^glossa CLI on /);
+    expect(h.calls.slice(1).every((c) => c.url.endsWith("/api/v1/auth/device/token") && c.body.device_code === "dc_secret")).toBe(true);
+    expect(h.waited()).toBe(3000 + 3000 + 5000); // backs off after the network error
+  });
+
+  it("does not open a browser with browser: false", async () => {
+    const h = harness([reply(200, { api_key: "gls_new", email: null })]);
+    await deviceLogin({ ...h.opts, browser: false });
+    expect(h.opened).toEqual([]);
+  });
+
+  it("stops when the person cancels", async () => {
+    const h = harness([reply(400, { code: "access_denied", detail: "The sign-in was cancelled in the browser." })]);
+    await expect(deviceLogin(h.opts)).rejects.toThrow(/cancelled/);
+  });
+
+  it("gives up when the code expires", async () => {
+    const h = harness(Array.from({ length: 400 }, () => reply(428, { code: "authorization_pending" })));
+    await expect(deviceLogin(h.opts)).rejects.toThrow(/expired/);
+  });
+});
+
+describe("file bodies", () => {
+  it("sends small files as text and large ones brotli-compressed", () => {
+    expect(fileBody("{}")).toEqual({ content: "{}" });
+    const big = JSON.stringify(Array.from({ length: 60_000 }, (_, i) => ({ key: `k${i}`, de: "Zurückgeben" })));
+    const body = fileBody(big);
+    expect(body.content).toBeUndefined();
+    expect(body.content_brotli.length).toBeLessThan(big.length / 10);
+    expect(fileText(body)).toBe(big);
+    expect(fileText({ content: "x" })).toBe("x");
+  });
+});

package/package.json

@@ -1,6 +1,13 @@
 {
   "name": "@meterapp/glossa",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "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" },
+  "files": ["bin", "README.md"],
+  "engines": { "node": ">=20" },
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/MeterApp/glossa.git", "directory": "packages/cli" },
+  "keywords": ["i18n", "l10n", "localization", "translation", "crowdin", "mcp", "ai", "cli"],
+  "scripts": { "test": "cd ../.. && vitest run packages/cli" }
+}