@meterapp/glossa 0.2.0 → 0.3.0

package/README.md

@@ -7,6 +7,8 @@ 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
@@ -19,6 +21,11 @@ npx @meterapp/glossa subscribe pro --interval year --open   # Stripe Checkout li
 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.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";
@@ -120,6 +120,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");
@@ -325,7 +333,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 +363,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,6 +477,11 @@ ${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)
@@ -411,7 +489,7 @@ ${bold("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 <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 +519,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":
@@ -466,7 +548,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,5 @@
 import { describe, expect, it } from "vitest";
-import { coerceFlags, deviceLogin, fileBody, fileText, parseArgs, subscribeInput } from "./glossa.mjs";
+import { coerceFlags, deviceLogin, fileBody, fileText, parseArgs, readJsonArg, fillBatches, subscribeInput } from "./glossa.mjs";
 
 describe("cli args", () => {
   it("parses flags and positionals", () => {
@@ -22,6 +22,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) });

package/package.json

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