@factorialco/fcode-cli 2.1.0 → 2.3.0

package/dist/core/commands/base-command.js

@@ -4,16 +4,42 @@ const core_1 = require("@oclif/core");
 const global_1 = require("../../config/global");
 const workspace_1 = require("../../config/workspace");
 const color_1 = require("@oclif/color");
+const auth_service_1 = require("../../services/auth-service");
 const errors_1 = require("../errors");
 const cli_1 = require("../../utils/cli");
 const url_utils_1 = require("../../utils/url-utils");
 class BaseCommand extends core_1.Command {
+    constructor() {
+        super(...arguments);
+        this.sessionRefreshRetried = false;
+    }
     async catch(error) {
         // do any extra work with error
         if (error && error.response && error.response.status === 401) {
+            process.exitCode = 1;
             cli_1.default.error(`User authentication is invalid for current team.`);
             return;
         }
+        if (error && error.response && error.response.status === 403) {
+            let origin;
+            try {
+                origin = await this.workspaceConfig.getTeamOrigin();
+            }
+            catch {
+                // No workspace context; report without the slug.
+            }
+            // A 403 with a valid session usually means the token's team groups went
+            // stale — they are snapshotted at issuance (FCT-61231). Re-mint the token
+            // and retry the command once; a second denial falls through to the error.
+            if (!this.sessionRefreshRetried && origin && (await auth_service_1.default.refreshSession(origin.url))) {
+                this.sessionRefreshRetried = true;
+                await this.onSessionRefreshed();
+                return this.run().catch((retryError) => this.catch(retryError));
+            }
+            process.exitCode = 1;
+            cli_1.default.error((0, errors_1.teamAccessDeniedMessage)(origin?.slug));
+            return;
+        }
         if (error instanceof errors_1.NotAuthenticated) {
             let errorMessage = 'No session active. Logging you in';
             const loginArgs = [];
@@ -40,9 +66,11 @@ class BaseCommand extends core_1.Command {
             return this.run();
         }
         if (error instanceof errors_1.CLIError) {
+            process.exitCode = 1;
             cli_1.default.error(error);
             return;
         }
+        process.exitCode = 1;
         cli_1.default.error(error.message);
     }
     async init(url) {
@@ -53,6 +81,9 @@ class BaseCommand extends core_1.Command {
         const { authUrl } = await this.globalConfig.getAuthInfo(workspaceUrl);
         await this.config.runHook('auth', { argv: [workspaceUrl, authUrl], id: 'init' });
     }
+    // Called after a 403-triggered session refresh, before the retry: rewire
+    // anything that captured the old access token. API commands override this.
+    async onSessionRefreshed() { }
     async logActiveTeam() {
         const { slug, url } = await this.workspaceConfig.getTeamOrigin();
         cli_1.default.log(color_1.default.magenta(`💻 Working on Factorial Code team '${slug}${url !== global_1.FCODE_CLOUD_URL ? ` (${url})` : ''}'.`));

package/dist/core/commands/i18n-command.d.ts

@@ -0,0 +1,5 @@
+import { Locale } from '../types';
+import ResourceCommand from './resource-command';
+export default abstract class I18nCommand extends ResourceCommand<Locale> {
+    init(): Promise<void>;
+}

package/dist/core/commands/i18n-command.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const locale_1 = require("../../repositories/locale");
+const resource_merger_1 = require("../resource-merger");
+const resource_pusher_1 = require("../resource-pusher");
+const resource_command_1 = require("./resource-command");
+class I18nCommand extends resource_command_1.default {
+    async init() {
+        await super.init();
+        this._resourceRepository = new locale_1.default();
+        this._resourceMerger = new resource_merger_1.default(this._resourceRepository);
+        this._resourcePusher = new resource_pusher_1.default(this._resourceRepository, this._fcodeGraphQLClient);
+        this._resourceQuery = () => this._fcodeGraphQLClient.allLocales.bind(this._fcodeGraphQLClient)();
+    }
+}
+exports.default = I18nCommand;

package/dist/core/errors.d.ts

@@ -30,6 +30,12 @@ export declare class LocalVariableNotFound extends ResourceNotFound {
 export declare class CloudVariableNotFound extends ResourceNotFound {
     constructor(error: Error | string, variableId: string);
 }
+export declare class LocalLocaleNotFound extends ResourceNotFound {
+    constructor(error: Error | string, locale: string);
+}
+export declare class CloudLocaleNotFound extends ResourceNotFound {
+    constructor(error: Error | string, locale: string);
+}
 export declare class LocalProgrammingLanguageManifestNotFound extends ResourceNotFound {
     constructor(error: Error | string, programmingLanguageManifestId: string);
 }
@@ -41,6 +47,10 @@ export declare class NotAuthenticated extends CLIError {
     constructor(url: string);
     getUrl(): string;
 }
+export declare function teamAccessDeniedMessage(slug?: string): string;
+export declare class TeamAccessDenied extends CLIError {
+    constructor(slug?: string);
+}
 export declare class NotFcodeWorkspace extends CLIError {
     constructor();
 }

package/dist/core/errors.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ErrorExecutingProcess = exports.ProcessDependenciesNotInstalled = exports.DependenciesNotInstalled = exports.NotFcodeWorkspace = exports.NotAuthenticated = exports.CloudProgrammingLanguageManifestNotFound = exports.LocalProgrammingLanguageManifestNotFound = exports.CloudVariableNotFound = exports.LocalVariableNotFound = exports.CloudScriptLibraryNotFound = exports.LocalScriptLibraryNotFound = exports.CloudProcessNotFound = exports.LocalProcessNotFound = exports.ResourceNotFound = exports.CLIError = void 0;
+exports.ErrorExecutingProcess = exports.ProcessDependenciesNotInstalled = exports.DependenciesNotInstalled = exports.NotFcodeWorkspace = exports.TeamAccessDenied = exports.NotAuthenticated = exports.CloudProgrammingLanguageManifestNotFound = exports.LocalProgrammingLanguageManifestNotFound = exports.CloudLocaleNotFound = exports.LocalLocaleNotFound = exports.CloudVariableNotFound = exports.LocalVariableNotFound = exports.CloudScriptLibraryNotFound = exports.LocalScriptLibraryNotFound = exports.CloudProcessNotFound = exports.LocalProcessNotFound = exports.ResourceNotFound = exports.CLIError = void 0;
+exports.teamAccessDeniedMessage = teamAccessDeniedMessage;
 const global_1 = require("../config/global");
 class CLIError extends Error {
     constructor(message, options) {
@@ -74,6 +75,24 @@ class CloudVariableNotFound extends ResourceNotFound {
     }
 }
 exports.CloudVariableNotFound = CloudVariableNotFound;
+class LocalLocaleNotFound extends ResourceNotFound {
+    constructor(error, locale) {
+        super(error, 'Locale', locale, {
+            code: 'ERR_LOCAL_LOCALE_NOT_FOUND',
+            suggestions: [],
+        });
+    }
+}
+exports.LocalLocaleNotFound = LocalLocaleNotFound;
+class CloudLocaleNotFound extends ResourceNotFound {
+    constructor(error, locale) {
+        super(error, 'Locale', locale, {
+            code: 'ERR_CLOUD_LOCALE_NOT_FOUND',
+            suggestions: [],
+        });
+    }
+}
+exports.CloudLocaleNotFound = CloudLocaleNotFound;
 class LocalProgrammingLanguageManifestNotFound extends ResourceNotFound {
     constructor(error, programmingLanguageManifestId) {
         super(error, 'ProgrammingLanguageManifest', programmingLanguageManifestId, {
@@ -102,6 +121,20 @@ class NotAuthenticated extends CLIError {
     }
 }
 exports.NotAuthenticated = NotAuthenticated;
+function teamAccessDeniedMessage(slug) {
+    const team = slug ? ` '${slug}'` : '';
+    return (`You don't have access to team${team} with your current session.` +
+        ` If you were granted access recently, run 'fcode logout' and 'fcode login' and retry.`);
+}
+class TeamAccessDenied extends CLIError {
+    constructor(slug) {
+        super(teamAccessDeniedMessage(slug), {
+            code: 'ERR_TEAM_ACCESS_DENIED',
+            exit: 1,
+        });
+    }
+}
+exports.TeamAccessDenied = TeamAccessDenied;
 class NotFcodeWorkspace extends CLIError {
     constructor() {
         super('⚠️  Current directory is not a Factorial Code workspace.', {

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

@@ -4,6 +4,7 @@ const node_child_process_1 = require("node:child_process");
 const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
+const locale_resolver_1 = require("../../services/locale-resolver");
 const errors_1 = require("../errors");
 const cli_1 = require("../../utils/cli");
 const dependencies_1 = require("../utils/dependencies");
@@ -114,6 +115,9 @@ class ExecutionTask {
             },
             variables: this.getVariablesObject(),
             request: this._options.request ?? 'No request, you are using the CLI',
+            // Layered here rather than in the generated runtime: the cloud ships one already-merged
+            // flat map, and a local run has to resolve fcode.i18n against the same shape.
+            i18n: (0, locale_resolver_1.resolveLocalTranslations)(this._options.locale),
         };
     }
     async prepare() {

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

@@ -111,7 +111,12 @@ const main = typeof _hooksModule['${fn}'] === 'function'
       };`}
 
       global.fcode = {
-        import: (moduleName, version) => {
+        // A version is either a bare string or an options object ({ version: 'v1' }), the
+        // form every other versioned helper takes — the cloud reads both, so a local run must too.
+        import: (moduleName, tagOrOptions) => {
+          const version = typeof tagOrOptions === 'string'
+            ? tagOrOptions
+            : (tagOrOptions && typeof tagOrOptions === 'object' ? tagOrOptions.version : undefined);
           let modulePath = require('path').join('${process.cwd()}', 'modules', moduleName);
           if(version) {
             modulePath = require('path').join(modulePath, 'versions', version)
@@ -588,6 +593,26 @@ const main = typeof _hooksModule['${fn}'] === 'function'
             }
           };
         })(),
+        // The third argument is the version options the cloud honours. A workspace directory holds
+        // no published snapshots, so a pinned call resolves against the files on disk — the same
+        // per-file fallback the cloud applies to a locale that was never published at that tag.
+        // Own properties only and no array arguments, exactly like the cloud executors.
+        i18n: Object.assign((key, args, _options) => {
+          const translations = ${JSON.stringify(metadata.i18n.translations, null, 2)};
+          const template = Object.hasOwn(translations, key) ? translations[key] : undefined;
+          if (template === undefined) {
+            return key;
+          }
+          if (!args || typeof args !== 'object' || Array.isArray(args)) {
+            return template;
+          }
+          // Single pass, so a substituted value containing %{...} is never rescanned.
+          return template.replace(/%\{([^}]*)\}/g, (match, name) => {
+            const trimmed = name.trim();
+            const value = Object.hasOwn(args, trimmed) ? args[trimmed] : undefined;
+            return value === undefined || value === null ? match : String(value);
+          });
+        }, { locale: ${JSON.stringify(metadata.i18n.locale ?? null)} }),
         sendMail: async ({ to, subject, text, html } = {}) => {
           // No manager locally: log the email contents instead of sending, so
           // devs can see exactly what would be delivered when run in the cloud.

package/dist/core/resource-pusher.js

@@ -82,6 +82,16 @@ class ResourcePusher {
                 const createdVariable = await this._fcodeGraphQLClient.pushVariable(variable);
                 return this._repository.save(createdVariable);
             }
+            if (this._repository._repositoryName === 'i18n') {
+                const locale = resource;
+                // The recorded id is only a hint: pushing an identifier a parent workspace owns has to
+                // create an override here, so the update path is taken only for a locale this workspace
+                // already owns.
+                const pushed = locale.id && !locale.resolvingTeamSlug
+                    ? await this._fcodeGraphQLClient.updateLocale(locale)
+                    : await this._fcodeGraphQLClient.pushLocale(locale);
+                return this._repository.save(pushed);
+            }
             if (this._repository._repositoryName === 'dependencies') {
                 const updatedProgrammingLanguageManifests = await this._fcodeGraphQLClient.pushProgrammingLanguageManifest(resource);
                 return this._repository.save(updatedProgrammingLanguageManifests);
@@ -114,6 +124,11 @@ class ResourcePusher {
             if (this._repository._repositoryName === 'variables') {
                 await this._fcodeGraphQLClient.removeVariable(resource.id);
             }
+            if (this._repository._repositoryName === 'i18n') {
+                // By identifier, not slug: an inherited locale is tracked under a qualified slug, and only
+                // this workspace's own locales — where the two coincide — ever reach a remote delete.
+                await this._fcodeGraphQLClient.removeLocale(resource.locale);
+            }
             this._repository.removeMetadata(resource.slug);
         }
         catch (error) {

package/dist/core/types.d.ts

@@ -41,6 +41,9 @@ export interface TeamMetadata {
     variables: {
         [key: string]: Variable;
     };
+    i18n: {
+        [key: string]: Locale;
+    };
     dependencies: {
         [key: string]: ProgrammingLanguageManifest;
     };
@@ -187,6 +190,27 @@ export declare class ScriptLibrary extends Resource {
     constructor(id: string, name: string, sourceCode: string, programmingLanguage: ProgrammingLanguage, resolvingTeamSlug?: string);
     get contentHash(): string;
 }
+export declare class Locale extends Resource {
+    static LOCALE_REGEX: RegExp;
+    static INHERITED_SUFFIX: string;
+    id: string | undefined;
+    slug: string;
+    locale: string;
+    content: string;
+    constructor(id: string | undefined, locale: string, content: string, resolvingTeamSlug?: string);
+    /**
+     * The name a locale is tracked and stored under. Unlike every other resource, the identifier is
+     * not unique: a workspace sees its own `en` and each parent workspace's `en`, and all of them are
+     * live, because an override is layered over the parent's file key by key rather than replacing
+     * it. Naming files after the identifier alone would keep only one of them.
+     *
+     * A workspace directory therefore holds two files at most per identifier: `en.yaml` for its own
+     * and `en.inherited.yaml` for everything it inherits, which `mergeInheritedLocales` collapses
+     * into one file. An identifier cannot contain a dot, so the name parses back.
+     */
+    static slugFor(locale: string, resolvingTeamSlug?: string): string;
+    get contentHash(): string;
+}
 export declare class VersionedScriptLibrary extends Resource {
     id: string;
     slug: string;
@@ -262,9 +286,10 @@ export declare class Team extends Resource {
     errorHandlerConfig?: ErrorHandlerConfig;
     parentTeamSlugs: string[];
     webhookAuth?: WebhookAuth;
+    primaryLocale?: string;
     versions?: TeamVersionFileEntry[];
     aliases?: TeamAliasFileEntry[];
-    constructor(slug: string, parentTeamSlugs: string[], zoneId?: string, errorHandlerConfig?: ErrorHandlerConfig, webhookAuth?: WebhookAuth);
+    constructor(slug: string, parentTeamSlugs: string[], zoneId?: string, errorHandlerConfig?: ErrorHandlerConfig, webhookAuth?: WebhookAuth, primaryLocale?: string);
     get contentHash(): string;
 }
 export interface RawErrorHandlerConfig {
@@ -277,6 +302,7 @@ export interface RawTeamSettings {
     errorHandlerConfig?: RawErrorHandlerConfig | null;
     parentTeamSlugs: string[];
     webhookAuth?: WebhookAuth | null;
+    primaryLocale?: string | null;
 }
 export interface TeamUpdateInput {
     zoneId?: string;
@@ -286,6 +312,7 @@ export interface TeamUpdateInput {
         headerName?: string | null;
         variableKey?: string | null;
     } | null;
+    primaryLocale?: string;
 }
 export type ResourceMetadata = {
     [key: string]: any;
@@ -317,6 +344,7 @@ export type ExecutionOptions = {
     hookFilePath?: string;
     hookFunction?: string;
     silent?: boolean;
+    locale?: string;
 };
 export declare const ForceFlag: {
     force: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;

package/dist/core/types.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ServiceAccount = exports.Dependency = exports.DependenciesFlags = exports.TeamNameArg = exports.ResourceSlugArg = exports.ForceFlag = exports.ScriptLibraryNotFound = exports.ProcessNotFound = exports.Team = exports.ProgrammingLanguageManifest = exports.Variable = exports.VersionedScriptLibrary = exports.ScriptLibrary = exports.VersionedProcess = exports.Process = exports.DEFAULT_WEBHOOK_AUTH_HEADER = exports.programmingLanguageDisplayName = exports.ResourceStatus = exports.OnConflictResolution = exports.Resource = void 0;
+exports.ServiceAccount = exports.Dependency = exports.DependenciesFlags = exports.TeamNameArg = exports.ResourceSlugArg = exports.ForceFlag = exports.ScriptLibraryNotFound = exports.ProcessNotFound = exports.Team = exports.ProgrammingLanguageManifest = exports.Variable = exports.VersionedScriptLibrary = exports.Locale = exports.ScriptLibrary = exports.VersionedProcess = exports.Process = exports.DEFAULT_WEBHOOK_AUTH_HEADER = exports.programmingLanguageDisplayName = exports.ResourceStatus = exports.OnConflictResolution = exports.Resource = void 0;
 const core_1 = require("@oclif/core");
 const crypto = require("node:crypto");
 const canonical_hash_1 = require("../utils/canonical-hash");
@@ -103,6 +103,41 @@ class ScriptLibrary extends Resource {
     }
 }
 exports.ScriptLibrary = ScriptLibrary;
+class Locale extends Resource {
+    constructor(id, locale, content, resolvingTeamSlug) {
+        super();
+        this.id = id;
+        this.slug = Locale.slugFor(locale, resolvingTeamSlug);
+        this.locale = locale;
+        this.content = content;
+        this.resolvingTeamSlug = resolvingTeamSlug;
+    }
+    /**
+     * The name a locale is tracked and stored under. Unlike every other resource, the identifier is
+     * not unique: a workspace sees its own `en` and each parent workspace's `en`, and all of them are
+     * live, because an override is layered over the parent's file key by key rather than replacing
+     * it. Naming files after the identifier alone would keep only one of them.
+     *
+     * A workspace directory therefore holds two files at most per identifier: `en.yaml` for its own
+     * and `en.inherited.yaml` for everything it inherits, which `mergeInheritedLocales` collapses
+     * into one file. An identifier cannot contain a dot, so the name parses back.
+     */
+    static slugFor(locale, resolvingTeamSlug) {
+        return resolvingTeamSlug ? `${locale}${Locale.INHERITED_SUFFIX}` : locale;
+    }
+    // Hashed over the raw YAML: the file is the source of truth and round-trips comments and
+    // ordering, so any edit — even one that parses to the same translations — is a change to push.
+    get contentHash() {
+        return crypto.createHash('md5').update(this.content).digest('hex');
+    }
+}
+exports.Locale = Locale;
+// Free-form identifier rather than a validated BCP-47 tag, so a workspace can use whatever it
+// already names its translations after. Case is significant: pt-BR and pt-br are different
+// locales, and the platform's unique index is case-sensitive too.
+Locale.LOCALE_REGEX = /^[A-Za-z0-9][\w-]{0,19}$/;
+// Marks a file as owned by a parent workspace, the way `variables.inherited.env` does.
+Locale.INHERITED_SUFFIX = '.inherited';
 class VersionedScriptLibrary extends Resource {
     constructor(id, tag, sourceCode, programmingLanguage) {
         super();
@@ -166,19 +201,22 @@ class ProgrammingLanguageManifest extends Resource {
 }
 exports.ProgrammingLanguageManifest = ProgrammingLanguageManifest;
 class Team extends Resource {
-    constructor(slug, parentTeamSlugs, zoneId, errorHandlerConfig, webhookAuth) {
+    constructor(slug, parentTeamSlugs, zoneId, errorHandlerConfig, webhookAuth, primaryLocale) {
         super();
         this.slug = slug;
         this.parentTeamSlugs = parentTeamSlugs;
         this.zoneId = zoneId;
         this.errorHandlerConfig = errorHandlerConfig;
         this.webhookAuth = webhookAuth;
+        this.primaryLocale = primaryLocale;
     }
     get contentHash() {
         const payload = {
             zoneId: this.zoneId || null,
             errorHandlerConfig: this.errorHandlerConfig || null,
-            parentTeamSlugs: [...(this.parentTeamSlugs || [])].sort(),
+            // Kept in the given order, not sorted: the order is the inheritance precedence, so a pure
+            // reorder is a real change that must be detected and pushed.
+            parentTeamSlugs: [...(this.parentTeamSlugs || [])],
         };
         // Inserted only when set, so every team.json that predates webhook auth keeps the
         // hash already stored in .fcode and does not report a phantom conflict. A key present
@@ -186,6 +224,11 @@ class Team extends Resource {
         if (this.webhookAuth) {
             payload.webhookAuth = this.webhookAuth;
         }
+        // Same insert-only-when-set rule, for the same reason: a team.json written before locales
+        // existed must keep the hash already stored in .fcode.
+        if (this.primaryLocale) {
+            payload.primaryLocale = this.primaryLocale;
+        }
         return (0, canonical_hash_1.canonicalJsonHash)(payload);
     }
 }

package/dist/repositories/locale.d.ts

@@ -0,0 +1,24 @@
+import { Locale, ResourceMetadata } from '../core/types';
+import ResourceRepositoryBase from './resource';
+/**
+ * Locales live as one YAML file per locale directly under `i18n/`, named after the slug
+ * (`i18n/pt-BR.yaml`, `i18n/pt-BR.inherited.yaml`). A file, not a directory: a locale has exactly
+ * one artifact, and naming the file after the identifier is what lets `push` work without knowing
+ * any ids.
+ *
+ * A workspace keeps what it inherits next to what it owns, because overriding a locale only layers
+ * keys over the inherited file rather than replacing it — see {@link Locale.slugFor}.
+ */
+declare class LocaleRepository extends ResourceRepositoryBase<Locale> {
+    constructor();
+    find(slug: string): Promise<Locale>;
+    findSlugsNotAdded(): Promise<Array<string>>;
+    protected getResourcePath(locale: Locale): string;
+    protected removeFiles(locale: Locale): Promise<void>;
+    protected resourceToMetadata(locale: Locale): ResourceMetadata;
+    protected saveFiles(locale: Locale): Promise<void>;
+    metadataFromFiles(slug: string): Promise<ResourceMetadata>;
+    validSlug(slug: string): boolean;
+    slugFormatMessage(): string;
+}
+export default LocaleRepository;

package/dist/repositories/locale.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = require("fs-extra");
+const path = require("node:path");
+const color_1 = require("@oclif/color");
+const cli_1 = require("../utils/cli");
+const errors_1 = require("../core/errors");
+const types_1 = require("../core/types");
+const file_utils_1 = require("../utils/file-utils");
+const resource_1 = require("./resource");
+const YAML_EXTENSION = '.yaml';
+/**
+ * Locales live as one YAML file per locale directly under `i18n/`, named after the slug
+ * (`i18n/pt-BR.yaml`, `i18n/pt-BR.inherited.yaml`). A file, not a directory: a locale has exactly
+ * one artifact, and naming the file after the identifier is what lets `push` work without knowing
+ * any ids.
+ *
+ * A workspace keeps what it inherits next to what it owns, because overriding a locale only layers
+ * keys over the inherited file rather than replacing it — see {@link Locale.slugFor}.
+ */
+class LocaleRepository extends resource_1.default {
+    constructor() {
+        super({
+            name: 'i18n',
+        });
+    }
+    async find(slug) {
+        const { [this._repositoryName]: locales } = await this.workspaceConfig.getActiveTeam();
+        const localeMetadata = locales?.[slug];
+        if (!localeMetadata) {
+            throw new errors_1.LocalLocaleNotFound(new Error('Locale not found on team metadata'), slug);
+        }
+        try {
+            const content = fs.readFileSync(this.getResourcePath(localeMetadata)).toString();
+            return new types_1.Locale(localeMetadata.id, localeMetadata.locale ?? slug, content, localeMetadata.resolvingTeamSlug);
+        }
+        catch (error) {
+            throw new errors_1.LocalLocaleNotFound(error, slug);
+        }
+    }
+    async findSlugsNotAdded() {
+        const slugsNotAdded = [];
+        if (!fs.pathExistsSync(this._repositoryName)) {
+            return slugsNotAdded;
+        }
+        for (const fileName of fs.readdirSync(this._repositoryName)) {
+            if (!fileName.endsWith(YAML_EXTENSION)) {
+                continue;
+            }
+            const slug = path.basename(fileName, YAML_EXTENSION);
+            if (await this.workspaceConfig.exists('i18n', slug)) {
+                continue;
+            }
+            // Only `pull` writes an inherited file, and it registers it as it does. One left behind by a
+            // workspace that no longer inherits it is stale, not a locale waiting to be tracked.
+            if (slug.endsWith(types_1.Locale.INHERITED_SUFFIX)) {
+                continue;
+            }
+            if (this.validSlug(slug)) {
+                slugsNotAdded.push(slug);
+            }
+            else {
+                cli_1.default.log(color_1.default.yellow(`\n⚠️  local locale file '${fileName}' doesn't have a valid name and will be ignored. ${this.slugFormatMessage()}`));
+            }
+        }
+        return slugsNotAdded;
+    }
+    getResourcePath(locale) {
+        return path.join(this._repositoryName, `${locale.slug ?? locale.locale}${YAML_EXTENSION}`);
+    }
+    async removeFiles(locale) {
+        fs.removeSync(this.getResourcePath(locale));
+        this.removeDirectoryIfEmpty(this._repositoryName);
+    }
+    resourceToMetadata(locale) {
+        return {
+            id: locale.id,
+            locale: locale.locale,
+            slug: locale.slug,
+            ...(locale.resolvingTeamSlug && { resolvingTeamSlug: locale.resolvingTeamSlug }),
+        };
+    }
+    async saveFiles(locale) {
+        // Inherited locales are written read-only, like inherited modules: they belong to a parent
+        // workspace, and editing one here would push an override rather than change the parent.
+        (0, file_utils_1.outputFileSyncIfChanged)(this.getResourcePath(locale), locale.content || '', { readOnly: Boolean(locale.resolvingTeamSlug) });
+    }
+    async metadataFromFiles(slug) {
+        return {
+            locale: slug,
+            slug: slug,
+            contentHash: '',
+        };
+    }
+    validSlug(slug) {
+        return types_1.Locale.LOCALE_REGEX.test(slug);
+    }
+    slugFormatMessage() {
+        return "Use up to 20 letters, numbers, '-' or '_', starting with a letter or a number.";
+    }
+}
+exports.default = LocaleRepository;

package/dist/repositories/resource.js

@@ -19,7 +19,10 @@ class ResourceRepositoryBase {
         }
     }
     async findAll() {
-        const { [this._repositoryName]: resources } = await this.workspaceConfig.getActiveTeam();
+        // Defaulted because a collection added after a workspace was cloned (as `i18n` was) is absent
+        // from its sync metadata until the first pull writes it — findAll must see "no resources",
+        // not crash every aggregate pull/push/status in every pre-existing workspace.
+        const { [this._repositoryName]: resources = {} } = await this.workspaceConfig.getActiveTeam();
         // eslint-disable-next-line unicorn/no-array-reduce
         const existResources = await Object.keys(resources).reduce((promise, slug) => promise.then(async (existIds) => {
             const exists = await this.exists(slug);

package/dist/repositories/team.js

@@ -29,7 +29,7 @@ class TeamRepository {
         }
         catch { }
         const parentTeamSlugs = Array.isArray(raw.parentTeamSlugs) ? raw.parentTeamSlugs : [];
-        const team = new types_1.Team(slug, parentTeamSlugs, raw.zoneId, this.parseErrorHandler(raw.errorHandlerConfig), this.parseWebhookAuth(raw.webhookAuth));
+        const team = new types_1.Team(slug, parentTeamSlugs, raw.zoneId, this.parseErrorHandler(raw.errorHandlerConfig), this.parseWebhookAuth(raw.webhookAuth), typeof raw.primaryLocale === 'string' && raw.primaryLocale.length > 0 ? raw.primaryLocale : undefined);
         // Parsed so a find()+save() round-trip does not drop the pull-only fields.
         if (Array.isArray(raw.versions)) {
             team.versions = raw.versions;
@@ -51,7 +51,7 @@ class TeamRepository {
                 tag: raw.errorHandlerConfig.tag ?? null,
             };
         }
-        return new types_1.Team(raw.slug, raw.parentTeamSlugs ?? [], raw.zoneId, errorHandlerConfig, this.parseWebhookAuth(raw.webhookAuth));
+        return new types_1.Team(raw.slug, raw.parentTeamSlugs ?? [], raw.zoneId, errorHandlerConfig, this.parseWebhookAuth(raw.webhookAuth), raw.primaryLocale ?? undefined);
     }
     /**
      * Writes the cloud's team versions and aliases into the Team as the pull-only team.json
@@ -111,6 +111,9 @@ class TeamRepository {
         if (team.webhookAuth !== undefined) {
             file.webhookAuth = team.webhookAuth;
         }
+        if (team.primaryLocale !== undefined) {
+            file.primaryLocale = team.primaryLocale;
+        }
         // Pull-only global versioning fields, appended after the pushable settings.
         if (team.versions !== undefined) {
             file.versions = team.versions;

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

@@ -64,6 +64,7 @@ fcode = FcodeGlobal(
     Storage(),
     Schedule(),
     Variables(env_variables),
+    metadata.get("i18n", {}),
 )
 
 logging.basicConfig(level=os.environ.get("FCODE_LOG_LEVEL", logging.INFO))

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

@@ -78,8 +78,42 @@ class Processes(dict):
             print(error, file=sys.stderr)
 
 
+class I18n:
+    """Local equivalent of the cloud's fcode.i18n.
+
+    The CLI has already layered the chosen locale over the workspace's primary one, so what
+    arrives here is a single flat map. Nothing raises: a key with no translation resolves to the
+    key itself, and a placeholder with no argument is left exactly as written.
+
+    The ``options`` argument (the version a call pins in the cloud) is accepted and ignored: a
+    workspace directory holds no published snapshots, so a pinned call resolves against the files
+    on disk -- the same per-file fallback the cloud applies to a locale never published at that tag.
+    """
+
+    def __init__(self, i18n_payload):
+        payload = i18n_payload or {}
+        self.__translations = payload.get("translations") or {}
+        self.locale = payload.get("locale")
+
+    def __call__(self, key, args=None, options=None):
+        template = self.__translations.get(key)
+        if template is None:
+            return key
+        if not isinstance(args, dict):
+            return template
+
+        import re
+
+        def replace(match):
+            value = args.get(match.group(1).strip())
+            return match.group(0) if value is None else str(value)
+
+        # Single pass, so a substituted value containing %{...} is never rescanned.
+        return re.sub(r"%\{([^}]*)\}", replace, template)
+
+
 class FcodeGlobal:
-    def __init__(self, context, execution, env, datastore, storage, schedule, variables):
+    def __init__(self, context, execution, env, datastore, storage, schedule, variables, i18n=None):
         self.context = context
         self.execution = execution
         self.team = AttrsInfo({"timezone": "UTC"})
@@ -89,6 +123,7 @@ class FcodeGlobal:
         self.schedule = schedule
         self.variables = variables
         self.processes = Processes()
+        self.i18n = I18n(i18n)
 
     def send_mail(self, to=None, subject=None, text=None, html=None):
         # No manager locally: log the email contents instead of sending, so devs
@@ -110,6 +145,13 @@ class FcodeGlobal:
         return {"messageId": "local-run", "accepted": accepted, "rejected": []}
 
     def import_module(self, module_name, version=None):
+        """Import a workspace module, optionally at a version.
+
+        The version is either a bare string or an options dict ({"version": "v1"}), the form
+        every other versioned helper takes — the cloud reads both, so a local run must too.
+        """
+        if isinstance(version, dict):
+            version = version.get("version")
         module_path = module_name
         if version:
             module_path = os.path.join(module_path, "versions", version)