@factorialco/fcode-cli 3.4.0 → 3.5.1

package/README.md

@@ -20,7 +20,7 @@ $ npm install -g @factorialco/fcode-cli
 $ fcode COMMAND
 running command...
 $ fcode (--version)
-@factorialco/fcode-cli/3.4.0 linux-x64 node-v22.22.3
+@factorialco/fcode-cli/3.5.1 linux-x64 node-v22.22.3
 $ fcode --help [COMMAND]
 USAGE
   $ fcode COMMAND

package/dist/core/executors/javascript-execution-task.js

@@ -606,25 +606,38 @@ const main = typeof _hooksModule['${fn}'] === 'function'
         i18n: Object.assign((key, args, options) => {
           const translations = ${JSON.stringify(metadata.i18n.translations, null, 2)};
           const byLocale = ${JSON.stringify(metadata.i18n.byLocale, null, 2)};
+          const primaryLocale = ${JSON.stringify(metadata.i18n.primaryLocale ?? null)};
           const requested = options && typeof options === 'object' && options.locale !== undefined && options.locale !== null
             ? String(options.locale)
             : undefined;
           // An identifier no locale matches is shortened one segment at a time ('en-gb' reads
-          // 'en'), by name first and ignoring case only as a last resort — the same chain the
-          // cloud resolves, so a local run answers a regional variant the same way.
+          // 'en'), by name first and ignoring case only as a last resort, and a language that
+          // still matches nothing is broadened to a regional locale of it ('es' reads 'es-ES',
+          // the primary one if it is among them, else the alphabetically first) — the same chain
+          // the cloud resolves, so a local run answers the same identifiers the same way.
+          const names = Object.keys(byLocale);
+          const matching = (candidate) => names.includes(candidate)
+            ? candidate
+            : names.filter((name) => name.toLowerCase() === candidate.toLowerCase()).sort()[0];
           const localeMaps = [];
-          for (let candidate = requested; candidate; ) {
-            const names = Object.keys(byLocale);
-            const lowered = candidate.toLowerCase();
-            const match = names.includes(candidate)
-              ? candidate
-              : names.filter((name) => name.toLowerCase() === lowered).sort()[0];
+          const add = (match) => {
             if (match !== undefined && !localeMaps.includes(byLocale[match])) {
               localeMaps.push(byLocale[match]);
             }
+          };
+          let language;
+          for (let candidate = requested; candidate; ) {
+            add(matching(candidate));
+            language = candidate;
             const lastSeparator = Math.max(candidate.lastIndexOf('-'), candidate.lastIndexOf('_'));
             candidate = lastSeparator > 0 ? candidate.slice(0, lastSeparator) : undefined;
           }
+          if (language !== undefined && !/[-_]/.test(language) && matching(language) === undefined) {
+            const sameLanguage = names
+              .filter((name) => name.split(/[-_]/)[0].toLowerCase() === language.toLowerCase())
+              .sort();
+            add(sameLanguage.includes(primaryLocale) ? primaryLocale : sameLanguage[0]);
+          }
           let template;
           for (const localeMap of localeMaps) {
             template = Object.hasOwn(localeMap, key) ? localeMap[key] : undefined;

package/dist/core/resource-pusher.js

@@ -6,6 +6,7 @@ const resource_checker_1 = require("../services/resource-checker");
 const promise_1 = require("../utils/promise");
 const types_1 = require("./types");
 const variable_warnings_1 = require("../utils/variable-warnings");
+const file_parameter_warnings_1 = require("../utils/file-parameter-warnings");
 const global_1 = require("../config/global");
 const settings_1 = require("../config/settings");
 class ResourcePusher {
@@ -64,7 +65,10 @@ class ResourcePusher {
     async pushResource(resource) {
         try {
             if (this._repository._repositoryName === 'processes') {
-                const updatedProcess = await this._fcodeGraphQLClient.pushProcess(resource);
+                const process = resource;
+                // Only the processes being pushed are named, so each gets fixed by whoever next touches it.
+                (0, file_parameter_warnings_1.warnDeprecatedFileFields)(process.slug, (0, file_parameter_warnings_1.deprecatedFileFields)(process.script?.parametersSchema));
+                const updatedProcess = await this._fcodeGraphQLClient.pushProcess(process);
                 return this._repository.save(updatedProcess);
             }
             if (this._repository._repositoryName === 'modules') {

package/dist/runtime/libs/python/fcode/context.py

@@ -96,6 +96,7 @@ class I18n:
         payload = i18n_payload or {}
         self.__translations = payload.get("translations") or {}
         self.__by_locale = payload.get("byLocale") or {}
+        self.__primary_locale = payload.get("primaryLocale")
         self.locale = payload.get("locale")
 
     def __call__(self, key, args=None, options=None):
@@ -125,24 +126,43 @@ class I18n:
         """The maps a requested locale opens, most specific first.
 
         An identifier no locale matches is shortened one segment at a time ("en-gb" reads "en"),
-        by name first and ignoring case only as a last resort -- the same chain the cloud
-        executors resolve, so a local run answers a regional variant the same way.
+        by name first and ignoring case only as a last resort, and a language that still matches
+        nothing is broadened to a regional locale of it ("es" reads "es-ES", the primary one if it
+        is among them, else the alphabetically first) -- the same chain the cloud executors
+        resolve, so a local run answers the same identifiers the same way.
         """
         if locale is None or not self.__by_locale:
             return []
+        import re
+
         names = list(self.__by_locale.keys())
         chain = []
-        candidate = locale
-        while candidate:
+
+        def matching(candidate):
             if candidate in names:
-                match = candidate
-            else:
-                folded = sorted(n for n in names if n.lower() == candidate.lower())
-                match = folded[0] if folded else None
+                return candidate
+            folded = sorted(n for n in names if n.lower() == candidate.lower())
+            return folded[0] if folded else None
+
+        def add(match):
             if match is not None and match not in chain:
                 chain.append(match)
+
+        candidate = locale
+        language = None
+        while candidate:
+            add(matching(candidate))
+            language = candidate
             last_separator = max(candidate.rfind("-"), candidate.rfind("_"))
             candidate = candidate[:last_separator] if last_separator > 0 else None
+        if language and not re.search(r"[-_]", language) and matching(language) is None:
+            same_language = sorted(
+                n for n in names if re.split(r"[-_]", n)[0].lower() == language.lower()
+            )
+            if self.__primary_locale in same_language:
+                add(self.__primary_locale)
+            elif same_language:
+                add(same_language[0])
         return [self.__by_locale[name] for name in chain if self.__by_locale[name]]
 
 

package/dist/services/fcode-graphql-client.js

@@ -4,6 +4,11 @@ const graphql_request_1 = require("graphql-request");
 const types_1 = require("../core/types");
 const locale_merger_1 = require("./locale-merger");
 const _ = require("lodash");
+// Source code travels base64 encoded: Cloudflare's WAF blocks requests whose body
+// looks like an attack payload, which source code often does. sourceCodeEncoding tells the
+// API to decode it back.
+const SOURCE_CODE_ENCODING = 'BASE64';
+const encodeSourceCode = (sourceCode) => sourceCode == null ? sourceCode : Buffer.from(sourceCode, 'utf8').toString('base64');
 // Manifest fields an fcode-api older than this CLI may not know. The manifest query falls back to a
 // narrower selection when the error names one of them, so a CLI stays usable against an
 // on-premises api that has not been updated yet.
@@ -261,8 +266,19 @@ class FcodeGraphQLClient {
     createVersionedProcesses(versionedProcess) {
         return this.client
             .request((0, graphql_request_1.gql) `
-          mutation publishProcess($processId: ID!, $tag: String!, $sourceCode: String, $parametersSchema: JSON, $readme: String) {
-            publishProcess(processId: $processId, tag: $tag, input: { sourceCode: $sourceCode, parametersSchema: $parametersSchema, readme: $readme }) {
+          mutation publishProcess(
+            $processId: ID!
+            $tag: String!
+            $sourceCode: String
+            $sourceCodeEncoding: SourceCodeEncoding
+            $parametersSchema: JSON
+            $readme: String
+          ) {
+            publishProcess(
+              processId: $processId
+              tag: $tag
+              input: { sourceCode: $sourceCode, sourceCodeEncoding: $sourceCodeEncoding, parametersSchema: $parametersSchema, readme: $readme }
+            ) {
               id
             }
           }
@@ -271,7 +287,8 @@ class FcodeGraphQLClient {
             tag: versionedProcess.tag,
             parametersSchema: versionedProcess.script.parametersSchema,
             readme: versionedProcess.readme,
-            sourceCode: versionedProcess.script.sourceCode,
+            sourceCode: encodeSourceCode(versionedProcess.script.sourceCode),
+            sourceCodeEncoding: SOURCE_CODE_ENCODING,
         })
             .catch((error) => {
             return Promise.reject(this.cleanError(error));
@@ -330,15 +347,20 @@ class FcodeGraphQLClient {
     createVersionedScriptLibrary(versionedScriptLibrary) {
         return this.client
             .request((0, graphql_request_1.gql) `
-          mutation publishScriptLibrary($scriptLibraryId: ID!, $tag: String!, $sourceCode: String) {
-            publishScriptLibrary(scriptLibraryId: $scriptLibraryId, tag: $tag, input: { sourceCode: $sourceCode }) {
+          mutation publishScriptLibrary($scriptLibraryId: ID!, $tag: String!, $sourceCode: String, $sourceCodeEncoding: SourceCodeEncoding) {
+            publishScriptLibrary(
+              scriptLibraryId: $scriptLibraryId
+              tag: $tag
+              input: { sourceCode: $sourceCode, sourceCodeEncoding: $sourceCodeEncoding }
+            ) {
               id
             }
           }
         `, {
             scriptLibraryId: versionedScriptLibrary.id,
             tag: versionedScriptLibrary.tag,
-            sourceCode: versionedScriptLibrary.sourceCode,
+            sourceCode: encodeSourceCode(versionedScriptLibrary.sourceCode),
+            sourceCodeEncoding: SOURCE_CODE_ENCODING,
         })
             .catch((error) => {
             return Promise.reject(this.cleanError(error));
@@ -553,7 +575,8 @@ class FcodeGraphQLClient {
             parametersSchema: process.script.parametersSchema,
             readme: process.readme,
             tags: process.tags,
-            sourceCode: process.script.sourceCode,
+            sourceCode: encodeSourceCode(process.script.sourceCode),
+            sourceCodeEncoding: SOURCE_CODE_ENCODING,
             manifest: process.settings.dependencies.scopedToProcess ? process.manifest : null,
             settings,
         };
@@ -640,8 +663,8 @@ class FcodeGraphQLClient {
         if (scriptLibrary.id) {
             return this.client
                 .request((0, graphql_request_1.gql) `
-            mutation updateScriptLibrary($id: ID!, $sourceCode: String) {
-              updateScriptLibrary(id: $id, input: { sourceCode: $sourceCode }) {
+            mutation updateScriptLibrary($id: ID!, $sourceCode: String, $sourceCodeEncoding: SourceCodeEncoding) {
+              updateScriptLibrary(id: $id, input: { sourceCode: $sourceCode, sourceCodeEncoding: $sourceCodeEncoding }) {
                 id
                 name
                 programmingLanguage
@@ -650,7 +673,8 @@ class FcodeGraphQLClient {
             }
           `, {
                 id: scriptLibrary.id,
-                sourceCode: scriptLibrary.sourceCode,
+                sourceCode: encodeSourceCode(scriptLibrary.sourceCode),
+                sourceCodeEncoding: SOURCE_CODE_ENCODING,
             })
                 .then(({ updateScriptLibrary: scriptLibrary }) => new types_1.ScriptLibrary(scriptLibrary.id, scriptLibrary.name, scriptLibrary.sourceCode, scriptLibrary.programmingLanguage))
                 .catch((error) => {
@@ -659,8 +683,18 @@ class FcodeGraphQLClient {
         }
         return this.client
             .request((0, graphql_request_1.gql) `
-          mutation createScriptLibrary($name: String!, $sourceCode: String, $programmingLanguage: ProgrammingLanguage) {
-            createScriptLibrary(name: $name, programmingLanguage: $programmingLanguage, sourceCode: $sourceCode) {
+          mutation createScriptLibrary(
+            $name: String!
+            $sourceCode: String
+            $sourceCodeEncoding: SourceCodeEncoding
+            $programmingLanguage: ProgrammingLanguage
+          ) {
+            createScriptLibrary(
+              name: $name
+              programmingLanguage: $programmingLanguage
+              sourceCode: $sourceCode
+              sourceCodeEncoding: $sourceCodeEncoding
+            ) {
               id
               name
               sourceCode
@@ -669,7 +703,8 @@ class FcodeGraphQLClient {
           }
         `, {
             name: scriptLibrary.name,
-            sourceCode: scriptLibrary.sourceCode,
+            sourceCode: encodeSourceCode(scriptLibrary.sourceCode),
+            sourceCodeEncoding: SOURCE_CODE_ENCODING,
             programmingLanguage: scriptLibrary.programmingLanguage,
         })
             .then(({ createScriptLibrary: scriptLibrary }) => new types_1.ScriptLibrary(scriptLibrary.id, scriptLibrary.name, scriptLibrary.sourceCode, scriptLibrary.programmingLanguage))

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

@@ -16,7 +16,9 @@ export declare function flattenTranslations(document: unknown, prefix?: string,
  * publishes plain languages, so the request degrades one segment at a time — split on `-` or `_`,
  * without parsing a language tag, since any short slug is a legal identifier here — and every step
  * that matches stays in the chain: a variant file translates the keys that differ and leaves the
- * rest to the language it came from.
+ * rest to the language it came from. The opposite happens too — the host sends `es` while the
+ * workspace has `es-ES` — so a language layer that matches nothing, by name or ignoring case, is
+ * broadened to a regional file of that language, in the place the language would have taken.
  */
 export declare function localeFallbackChain(requested: string | undefined, primary: string | undefined, available: Array<string>): Array<string>;
 /**
@@ -25,10 +27,12 @@ export declare function localeFallbackChain(requested: string | undefined, prima
  * shorter form of the requested one the workspace publishes — layered underneath, plus each
  * locale's own map (inherited file layered under its own, but NOT merged over the primary) so a
  * call naming a locale (`fcode.i18n(key, args, { locale })`) resolves like the cloud's `by_locale`:
- * key by key in the requested locale first, falling back to the merged translations
+ * key by key in the requested locale first, falling back to the merged translations — and the
+ * primary locale, which a call naming a bare language prefers when it broadens to a regional file
  */
 export declare function resolveLocalTranslations(requestedLocale?: string, workspaceDir?: string): {
     locale?: string;
+    primaryLocale?: string;
     translations: Record<string, string>;
     byLocale: Record<string, Record<string, string>>;
 };

package/dist/services/locale-resolver.js

@@ -120,6 +120,20 @@ function matchingLocale(candidate, available) {
     }
     return available.filter((locale) => locale.toLowerCase() === candidate.toLowerCase()).sort()[0];
 }
+const LOCALE_SEPARATOR = /[-_]/;
+/**
+ * The available locale a bare language broadens to when the workspace only has regional files for
+ * it (`es` → `es-ES`): one whose first segment is the language, case ignored — the primary locale
+ * if it is one of them, the alphabetically first otherwise. A language with a separator in it (an
+ * identifier that starts with one) broadens to nothing. Mirrors the platform's `LocaleFallbackChain`.
+ */
+function sameLanguageLocale(language, primary, available) {
+    if (!language || LOCALE_SEPARATOR.test(language)) {
+        return undefined;
+    }
+    const sameLanguage = available.filter((locale) => locale.split(LOCALE_SEPARATOR)[0].toLowerCase() === language.toLowerCase()).sort();
+    return primary !== undefined && sameLanguage.includes(primary) ? primary : sameLanguage[0];
+}
 /**
  * The locale files that answer a requested identifier, lowest precedence first. Mirrors the
  * platform's `LocaleFallbackChain`, so a local run and the cloud resolve the same text.
@@ -128,7 +142,9 @@ function matchingLocale(candidate, available) {
  * publishes plain languages, so the request degrades one segment at a time — split on `-` or `_`,
  * without parsing a language tag, since any short slug is a legal identifier here — and every step
  * that matches stays in the chain: a variant file translates the keys that differ and leaves the
- * rest to the language it came from.
+ * rest to the language it came from. The opposite happens too — the host sends `es` while the
+ * workspace has `es-ES` — so a language layer that matches nothing, by name or ignoring case, is
+ * broadened to a regional file of that language, in the place the language would have taken.
  */
 function localeFallbackChain(requested, primary, available) {
     const chain = [];
@@ -146,8 +162,14 @@ function localeFallbackChain(requested, primary, available) {
         const lastSeparator = Math.max(candidate.lastIndexOf('-'), candidate.lastIndexOf('_'));
         candidate = lastSeparator > 0 ? candidate.slice(0, lastSeparator) : undefined;
     }
-    for (const shorterOrExact of candidates)
-        add(shorterOrExact);
+    candidates.forEach((shorterOrExact, index) => {
+        if (index === 0 && !matchingLocale(shorterOrExact, available)) {
+            add(sameLanguageLocale(shorterOrExact, primary, available));
+        }
+        else {
+            add(shorterOrExact);
+        }
+    });
     return chain;
 }
 /**
@@ -156,14 +178,15 @@ function localeFallbackChain(requested, primary, available) {
  * shorter form of the requested one the workspace publishes — layered underneath, plus each
  * locale's own map (inherited file layered under its own, but NOT merged over the primary) so a
  * call naming a locale (`fcode.i18n(key, args, { locale })`) resolves like the cloud's `by_locale`:
- * key by key in the requested locale first, falling back to the merged translations
+ * key by key in the requested locale first, falling back to the merged translations — and the
+ * primary locale, which a call naming a bare language prefers when it broadens to a regional file
  */
 function resolveLocalTranslations(requestedLocale, workspaceDir = process.cwd()) {
     const primary = primaryLocaleOf(workspaceDir);
     const locale = requestedLocale || primary;
     const byLocale = Object.fromEntries(availableLocales(workspaceDir).map((slug) => [slug, readLocale(workspaceDir, slug)]));
     if (!locale) {
-        return { locale: undefined, translations: {}, byLocale };
+        return { locale: undefined, primaryLocale: primary, translations: {}, byLocale };
     }
     // `byLocale` already holds every locale's own file, so the merged map — the fallback chain
     // layered lowest precedence first — is derived from it rather than read from disk a second time.
@@ -171,5 +194,5 @@ function resolveLocalTranslations(requestedLocale, workspaceDir = process.cwd())
     for (const layer of localeFallbackChain(requestedLocale, primary, Object.keys(byLocale))) {
         Object.assign(translations, byLocale[layer]);
     }
-    return { locale, translations, byLocale };
+    return { locale, primaryLocale: primary, translations, byLocale };
 }

package/dist/utils/file-parameter-warnings.d.ts

@@ -0,0 +1,8 @@
+export interface DeprecatedFileField {
+    /** Dotted path of the property inside the schema's `properties`, e.g. `dumpFile` or `upload.file`. */
+    path: string;
+    /** Extensions taken from `ui:options.accept`, the value `x-fcode-file.accept` should carry. */
+    accept: Array<string>;
+}
+export declare function deprecatedFileFields(schema: any): Array<DeprecatedFileField>;
+export declare function warnDeprecatedFileFields(processSlug: string, fields: Array<DeprecatedFileField>): void;

package/dist/utils/file-parameter-warnings.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deprecatedFileFields = deprecatedFileFields;
+exports.warnDeprecatedFileFields = warnDeprecatedFileFields;
+const color_1 = require("@oclif/color");
+const cli_1 = require("./cli");
+// A file parameter is declared with `x-fcode-file`. `"ui:widget": "file"` is an rjsf presentation
+// key, so a property that only has the widget is still recognised as a file for now, but that
+// fallback is deprecated and will go.
+function deprecatedFileFields(schema) {
+    const fields = [];
+    collect(schema, [], fields);
+    return fields;
+}
+function collect(node, parents, fields) {
+    const properties = node?.properties;
+    if (!isObject(properties)) {
+        return;
+    }
+    for (const [key, property] of Object.entries(properties)) {
+        if (!isObject(property)) {
+            continue;
+        }
+        const path = [...parents, key];
+        if (property.ui?.['ui:widget'] === 'file' && property['x-fcode-file'] == undefined) {
+            fields.push({ path: path.join('.'), accept: acceptList(property.ui['ui:options']?.accept) });
+        }
+        collect(property, path, fields);
+        collect(property.items, path, fields);
+    }
+}
+function acceptList(accept) {
+    const values = Array.isArray(accept) ? accept : typeof accept === 'string' ? accept.split(',') : [];
+    return values.map((value) => String(value).trim()).filter((value) => value !== '');
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// Naming extensions is the habit worth teaching: accept is what tells a Factorial One agent what the
+// parameter takes. An empty list is still offered, so a field that really takes any file can say so.
+function warnDeprecatedFileFields(processSlug, fields) {
+    for (const field of fields) {
+        const fix = field.accept.length > 0
+            ? `Add "x-fcode-file": { "accept": ${extensionList(field.accept)} } to it in parametersSchema.json ` +
+                `(or { "accept": [] } if it really takes any file).`
+            : `Add "x-fcode-file" to it in parametersSchema.json, listing the extensions it takes, ` +
+                `e.g. { "accept": [".csv", ".xlsx"] }: they tell Factorial One what the parameter takes. ` +
+                `If it really takes any file, declare that with { "accept": [] }.`;
+        cli_1.default.log(color_1.default.yellow(`⚠️  '${processSlug}': parameter '${field.path}' is a file only through "ui:widget": "file", which is deprecated ` +
+            `for declaring a file and will stop working. ${fix}`));
+    }
+}
+function extensionList(extensions) {
+    return `[${extensions.map((extension) => JSON.stringify(extension)).join(', ')}]`;
+}

package/oclif.manifest.json

@@ -2516,5 +2516,5 @@
       ]
     }
   },
-  "version": "3.4.0"
+  "version": "3.5.1"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@factorialco/fcode-cli",
-  "version": "3.4.0",
+  "version": "3.5.1",
   "packageManager": "pnpm@11.7.0",
   "description": "Factorial Code Command Line Interface",
   "homepage": "https://code.factorialhr.com/docs/cli/",