glotfox 0.0.0-stage → 0.1.0

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+import {
+  check,
+  extract,
+  generateTypes,
+  init,
+  loadConfig,
+  pull,
+  push
+} from "./chunk-AQOIF7AF.js";
+
+// src/cli.ts
+import { parseArgs } from "node:util";
+var HELP = `glotfox - developer-first i18n toolkit
+
+Usage:
+  glotfox init [--source <locale>] [--targets <a,b,...>] [--force]
+  glotfox extract [--dry-run] [--force]
+  glotfox check [--strict]
+  glotfox types [--out <file>] [--dry-run]
+  glotfox push [--dry-run] [--api-url <url>]
+  glotfox pull [--dry-run] [--api-url <url>]
+  glotfox --help | --version
+
+Commands:
+  push      Upload the source-locale keys (and descriptions) to GlotFox.
+  pull      Download approved translations of the target locales into the
+            locale files. Authenticate with a project API key in GLOTFOX_API_KEY.
+  init      Write glotfox.config.json in the current directory.
+  extract   Scan source files for t('key'), <Trans i18nKey> and useTranslation,
+            and add new keys to the source-locale files. Never deletes anything;
+            keys no longer used in code are reported. Also regenerates the
+            type declarations when output.types is set.
+  check     Read-only CI check: exit 1 if code has keys missing from the locale
+            files (run extract), the generated types are out of date, or a
+            translation is not valid ICU. Other QA findings are warnings.
+  types     Generate a .d.ts with type-safe keys and ICU placeholder types.
+
+Options:
+  --dry-run   (extract, types) Report changes without writing files.
+  --out       (types) Output file (default: output.types from the config).
+  --strict    (check) Treat QA warnings as failures.
+  --force     (init) Overwrite an existing config. (extract) Overwrite existing descriptions.
+`;
+function printTypes(r) {
+  for (const w of r.warnings) console.warn(`warning: ${w}`);
+  console.log(`${r.written ? "Wrote" : "Up to date:"} ${r.file} (${r.keys} keys)`);
+}
+async function main(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" },
+      "dry-run": { type: "boolean" },
+      force: { type: "boolean" },
+      strict: { type: "boolean" },
+      source: { type: "string" },
+      targets: { type: "string" },
+      out: { type: "string" },
+      "api-url": { type: "string" }
+    }
+  });
+  const command = positionals[0];
+  if (values.version) {
+    console.log("0.1.0");
+    return 0;
+  }
+  if (values.help || !command) {
+    console.log(HELP);
+    return command || values.help ? 0 : 1;
+  }
+  const cwd = process.cwd();
+  if (command === "init") {
+    const targetLocales = values.targets?.split(",").map((s) => s.trim()).filter(Boolean);
+    console.log(`Created ${init({ cwd, sourceLocale: values.source, targetLocales, force: values.force })}`);
+    return 0;
+  }
+  if (command === "extract") {
+    const r = extract({ cwd, dryRun: values["dry-run"], force: values.force });
+    for (const w of r.warnings) console.warn(`warning: ${w}`);
+    console.log(`Scanned ${r.files} files, found ${r.found.length} keys.`);
+    console.log(`${values["dry-run"] ? "Would add" : "Added"} ${r.added.length} new key(s)${r.added.length ? ":" : "."}`);
+    for (const k of r.added) console.log(`  + ${k}`);
+    if (r.unused.length) {
+      console.log(`${r.unused.length} unused key(s) (kept; not found in code):`);
+      for (const k of r.unused) console.log(`  ? ${k}`);
+    }
+    if (!values["dry-run"] && loadConfig(cwd).config.output.types) printTypes(generateTypes({ cwd }));
+    return 0;
+  }
+  if (command === "check") {
+    const r = check({ cwd, strict: values.strict });
+    for (const w of r.warnings) console.warn(`warning: ${w}`);
+    for (const f of r.issues) {
+      const line = `${f.locale} ${f.key}: ${f.issue.message} [${f.issue.code}]`;
+      if (f.issue.severity === "error" || values.strict) console.error(`${f.issue.severity === "error" ? "error" : "warning"}: ${line}`);
+      else console.warn(`warning: ${line}`);
+    }
+    if (r.missing.length) {
+      console.error(`${r.missing.length} key(s) used in code but missing from the source locale; run \`glotfox extract\`:`);
+      for (const k of r.missing) console.error(`  + ${k}`);
+    }
+    if (r.typesStale) console.error(`${r.typesFile} is missing or out of date; run \`glotfox extract\` or \`glotfox types\`.`);
+    if (r.ok) console.log("OK: keys are extracted and types are up to date.");
+    return r.ok ? 0 : 1;
+  }
+  if (command === "types") {
+    printTypes(generateTypes({ cwd, out: values.out, dryRun: values["dry-run"] }));
+    return 0;
+  }
+  if (command === "push") {
+    const r = await push({ cwd, apiUrl: values["api-url"], dryRun: values["dry-run"] });
+    console.log(
+      values["dry-run"] ? `Would push ${r.keys} key(s).` : `Pushed ${r.keys} key(s): ${r.created} new, ${r.updated} existing.`
+    );
+    return 0;
+  }
+  if (command === "pull") {
+    const r = await pull({ cwd, apiUrl: values["api-url"], dryRun: values["dry-run"] });
+    for (const [locale, n] of Object.entries(r.received)) console.log(`${locale}: ${n} approved translation(s)`);
+    console.log(`${values["dry-run"] ? "Would write" : "Wrote"} ${r.written.length} file(s)${r.written.length ? ":" : "."}`);
+    for (const f of r.written) console.log(`  ${f}`);
+    return 0;
+  }
+  console.error(`Unknown command "${command}"
+`);
+  console.error(HELP);
+  return 1;
+}
+try {
+  process.exitCode = await main(process.argv.slice(2));
+} catch (e) {
+  console.error(`error: ${e.message}`);
+  process.exitCode = 1;
+}

package/dist/config.d.ts

@@ -0,0 +1,25 @@
+import { type FileFormat } from "./_shared/formats.js";
+export declare const CONFIG_FILE = "glotfox.config.json";
+export interface GlotfoxConfig {
+    version: number;
+    sourceLocale: string;
+    targetLocales: string[];
+    defaultNamespace: string;
+    include: string[];
+    exclude: string[];
+    output: {
+        dir: string;
+        pattern: string;
+        format: FileFormat;
+        emptyValues: "omit" | "empty";
+        types: string | null;
+    };
+}
+export declare const NAMESPACE_RE: RegExp;
+/** Validate a parsed config object and apply defaults (translation file format spec, section 6). */
+export declare function normalizeConfig(raw: unknown): GlotfoxConfig;
+/** Find the nearest config in `cwd` or an ancestor. Returns the config and its directory (the project root). */
+export declare function loadConfig(cwd: string): {
+    config: GlotfoxConfig;
+    root: string;
+};

package/dist/extract.d.ts

@@ -0,0 +1,45 @@
+import { type GlotfoxConfig } from "./config.js";
+export interface ExtractOptions {
+    cwd: string;
+    dryRun?: boolean;
+    /** Overwrite descriptions that already exist in the meta files. */
+    force?: boolean;
+}
+export interface ExtractResult {
+    files: number;
+    /** "ns:key" of keys found in code. */
+    found: string[];
+    added: string[];
+    /** Keys present in the source locale but not found in code. Never deleted. */
+    unused: string[];
+    warnings: string[];
+    written: string[];
+}
+type Messages = Record<string, string>;
+export declare function filePath(root: string, config: GlotfoxConfig, locale: string, namespace: string): string;
+/** Descriptions always live in a JSON `<namespace>.meta.json`, whatever the locale file format. */
+export declare function metaFilePath(root: string, config: GlotfoxConfig, locale: string, namespace: string): string;
+export declare function readMessages(file: string, config: GlotfoxConfig): Messages;
+/** Namespaces that already have a file for `locale`, derived from output.pattern. */
+export declare function existingNamespaces(root: string, config: GlotfoxConfig, locale: string): string[];
+/** A valid `t()` call found in code. */
+export interface CodeUse {
+    /** `namespace:key` */
+    id: string;
+    namespace: string;
+    key: string;
+    /** Path relative to the project root, with `/` separators. */
+    file: string;
+    line: number;
+    defaultValue?: string;
+    description?: string;
+    maxLength?: number;
+}
+/** Every valid key use in the files matched by `include`/`exclude`, plus warnings for the invalid ones. */
+export declare function scanProject(root: string, config: GlotfoxConfig): {
+    files: number;
+    uses: CodeUse[];
+    warnings: string[];
+};
+export declare function extract(opts: ExtractOptions): ExtractResult;
+export {};

package/dist/glob.d.ts

@@ -0,0 +1,5 @@
+/** Convert a glob (`*`, `**`, `?`, `{a,b}`) to a RegExp matching a "/"-separated relative path. */
+export declare function globToRegExp(glob: string): RegExp;
+/** List all files under `root` (relative, "/" separated), skipping node_modules and .git. */
+export declare function walk(root: string, rel?: string): string[];
+export declare function matchFiles(root: string, include: string[], exclude: string[]): string[];

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { extract, type ExtractOptions, type ExtractResult } from "./extract.js";
+export { init, type InitOptions } from "./init.js";
+export { loadConfig, normalizeConfig, type GlotfoxConfig } from "./config.js";
+export { generateTypes, messageArgs, type TypesOptions, type TypesResult } from "./types.js";
+export { push, pull, type SyncOptions, type PushResult, type PullResult } from "./sync.js";
+export { check, type CheckResult } from "./check.js";
+export { scanSource, type ExtractedKey } from "./scan.js";

package/dist/index.js

@@ -0,0 +1,24 @@
+import {
+  check,
+  extract,
+  generateTypes,
+  init,
+  loadConfig,
+  messageArgs,
+  normalizeConfig,
+  pull,
+  push,
+  scanSource
+} from "./chunk-AQOIF7AF.js";
+export {
+  check,
+  extract,
+  generateTypes,
+  init,
+  loadConfig,
+  messageArgs,
+  normalizeConfig,
+  pull,
+  push,
+  scanSource
+};

package/dist/init.d.ts

@@ -0,0 +1,8 @@
+export interface InitOptions {
+    cwd: string;
+    sourceLocale?: string;
+    targetLocales?: string[];
+    force?: boolean;
+}
+/** Write glotfox.config.json in `cwd`. Returns the file path. */
+export declare function init(opts: InitOptions): string;

package/dist/scan.d.ts

@@ -0,0 +1,18 @@
+/** Source scanner: finds t('key'), <Trans i18nKey=...> and useTranslation(ns) in JS/TS/JSX/TSX text. */
+export interface ExtractedKey {
+    namespace: string | null;
+    key: string;
+    defaultValue?: string;
+    description?: string;
+    /** Character limit from `{ maxLength: 20 }`. */
+    maxLength?: number;
+    line: number;
+}
+export declare const KEY_RE: RegExp;
+export declare const MAX_KEY_LENGTH = 128;
+/** Read a '...', "..." or `...` literal (without ${}) starting at `i`. */
+export declare function readString(src: string, i: number): {
+    value: string;
+    end: number;
+} | null;
+export declare function scanSource(src: string): ExtractedKey[];

package/dist/sync.d.ts

@@ -0,0 +1,37 @@
+export declare const DEFAULT_API_URL = "https://glotfox.app.dukauskas.lt";
+export interface KeyReference {
+    file: string;
+    line: number;
+}
+export interface PushKey {
+    key: string;
+    value: string;
+    context?: string;
+    maxLength?: number;
+    references: KeyReference[];
+}
+export interface SyncOptions {
+    cwd: string;
+    /** Project API key (`gf_…`); defaults to $GLOTFOX_API_KEY. */
+    apiKey?: string;
+    /** Server base URL; defaults to $GLOTFOX_API_URL, then the hosted service. */
+    apiUrl?: string;
+    /** Injectable for tests. */
+    fetch?: typeof fetch;
+    dryRun?: boolean;
+}
+export interface PushResult {
+    keys: number;
+    created: number;
+    updated: number;
+}
+export interface PullResult {
+    /** Files written (or that would be, with dryRun). */
+    written: string[];
+    /** Number of approved translations received per locale. */
+    received: Record<string, number>;
+}
+/** Upload the source-locale keys (and their descriptions) to the project. */
+export declare function push(opts: SyncOptions): Promise<PushResult>;
+/** Download approved translations of every target locale into the locale files. */
+export declare function pull(opts: SyncOptions): Promise<PullResult>;

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+export interface TypesOptions {
+    cwd: string;
+    /** Override output.types (relative to the project root). */
+    out?: string;
+    dryRun?: boolean;
+}
+export interface TypesResult {
+    file: string;
+    keys: number;
+    warnings: string[];
+    written: boolean;
+}
+/** Map of argument name -> set of TypeScript types, derived from an ICU message. Throws on malformed input. */
+export declare function messageArgs(message: string): Map<string, Set<string>>;
+/** Render the declaration file text for an `ns -> key -> message` catalog. */
+export declare function renderTypes(catalog: Map<string, Record<string, string>>, defaultNamespace: string, warnings?: string[]): {
+    text: string;
+    keys: number;
+};
+/** Generate the TypeScript declaration file from the source-locale files. */
+export declare function generateTypes(opts: TypesOptions): TypesResult;

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "glotfox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "GlotFox CLI: extract translation keys from React/Next.js and vanilla JS/TS projects",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "glotfox": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@glotfox/shared": "0.0.0",
+    "@types/node": "^22.10.0",
+    "esbuild": "^0.25.12",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }