@meterapp/glossa 0.2.0 → 0.4.0

package/README.md

@@ -7,18 +7,26 @@ 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
+npx @meterapp/glossa pricing [--json]   # plans, prices and limits, no key needed
+npx @meterapp/glossa account            # plan, usage against every limit, next plan
+npx @meterapp/glossa upgrade --plan pro --yearly --open   # Stripe Checkout link for a human, even before login
+npx @meterapp/glossa billing portal     # invoices, card, plan change, cancel
 ```
 
-`subscribe` prints a Stripe Checkout link and charges nothing; a human pays in
+`upgrade` (alias `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

package/bin/glossa.mjs

@@ -9,7 +9,7 @@ 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.2.0";
+const VERSION = "0.4.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";
@@ -53,12 +53,13 @@ function fail(message, code = 1) {
 }
 
 // ------------------------------------------------------------------- http
-async function call(op, input = {}, { method = "POST" } = {}) {
+/** `anonymous: true` calls a public op without a key when none is saved (pricing, checkout before signup). */
+async function call(op, input = {}, { method = "POST", anonymous = false } = {}) {
   const key = apiKey();
-  if (!key) fail("not signed in. Run `glossa login` or set GLOSSA_API_KEY.");
+  if (!key && !anonymous) 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}` },
+    headers: { ...(key ? { 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();
@@ -120,6 +121,14 @@ export function coerceFlags(flags, schema) {
   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");
@@ -131,7 +140,7 @@ const money = (cents) => (cents === null || cents === undefined ? "custom" : `$$
 /** `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`).');
+  if (!["pro", "team"].includes(plan)) throw new Error('name a plan: `glossa upgrade --plan pro` or `--plan team` (see `glossa pricing`).');
   const interval = flags.yearly || flags.interval === "year" || flags.interval === "yearly" ? "year" : "month";
   return { plan, interval, ...(flags.confirm ? { confirm: true } : {}) };
 }
@@ -141,28 +150,56 @@ function openUrl(url) {
   spawn(command, [url], { stdio: "ignore", detached: true }).on("error", () => undefined).unref();
 }
 
+/** One line per plan from the shared pricing document (GET /api/v1/pricing). */
+export function pricingLines(doc) {
+  return doc.plans.map((plan) => {
+    const price = plan.price.monthly === null ? "custom" : plan.price.monthly === 0 ? "free" : `$${plan.price.monthly.toLocaleString("en-US")}/mo · $${plan.price.yearly.toLocaleString("en-US")}/yr`;
+    const included = plan.included.ai_translations_per_month === null ? "volume" : plan.included.ai_translations_per_month.toLocaleString("en-US");
+    const members = plan.limits.members === null ? "unlimited" : plan.limits.members;
+    const projects = plan.limits.projects === null ? "unlimited" : plan.limits.projects;
+    return { name: plan.name, text: `${price.padEnd(22)} ${included} AI translations/mo, ${members} members, ${projects} projects` };
+  });
+}
+
 async function pricing(flags) {
-  const response = await fetch(`${host()}/api/v1/get_pricing`, { headers: { "User-Agent": `glossa-cli/${VERSION}`, "X-Glossa-Integration": "cli" } });
+  const response = await fetch(`${host()}/api/v1/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]`));
+  const doc = await response.json();
+  if (flags.json || !isTTY) return print(doc, flags);
+  for (const line of pricingLines(doc)) console.log(`${bold(line.name.padEnd(11))} ${line.text}`);
+  console.log(dim(`\n${doc.unit}\nBuy (no account needed first): glossa upgrade --plan pro [--yearly] [--open]`));
 }
 
-async function billing(flags) {
+const usageLine = (label, usage) => `  ${label.padEnd(16)} ${usage.used.toLocaleString("en-US")} of ${usage.included === null ? "unlimited" : usage.included.toLocaleString("en-US")}`;
+
+async function billing(positional, flags) {
+  if (positional[0] === "portal") {
+    const result = await call("get_billing_link");
+    if (flags.json || !isTTY) print(result, flags);
+    else console.log(`${result.message}\n${result.url}`);
+    if (flags.open) openUrl(result.url);
+    return;
+  }
   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")}`);
+  for (const [label, usage] of [["AI translations", state.usage.ai_translations], ["members", state.usage.members], ["projects", state.usage.projects]]) console.log(usageLine(label, usage));
+  console.log(dim(`  card saved: ${state.payment_method_saved ? "yes" : "no"} · invoices and card: glossa billing portal`));
+}
+
+async function account(flags) {
+  const state = await call("get_account");
+  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.workspace.name)} ${dim(`(${state.workspace.slug}, ${state.role})`)}`);
+  console.log(`${bold(state.plan_name)} ${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(usageLine(label, usage));
+  if (state.next_tier) {
+    const adds = state.next_tier.adds;
+    const more = adds.ai_translations_per_month ? `${adds.ai_translations_per_month.toLocaleString("en-US")} AI translations/mo` : adds.ai_translations_per_month === null ? "volume pricing" : "";
+    console.log(dim(`\nNext: ${state.next_tier.name}${state.next_tier.price.monthly ? ` ($${state.next_tier.price.monthly}/mo)` : ""}${more ? `, ${more}` : ""} → ${state.next_tier.checkout_url}`));
   }
-  console.log(dim(`  card saved: ${state.payment_method_saved ? "yes" : "no"} · ${state.manage_url}`));
 }
 
 /**
@@ -176,13 +213,17 @@ async function subscribe(positional, flags) {
   } catch (error) {
     fail(error.message);
   }
-  const result = input.confirm ? await call("subscribe", input) : await call("create_checkout_link", input);
+  if (input.confirm && !apiKey()) fail("--confirm charges a saved card and needs `glossa login` first. Without it you get a checkout link.");
+  const result = input.confirm ? await call("subscribe", input) : await call("create_checkout_link", input, { anonymous: true });
   const url = result.url ?? result.checkout_url ?? null;
+  // Paid before signing in: remember the session so `glossa login` attaches it to the workspace.
+  if (!apiKey() && result.session_id) saveUserConfig({ ...userConfig(), pending_checkout: result.session_id });
   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);
+    if (!apiKey()) console.log(dim("After paying, run `glossa login`: the plan attaches to your workspace."));
   } else {
     console.log(green(`✓ ${result.status}: ${result.billing?.plan_name ?? input.plan} (${input.interval}ly)`));
   }
@@ -268,6 +309,26 @@ async function login(flags) {
   }
   const workspace = await call("get_workspace");
   console.log(green(`Signed in to ${workspace.name} (${workspace.slug}). Key saved to ${CONFIG_PATH}.`));
+  await claimPending();
+}
+
+/** Attaches a checkout paid before login (saved by `glossa upgrade`) to the workspace just signed in to. */
+async function claimPending() {
+  const config = userConfig();
+  if (!config.pending_checkout) return;
+  try {
+    const result = await call("claim_checkout", { session_id: config.pending_checkout });
+    console.log(green(`✓ ${result.billing.plan_name} is now this workspace's plan.`));
+    delete config.pending_checkout;
+    saveUserConfig(config);
+  } catch (error) {
+    if (error.body?.code === "checkout_incomplete") return console.log(dim("A checkout link is still open; finish paying, then run `glossa login` again (or `glossa claim_checkout --session-id …`)."));
+    if (["already_claimed", "not_found"].includes(error.body?.code)) {
+      delete config.pending_checkout;
+      saveUserConfig(config);
+    }
+    console.log(dim(`Could not attach the earlier checkout: ${error.message}`));
+  }
 }
 
 function logout() {
@@ -325,7 +386,8 @@ async function push(positional, flags) {
         `${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.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}`));
@@ -354,6 +416,70 @@ async function pull(positional, flags) {
   }
 }
 
+// ------------------------------------------------- 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);
@@ -404,14 +530,22 @@ ${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 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 pricing [--json]                   plans, prices and limits (no key needed)
+  glossa account                            plan, usage against every limit, next plan
   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 '{…}']  run any op (glossa ops lists them)
+  glossa billing portal [--open]            invoices, card, plan change, cancel (Stripe)
+  glossa upgrade --plan pro|team [--yearly] [--open]
+                                            Stripe Checkout link for a human, also before
+                                            signing in (\`glossa login\` attaches it after);
+                                            --confirm charges the saved card (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"]}
@@ -441,6 +575,10 @@ async function main() {
       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":
@@ -448,7 +586,9 @@ async function main() {
     case "pricing":
       return pricing(flags);
     case "billing":
-      return billing(flags);
+      return billing(positional, flags);
+    case "account":
+      return account(flags);
     case "subscribe":
     case "upgrade":
       return subscribe(positional, flags);
@@ -466,7 +606,7 @@ async function main() {
         console.log(`${bold(op.name)} — ${op.description}\n\n${JSON.stringify(op.input_schema, null, 2)}`);
         return;
       }
-      const input = { ...(flags.json ? JSON.parse(String(flags.json)) : {}), ...coerceFlags(flags, op.input_schema) };
+      const input = { ...(flags.json ? readJsonArg(flags.json) : {}), ...coerceFlags(flags, op.input_schema) };
       return print(await call(op.name, input), flags);
     }
   }

package/bin/glossa.test.mjs

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
-import { coerceFlags, deviceLogin, fileBody, fileText, parseArgs, subscribeInput } from "./glossa.mjs";
+import { coerceFlags, deviceLogin, fileBody, fileText, parseArgs, readJsonArg, fillBatches, pricingLines, subscribeInput } from "./glossa.mjs";
+import { pricingDocument } from "../../../lib/billing/pricing";
 
 describe("cli args", () => {
   it("parses flags and positionals", () => {
@@ -22,6 +23,26 @@ describe("subscribe", () => {
   });
 });
 
+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) });
@@ -80,3 +101,12 @@ describe("file bodies", () => {
     expect(fileText({ content: "x" })).toBe("x");
   });
 });
+
+describe("pricing", () => {
+  it("prints one line per plan from the shared pricing document", () => {
+    const lines = pricingLines(pricingDocument("agent-cli"));
+    expect(lines.map((l) => l.name)).toEqual(["Free", "Pro", "Team", "Enterprise"]);
+    expect(lines[1].text).toMatch(/^\$49\/mo · \$490\/yr .*25,000 AI translations\/mo, 10 members, unlimited projects$/);
+    expect(lines[3].text).toMatch(/^custom/);
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meterapp/glossa",
-  "version": "0.2.0",
+  "version": "0.4.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" },