@factorialco/fcode-cli 2.1.0 → 2.2.0

package/dist/services/locale-merger.d.ts

@@ -0,0 +1,23 @@
+import { Locale } from '../core/types';
+/**
+ * Collapses the locale files a workspace inherits into one file per identifier.
+ *
+ * The cloud lists a locale once per workspace that defines it, and every one of them is live: an
+ * override is layered over its parent key by key, so a locale several workspaces define is several
+ * files. A workspace directory keeps one inherited file per identifier instead — one file cannot
+ * hold two names — so the parents' files are merged here, in the order the cloud resolves them.
+ *
+ * A single parent's file is kept verbatim, comments and nesting included. Only a locale that
+ * several parents define is rewritten, as a flat mapping of dotted keys, which is the shape the
+ * lookup uses anyway and the one shape where a nested and a dotted key cannot disagree.
+ */
+export declare function mergeInheritedLocales(locales: Array<Locale>): Array<Locale>;
+/**
+ * Locale identifiers are case-sensitive on the platform (pt-BR and pt-br are different locales),
+ * but the filesystems macOS and Windows usually run on are not — both identifiers would collapse
+ * into one file, so a pull would write one locale over the other, `status` would report a phantom
+ * change forever, and the next push would silently overwrite one locale's cloud content with the
+ * other's. Refused outright before anything is written; on a case-sensitive filesystem the files
+ * live side by side and nothing is refused.
+ */
+export declare function assertLocaleFilesCanCoexist(locales: Array<Locale>, filesystemKeepsCase?: boolean): void;

package/dist/services/locale-merger.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeInheritedLocales = mergeInheritedLocales;
+exports.assertLocaleFilesCanCoexist = assertLocaleFilesCanCoexist;
+const fs = require("fs-extra");
+const os = require("node:os");
+const path = require("node:path");
+const yaml_1 = require("yaml");
+const color_1 = require("@oclif/color");
+const cli_1 = require("../utils/cli");
+const types_1 = require("../core/types");
+const locale_resolver_1 = require("./locale-resolver");
+/**
+ * Collapses the locale files a workspace inherits into one file per identifier.
+ *
+ * The cloud lists a locale once per workspace that defines it, and every one of them is live: an
+ * override is layered over its parent key by key, so a locale several workspaces define is several
+ * files. A workspace directory keeps one inherited file per identifier instead — one file cannot
+ * hold two names — so the parents' files are merged here, in the order the cloud resolves them.
+ *
+ * A single parent's file is kept verbatim, comments and nesting included. Only a locale that
+ * several parents define is rewritten, as a flat mapping of dotted keys, which is the shape the
+ * lookup uses anyway and the one shape where a nested and a dotted key cannot disagree.
+ */
+function mergeInheritedLocales(locales) {
+    const inheritedByIdentifier = new Map();
+    for (const locale of locales.filter((locale) => locale.resolvingTeamSlug)) {
+        inheritedByIdentifier.set(locale.locale, [...(inheritedByIdentifier.get(locale.locale) ?? []), locale]);
+    }
+    return [
+        ...locales.filter((locale) => !locale.resolvingTeamSlug),
+        ...[...inheritedByIdentifier.values()].map((files) => (files.length === 1 ? files[0] : mergeLocaleFiles(files))),
+    ];
+}
+/**
+ * The platform walks parents sorted by their slug — `Team.parentTeamIdsInResolutionOrder` — and
+ * the first defining a key wins. Deriving that order here, rather than trusting the order the API
+ * happened to list the rows in (which follows the listing's `orderBy`, `updatedAt` by default),
+ * is what keeps a local run and the cloud resolving the same text.
+ */
+function inResolutionOrder(files) {
+    return [...files].sort((a, b) => {
+        const [aSlug, bSlug] = [a.resolvingTeamSlug ?? '', b.resolvingTeamSlug ?? ''];
+        return aSlug < bSlug ? -1 : (aSlug > bSlug ? 1 : 0);
+    });
+}
+/**
+ * @param files the same locale as every parent workspace defines it, in any order
+ * @returns one locale carrying their merged translations, attributed to the winning parent
+ */
+function mergeLocaleFiles(files) {
+    const ordered = inResolutionOrder(files);
+    const [winner] = ordered;
+    const translations = {};
+    // Lowest precedence first, so the first parent in resolution order is the text that survives —
+    // the same layering the platform applies.
+    for (const file of [...ordered].reverse()) {
+        Object.assign(translations, translationsOf(file));
+    }
+    return new types_1.Locale(winner.id, winner.locale, `${mergeHeader(ordered)}${(0, yaml_1.stringify)(translations)}`, winner.resolvingTeamSlug);
+}
+function translationsOf(file) {
+    try {
+        return (0, locale_resolver_1.flattenTranslations)((0, yaml_1.parse)(file.content));
+    }
+    catch (error) {
+        // Skipped rather than fatal: a workspace cannot fix a parent's file, and the cloud ignores an
+        // unparseable one too.
+        cli_1.default.log(color_1.default.yellow(`\n⚠️  locale '${file.locale}' from workspace '${file.resolvingTeamSlug}' could not be parsed and will be ignored: ${error.message}`));
+        return {};
+    }
+}
+/**
+ * Locale identifiers are case-sensitive on the platform (pt-BR and pt-br are different locales),
+ * but the filesystems macOS and Windows usually run on are not — both identifiers would collapse
+ * into one file, so a pull would write one locale over the other, `status` would report a phantom
+ * change forever, and the next push would silently overwrite one locale's cloud content with the
+ * other's. Refused outright before anything is written; on a case-sensitive filesystem the files
+ * live side by side and nothing is refused.
+ */
+function assertLocaleFilesCanCoexist(locales, filesystemKeepsCase = filesystemKeepsCaseApart()) {
+    const slugsByFoldedSlug = new Map();
+    for (const locale of locales) {
+        const slug = locale.slug ?? locale.locale;
+        const folded = slug.toLowerCase();
+        slugsByFoldedSlug.set(folded, [...(slugsByFoldedSlug.get(folded) ?? []), slug]);
+    }
+    const collisions = [...slugsByFoldedSlug.values()].filter((slugs) => slugs.length > 1);
+    if (collisions.length === 0 || filesystemKeepsCase) {
+        return;
+    }
+    const described = collisions.map((slugs) => `'${slugs.join("' / '")}'`).join(', ');
+    throw new Error(`locales differing only in case cannot both be stored on this filesystem: ${described}. ` +
+        'Rename or remove one of them in the cloud and pull again.');
+}
+function filesystemKeepsCaseApart() {
+    const probe = fs.mkdtempSync(path.join(os.tmpdir(), 'fcode-case-'));
+    try {
+        fs.outputFileSync(path.join(probe, 'a'), '');
+        return !fs.existsSync(path.join(probe, 'A'));
+    }
+    finally {
+        fs.removeSync(probe);
+    }
+}
+function mergeHeader(files) {
+    const workspaces = files.map((file) => file.resolvingTeamSlug).join(', ');
+    return (`# Generated by fcode: the '${files[0].locale}' translations inherited from ${workspaces},\n` +
+        `# merged in the platform's resolution order (the first wins where they disagree).\n` +
+        `# Edit i18n/${files[0].locale}.yaml to override any of these keys.\n`);
+}

package/dist/services/locale-resolver.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Builds the translations a local run resolves `fcode.i18n` against, so `fcode run` behaves like
+ * the cloud does.
+ *
+ * The cloud does this work in the engine: it merges the workspace's locale over its parents', then
+ * layers the chosen locale over the primary one and ships a single flat map. Locally there is no
+ * engine, so the same layering happens here over the files in `i18n/` — including the inherited
+ * ones, which `pull` writes into the same directory as `<locale>.inherited.yaml`.
+ */
+export declare function flattenTranslations(document: unknown, prefix?: string, target?: Record<string, string>): Record<string, string>;
+/**
+ * @param requestedLocale the locale to run with, or undefined to use the workspace's primary
+ * @returns the locale actually used and its flat translations, with the primary locale underneath
+ */
+export declare function resolveLocalTranslations(requestedLocale?: string, workspaceDir?: string): {
+    locale?: string;
+    translations: Record<string, string>;
+};

package/dist/services/locale-resolver.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flattenTranslations = flattenTranslations;
+exports.resolveLocalTranslations = resolveLocalTranslations;
+const fs = require("fs-extra");
+const path = require("node:path");
+const yaml_1 = require("yaml");
+const cli_1 = require("../utils/cli");
+const color_1 = require("@oclif/color");
+const types_1 = require("../core/types");
+const I18N_DIRECTORY = 'i18n';
+const YAML_EXTENSION = '.yaml';
+const KEY_SEPARATOR = '.';
+/**
+ * Builds the translations a local run resolves `fcode.i18n` against, so `fcode run` behaves like
+ * the cloud does.
+ *
+ * The cloud does this work in the engine: it merges the workspace's locale over its parents', then
+ * layers the chosen locale over the primary one and ships a single flat map. Locally there is no
+ * engine, so the same layering happens here over the files in `i18n/` — including the inherited
+ * ones, which `pull` writes into the same directory as `<locale>.inherited.yaml`.
+ */
+function flattenTranslations(document, prefix = '', target = {}) {
+    if (document === null || document === undefined || typeof document !== 'object' || Array.isArray(document)) {
+        return target;
+    }
+    for (const [key, value] of Object.entries(document)) {
+        const keyPath = prefix ? `${prefix}${KEY_SEPARATOR}${key}` : key;
+        if (value === null || value === undefined) {
+            // A key written without a value is a placeholder: it counts as not translated, so lookups
+            // fall through to the fallback locale instead of resolving to an empty string.
+            continue;
+        }
+        if (typeof value === 'object' && !Array.isArray(value)) {
+            flattenTranslations(value, keyPath, target);
+        }
+        else if (!Array.isArray(value)) {
+            target[keyPath] = String(value);
+        }
+    }
+    return target;
+}
+function readLocaleFile(workspaceDir, slug) {
+    const filePath = path.join(workspaceDir, I18N_DIRECTORY, `${slug}${YAML_EXTENSION}`);
+    if (!fs.pathExistsSync(filePath)) {
+        return {};
+    }
+    try {
+        return flattenTranslations((0, yaml_1.parse)(fs.readFileSync(filePath).toString()));
+    }
+    catch (error) {
+        // A broken translation file must never stop a run, exactly as in the cloud.
+        cli_1.default.log(color_1.default.yellow(`\n⚠️  locale '${slug}' could not be parsed and will be ignored: ${error.message}`));
+        return {};
+    }
+}
+/** The identifier a locale file contributes keys to, whether the workspace owns the file or not. */
+function identifierOf(slug) {
+    return slug.endsWith(types_1.Locale.INHERITED_SUFFIX) ? slug.slice(0, -types_1.Locale.INHERITED_SUFFIX.length) : slug;
+}
+/**
+ * One locale as this workspace resolves it: what it inherits, with its own file layered on top key
+ * by key, so a key it does not translate itself still resolves to the parent's text. `pull` has
+ * already merged the parents' files into the inherited one.
+ */
+function readLocale(workspaceDir, locale) {
+    return {
+        ...readLocaleFile(workspaceDir, `${locale}${types_1.Locale.INHERITED_SUFFIX}`),
+        ...readLocaleFile(workspaceDir, locale),
+    };
+}
+function chosenPrimaryLocaleOf(workspaceDir) {
+    try {
+        const team = fs.readJsonSync(path.join(workspaceDir, 'team.json'));
+        return typeof team?.primaryLocale === 'string' && team.primaryLocale.length > 0 ? team.primaryLocale : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Every locale file in the workspace, own and inherited: `pull` writes them all to `i18n/`. */
+function localeFileSlugs(workspaceDir) {
+    const directory = path.join(workspaceDir, I18N_DIRECTORY);
+    if (!fs.pathExistsSync(directory)) {
+        return [];
+    }
+    return fs
+        .readdirSync(directory)
+        .filter((fileName) => fileName.endsWith(YAML_EXTENSION))
+        .map((fileName) => path.basename(fileName, YAML_EXTENSION))
+        .sort();
+}
+/** Every locale the workspace resolves, counting a locale defined in several workspaces once. */
+function availableLocales(workspaceDir) {
+    return [...new Set(localeFileSlugs(workspaceDir).map((slug) => identifierOf(slug)))].sort();
+}
+/**
+ * The workspace's primary locale: the one chosen in `team.json`, or its first locale when none is
+ * chosen — or when the chosen one has no file anymore, which would otherwise resolve zero keys.
+ * Mirrors the platform's `PrimaryLocale.resolve`, so a local run and the cloud agree on which
+ * locale a process without an explicit one resolves against.
+ */
+function primaryLocaleOf(workspaceDir) {
+    const available = availableLocales(workspaceDir);
+    const chosen = chosenPrimaryLocaleOf(workspaceDir);
+    return chosen && available.includes(chosen) ? chosen : available[0];
+}
+/**
+ * @param requestedLocale the locale to run with, or undefined to use the workspace's primary
+ * @returns the locale actually used and its flat translations, with the primary locale underneath
+ */
+function resolveLocalTranslations(requestedLocale, workspaceDir = process.cwd()) {
+    const primary = primaryLocaleOf(workspaceDir);
+    const locale = requestedLocale || primary;
+    if (!locale) {
+        return { locale: undefined, translations: {} };
+    }
+    const fallback = primary && primary !== locale ? readLocale(workspaceDir, primary) : {};
+    return { locale, translations: { ...fallback, ...readLocale(workspaceDir, locale) } };
+}

package/dist/services/process-runner.d.ts

@@ -10,6 +10,7 @@ export type RunProcessOptions = {
     variablesOverride?: Variable[];
     extraVariablesFile?: string;
     suppressElapsedLog?: boolean;
+    locale?: string;
 };
 export type RunHookOptions = {
     logLevel?: string;

package/dist/services/process-runner.js

@@ -34,7 +34,7 @@ function mergeVariables(base, ...overrides) {
     return [...map.values()];
 }
 async function runProcess(options) {
-    const { slug, version, logLevel = 'DEBUG', request, jsonLogs = false, suppressElapsedLog = false } = options;
+    const { slug, version, logLevel = 'DEBUG', request, jsonLogs = false, suppressElapsedLog = false, locale } = options;
     const processRepository = new process_1.default();
     const variableRepository = new variable_1.default();
     const fcodeProcess = await processRepository.find(slug, version);
@@ -50,7 +50,7 @@ async function runProcess(options) {
         }
     }
     const ExecutionTask = fcodeProcess.script.programmingLanguage === 'PYTHON' ? python_execution_task_1.default : javascript_execution_task_1.default;
-    const executor = new ExecutionTask(fcodeProcess.script.programmingLanguage, fcodeProcess, { version, parameters, variables, logLevel, request, jsonLogs });
+    const executor = new ExecutionTask(fcodeProcess.script.programmingLanguage, fcodeProcess, { version, parameters, variables, logLevel, request, jsonLogs, locale });
     const start = Date.now();
     try {
         await executor.prepare();

package/dist/utils/gitignore.d.ts

@@ -14,6 +14,6 @@ export declare function renderGitignoreWithInherited(existing: string, inherited
  * parent team and pulled read-only) are not tracked by git. Regenerated from the
  * current workspace metadata, so resources that stop being inherited drop out.
  * Inherited variable values live in one file, which is ignored as soon as the
- * workspace inherits any variable.
+ * workspace inherits any variable; inherited locales are one file each, like modules.
  */
 export declare function syncInheritedGitignore(workspaceDir?: string): Promise<void>;

package/dist/utils/gitignore.js

@@ -46,7 +46,7 @@ function stripManagedBlock(content) {
  * parent team and pulled read-only) are not tracked by git. Regenerated from the
  * current workspace metadata, so resources that stop being inherited drop out.
  * Inherited variable values live in one file, which is ignored as soon as the
- * workspace inherits any variable.
+ * workspace inherits any variable; inherited locales are one file each, like modules.
  */
 async function syncInheritedGitignore(workspaceDir = process.cwd()) {
     const team = await new workspace_1.default(workspaceDir).getActiveTeam();
@@ -59,6 +59,9 @@ async function syncInheritedGitignore(workspaceDir = process.cwd()) {
             .filter((module) => module.resolvingTeamSlug)
             .map((module) => `modules/${(0, filenamify_1.default)(module.name)}/`),
         ...(Object.values(team.variables ?? {}).some((variable) => variable.resolvingTeamSlug) ? [inheritedVariablesFileName] : []),
+        ...Object.values(team.i18n ?? {})
+            .filter((locale) => locale.resolvingTeamSlug)
+            .map((locale) => `i18n/${(0, filenamify_1.default)(locale.slug)}.yaml`),
     ];
     const gitignorePath = path.join(workspaceDir, '.gitignore');
     const existing = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, 'utf8') : '';

package/oclif.manifest.json

@@ -506,6 +506,13 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "locale": {
+          "description": "Locale fcode.i18n resolves against (defaults to the workspace primaryLocale)",
+          "name": "locale",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "variablesFile": {
           "char": "e",
           "description": "Path to a .env file whose variables override workspace variables",
@@ -876,6 +883,192 @@
         "status.js"
       ]
     },
+    "i18n:add": {
+      "aliases": [],
+      "args": {
+        "resourceSlug": {
+          "description": "Resource slug",
+          "name": "resourceSlug"
+        }
+      },
+      "description": "Keeps track of new local locales",
+      "examples": [
+        "$ fcode i18n:add",
+        "$ fcode i18n:add pt-BR"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "i18n:add",
+      "pluginAlias": "@factorialco/fcode-cli",
+      "pluginName": "@factorialco/fcode-cli",
+      "pluginType": "core",
+      "strict": true,
+      "isESM": false,
+      "relativePath": [
+        "dist",
+        "commands",
+        "i18n",
+        "add.js"
+      ]
+    },
+    "i18n:pull": {
+      "aliases": [],
+      "args": {
+        "resourceSlug": {
+          "description": "Resource slug",
+          "name": "resourceSlug"
+        }
+      },
+      "description": "Fetch all locales from cloud and save them locally",
+      "examples": [
+        "$ fcode i18n:pull"
+      ],
+      "flags": {
+        "force": {
+          "char": "f",
+          "description": "Force command",
+          "name": "force",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "i18n:pull",
+      "pluginAlias": "@factorialco/fcode-cli",
+      "pluginName": "@factorialco/fcode-cli",
+      "pluginType": "core",
+      "strict": true,
+      "isESM": false,
+      "relativePath": [
+        "dist",
+        "commands",
+        "i18n",
+        "pull.js"
+      ]
+    },
+    "i18n:push": {
+      "aliases": [],
+      "args": {
+        "resourceSlug": {
+          "description": "Resource slug",
+          "name": "resourceSlug"
+        }
+      },
+      "description": "Create or update cloud locales from local ones",
+      "examples": [
+        "$ fcode i18n:push",
+        "$ fcode i18n:push pt-BR"
+      ],
+      "flags": {
+        "force": {
+          "char": "f",
+          "description": "Force command",
+          "name": "force",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "i18n:push",
+      "pluginAlias": "@factorialco/fcode-cli",
+      "pluginName": "@factorialco/fcode-cli",
+      "pluginType": "core",
+      "strict": true,
+      "isESM": false,
+      "relativePath": [
+        "dist",
+        "commands",
+        "i18n",
+        "push.js"
+      ]
+    },
+    "i18n:remove": {
+      "aliases": [],
+      "args": {
+        "resourceSlug": {
+          "description": "Resource slug",
+          "name": "resourceSlug"
+        }
+      },
+      "description": "Remove track of a local locale",
+      "examples": [
+        "$ fcode i18n:remove pt-BR"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "i18n:remove",
+      "pluginAlias": "@factorialco/fcode-cli",
+      "pluginName": "@factorialco/fcode-cli",
+      "pluginType": "core",
+      "strict": true,
+      "isESM": false,
+      "relativePath": [
+        "dist",
+        "commands",
+        "i18n",
+        "remove.js"
+      ]
+    },
+    "i18n:reset": {
+      "aliases": [],
+      "args": {
+        "resourceSlug": {
+          "description": "Resource slug",
+          "name": "resourceSlug"
+        }
+      },
+      "description": "Reset locales with contents from current remote",
+      "examples": [
+        "$ fcode i18n:reset"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "i18n:reset",
+      "pluginAlias": "@factorialco/fcode-cli",
+      "pluginName": "@factorialco/fcode-cli",
+      "pluginType": "core",
+      "strict": true,
+      "isESM": false,
+      "relativePath": [
+        "dist",
+        "commands",
+        "i18n",
+        "reset.js"
+      ]
+    },
+    "i18n:status": {
+      "aliases": [],
+      "args": {
+        "resourceSlug": {
+          "description": "Resource slug",
+          "name": "resourceSlug"
+        }
+      },
+      "description": "List all locales status",
+      "examples": [
+        "$ fcode i18n:status"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "i18n:status",
+      "pluginAlias": "@factorialco/fcode-cli",
+      "pluginName": "@factorialco/fcode-cli",
+      "pluginType": "core",
+      "strict": true,
+      "isESM": false,
+      "relativePath": [
+        "dist",
+        "commands",
+        "i18n",
+        "status.js"
+      ]
+    },
     "modules:add": {
       "aliases": [],
       "args": {
@@ -1970,5 +2163,5 @@
       ]
     }
   },
-  "version": "2.1.0"
+  "version": "2.2.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@factorialco/fcode-cli",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "packageManager": "pnpm@11.7.0",
   "description": "Factorial Code Command Line Interface",
   "homepage": "https://code.factorialhr.com/docs/cli/",
@@ -41,6 +41,7 @@
     "openid-client": "^5.6.5",
     "string-width": "^4.2.3",
     "strip-comments": "^2.0.1",
+    "yaml": "^2.8.1",
     "zod": "^4.4.3"
   },
   "peerDependencies": {