@meterapp/glossa 0.7.0 → 0.7.2

package/README.md

@@ -91,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

@@ -10,7 +10,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.7.0";
+const VERSION = "0.7.2";
 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. */
@@ -110,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];
@@ -609,13 +611,14 @@ export function checkInput(flags, config, sources) {
 
 /**
  * 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.
+ * and folds the result into the verdict. A file whose source differs from Glossa's is compared
+ * only when the server rendered it from the commit (`outputs_from: "commit"`); older servers didn't.
  */
 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";
+      if (file.source === "changed" && file.outputs_from !== "commit") out.status = "not_comparable";
       else {
         const local = hashOf(out.path);
         out.status = local === null ? "missing" : local === out.sha256 ? "in_sync" : "stale";
@@ -1022,9 +1025,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:
@@ -1069,7 +1084,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

@@ -196,7 +196,7 @@ describe("check", () => {
     expect(() => checkInput({ stale: "maybe" }, config, [])).toThrow(/--stale/);
   });
 
-  it("compares the tree with pull's output and skips files whose source changed", () => {
+  it("compares the tree with pull's output and skips files whose source changed unless rendered from the commit", () => {
     const result = {
       ok: true,
       failures: [],
@@ -205,11 +205,12 @@ describe("check", () => {
       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") }] },
+        { source: "changed", outputs_from: "commit", outputs: [{ path: "web/es.json", sha256: syncHash("web") }] },
       ],
     };
-    const tree = { "es.json": syncHash("es"), "fr.json": syncHash("old") };
+    const tree = { "es.json": syncHash("es"), "fr.json": syncHash("old"), "web/es.json": syncHash("web") };
     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.files.flatMap((f) => f.outputs.map((o) => o.status))).toEqual(["in_sync", "stale", "missing", "not_comparable", "in_sync"]);
     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")] });
   });

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.7.0",
+  "version": "0.7.2",
   "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" },