@factorialco/fcode-cli 2.3.0 → 3.0.0

package/dist/core/utils/dependencies.js

@@ -12,7 +12,10 @@ async function getDependenciesPath(programmingLanguage) {
     const basePath = (0, workspace_1.baseDependenciesPath)(programmingLanguage);
     const repo = new programming_language_manifest_1.default();
     const programmingLanguageManifest = await repo.find(programmingLanguage);
-    const dependenciesDirectory = (0, env_dependencies_command_1.dependenciesHash)(programmingLanguageManifest.dependencies);
+    // The effective set, not the workspace's own: the cloud installs the inherited dependencies too,
+    // and the directory is named after the hash of what is installed. Hashing only the own list here
+    // would make a local run resolve a different directory than the platform.
+    const dependenciesDirectory = (0, env_dependencies_command_1.dependenciesHash)(programmingLanguageManifest.effectiveDependencies);
     return path.join(basePath, dependenciesDirectory);
 }
 function getProcessDependenciesPath(process) {

package/dist/env.js

@@ -14,7 +14,7 @@ const zod_1 = require("zod");
  */
 exports.envSchema = zod_1.z.object({
     // --- Cloud / auth endpoints ---
-    FCODE_CLOUD_URL: zod_1.z.string().min(1).default('https://code.factorial.dev/platform'),
+    FCODE_CLOUD_URL: zod_1.z.string().min(1).default('https://code.factorialhr.com/platform'),
     FCODE_AUTH_URL: zod_1.z.string().min(1).optional(),
     FCODE_CLIENT_ID: zod_1.z.string().min(1).default('cli'),
     // --- Local config location (defaults to os.homedir() at the call site) ---

package/dist/repositories/process.d.ts

@@ -1,5 +1,12 @@
-import { Process, ResourceMetadata, VersionedProcess } from '../core/types';
+import { Process, ProcessMetadataFields, ProgrammingLanguage, ResourceMetadata, VersionedProcess } from '../core/types';
 import ResourceRepositoryBase from './resource';
+/**
+ * What a process writes to metadata.json. Exported so anything rendering a process as its files
+ * — `saveFiles` here, `fcode diff` — produces the same bytes for the same process.
+ */
+export declare function buildProcessMetadata(process: Process): ProcessMetadataFields;
+export declare const PROCESS_SOURCE_CODE_FILE_NAME: (programmingLanguage: string) => string;
+export declare const PROCESS_DEPENDENCIES_FILE_NAME: (programmingLanguage: ProgrammingLanguage) => string;
 declare class ProcessRepository extends ResourceRepositoryBase<Process> {
     constructor();
     protected buildResourcePath(process: Process, filename: string, version?: string): string;
@@ -12,7 +19,6 @@ declare class ProcessRepository extends ResourceRepositoryBase<Process> {
     findSlugsNotAdded(): Promise<Array<string>>;
     find(processSlug: string, version?: string): Promise<Process>;
     private readMetadataFile;
-    private buildMetadata;
     findParameters(processSlug: string): Promise<any>;
     getLastFileModifiedDate(process: Process, filename: string): Promise<Date>;
     protected getResourcePath(process: Process): string;

package/dist/repositories/process.js

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROCESS_DEPENDENCIES_FILE_NAME = exports.PROCESS_SOURCE_CODE_FILE_NAME = void 0;
+exports.buildProcessMetadata = buildProcessMetadata;
 const fs = require("fs-extra");
 const crypto = require("node:crypto");
 const path = require("node:path");
@@ -17,6 +19,30 @@ const PROGRAMMING_LANGUAGE_DEPENDENCIES_FILE_NAME = {
     JAVASCRIPT: 'package.json',
     PYTHON: 'requirements.txt',
 };
+/**
+ * What a process writes to metadata.json. Exported so anything rendering a process as its files
+ * — `saveFiles` here, `fcode diff` — produces the same bytes for the same process.
+ */
+function buildProcessMetadata(process) {
+    const metadata = { name: process.name, tags: process.tags ?? [] };
+    if (process.description !== undefined) {
+        metadata.description = process.description;
+    }
+    if (process.webhook !== undefined) {
+        metadata.webhook = process.webhook;
+    }
+    if (process.form !== undefined) {
+        metadata.form = process.form;
+    }
+    if (process.uiTrigger !== undefined) {
+        metadata.uiTrigger = process.uiTrigger;
+    }
+    return metadata;
+}
+const PROCESS_SOURCE_CODE_FILE_NAME = (programmingLanguage) => (programmingLanguage === 'PYTHON' ? 'main.py' : 'index.js');
+exports.PROCESS_SOURCE_CODE_FILE_NAME = PROCESS_SOURCE_CODE_FILE_NAME;
+const PROCESS_DEPENDENCIES_FILE_NAME = (programmingLanguage) => PROGRAMMING_LANGUAGE_DEPENDENCIES_FILE_NAME[programmingLanguage];
+exports.PROCESS_DEPENDENCIES_FILE_NAME = PROCESS_DEPENDENCIES_FILE_NAME;
 class ProcessRepository extends resource_1.default {
     constructor() {
         super({
@@ -34,7 +60,7 @@ class ProcessRepository extends resource_1.default {
         return (0, filenamify_1.default)(process.slug);
     }
     getSourceCodeFileName(programmingLanguage) {
-        return programmingLanguage === 'PYTHON' ? 'main.py' : 'index.js';
+        return (0, exports.PROCESS_SOURCE_CODE_FILE_NAME)(programmingLanguage);
     }
     async findAll() {
         const { processes } = await this.workspaceConfig.getActiveTeam();
@@ -136,6 +162,7 @@ class ProcessRepository extends resource_1.default {
                 tags: Array.isArray(raw.tags) ? raw.tags : [],
                 webhook: raw.webhook,
                 form: raw.form,
+                uiTrigger: raw.uiTrigger,
             };
         }
         catch (error) {
@@ -145,19 +172,6 @@ class ProcessRepository extends resource_1.default {
             return { name: processSlug, tags: [] };
         }
     }
-    buildMetadata(process) {
-        const metadata = { name: process.name, tags: process.tags ?? [] };
-        if (process.description !== undefined) {
-            metadata.description = process.description;
-        }
-        if (process.webhook !== undefined) {
-            metadata.webhook = process.webhook;
-        }
-        if (process.form !== undefined) {
-            metadata.form = process.form;
-        }
-        return metadata;
-    }
     async findParameters(processSlug) {
         const processMetadata = await this.getProcessMetadata(processSlug);
         if (!processMetadata) {
@@ -234,7 +248,7 @@ class ProcessRepository extends resource_1.default {
             readOnly,
         });
         (0, file_utils_1.outputFileSyncIfChanged)(this.buildResourcePath(process, 'README.md'), process.readme || '', { readOnly });
-        (0, file_utils_1.outputFileSyncIfChanged)(this.buildResourcePath(process, 'metadata.json'), JSON.stringify(this.buildMetadata(process), null, 2), { readOnly });
+        (0, file_utils_1.outputFileSyncIfChanged)(this.buildResourcePath(process, 'metadata.json'), JSON.stringify(buildProcessMetadata(process), null, 2), { readOnly });
         (0, file_utils_1.outputFileSyncIfChanged)(this.buildResourcePath(process, 'parametersSchema.json'), JSON.stringify(process.script.parametersSchema, null, 2), { readOnly });
         const parametersFilePath = this.buildResourcePath(process, 'parameters.json');
         if (!fs.existsSync(parametersFilePath)) {

package/dist/repositories/programming-language-manifest.d.ts

@@ -1,17 +1,47 @@
-import { ResourceMetadata, ProgrammingLanguageManifest } from '../core/types';
+import { ProgrammingLanguage, ProgrammingLanguageManifest, ResourceMetadata, VersionedProgrammingLanguageManifest } from '../core/types';
 import ResourceRepositoryBase from './resource';
+/**
+ * The inherited file each language collapses its parents into. Exported so the gitignore sync names
+ * exactly what this repository writes, rather than repeating the strings.
+ */
+export declare const INHERITED_FILE_NAME: Record<ProgrammingLanguage, string>;
+export declare const DEPENDENCIES_DIR = "dependencies";
 declare class ProgrammingLanguageManifestRepository extends ResourceRepositoryBase<ProgrammingLanguageManifest> {
     constructor();
     find(slug: string): Promise<ProgrammingLanguageManifest>;
     protected getSourceCodeFileName(programmingLanguageManifest: ProgrammingLanguageManifest): string;
+    private getSourceCodeFileNameFor;
+    /**
+     * The inherited dependencies of one language, collapsed into a single file the way inherited
+     * variables are (`variables.inherited.env`) rather than one file per parent: two versions of the
+     * same package cannot be installed side by side, so there is only ever one winner per name and
+     * the platform has already picked it.
+     */
+    protected getInheritedFileName(programmingLanguage: ProgrammingLanguage): string;
+    getInheritedPath(programmingLanguage: ProgrammingLanguage): string;
+    private readInheritedDependencies;
     protected getResourceDirectory(programmingLanguageManifest: ProgrammingLanguageManifest): string;
     protected getResourcePath(programmingLanguageManifest: ProgrammingLanguageManifest): string;
     protected removeFiles(programmingLanguageManifest: ProgrammingLanguageManifest): Promise<void>;
     protected resourceToMetadata(programmingLanguageManifest: ProgrammingLanguageManifest): ResourceMetadata;
     protected saveFiles(programmingLanguageManifest: ProgrammingLanguageManifest): Promise<void>;
+    private removeInheritedFile;
     metadataFromFiles(slug: string): Promise<ResourceMetadata>;
     validSlug(slug: string): boolean;
     slugFormatMessage(): string;
+    /**
+     * Published snapshots live under `dependencies/versions/<tag>/`, one manifest file per language,
+     * mirroring the `versions/` folders of processes and modules. Written read-only: unlike those,
+     * these are pulled for visibility only — `fcode settings:versions:create` is what publishes them, and
+     * editing one here would push nothing.
+     */
+    private versionsDirectory;
+    private versionDirectory;
+    private versionPath;
+    getLocalVersionTags(): string[];
+    versionExistsLocally(version: VersionedProgrammingLanguageManifest): boolean;
+    removeVersion(tag: string): void;
+    saveVersion(version: VersionedProgrammingLanguageManifest): Promise<void>;
     findSlugsNotAdded(): Promise<Array<string>>;
 }
 export default ProgrammingLanguageManifestRepository;

package/dist/repositories/programming-language-manifest.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEPENDENCIES_DIR = exports.INHERITED_FILE_NAME = void 0;
 const fs = require("fs-extra");
 const path = require("node:path");
 const errors_1 = require("../core/errors");
@@ -7,6 +8,16 @@ const types_1 = require("../core/types");
 const resource_1 = require("./resource");
 const dependencies_1 = require("../core/utils/dependencies");
 const file_utils_1 = require("../utils/file-utils");
+/**
+ * The inherited file each language collapses its parents into. Exported so the gitignore sync names
+ * exactly what this repository writes, rather than repeating the strings.
+ */
+exports.INHERITED_FILE_NAME = {
+    JAVASCRIPT: 'package.inherited.json',
+    PYTHON: 'requirements.inherited.txt',
+};
+exports.DEPENDENCIES_DIR = 'dependencies';
+const VERSIONS_DIR = 'versions';
 class ProgrammingLanguageManifestRepository extends resource_1.default {
     constructor() {
         super({
@@ -21,14 +32,36 @@ class ProgrammingLanguageManifestRepository extends resource_1.default {
         }
         const sourceCodeFileContent = fs.readFileSync(this.getResourcePath(programmingLanguageManifest));
         try {
-            return new types_1.ProgrammingLanguageManifest(programmingLanguageManifest.id, programmingLanguageManifest.slug, programmingLanguageManifest.programmingLanguage, (0, dependencies_1.dependenciesFromFile)(programmingLanguageManifest.programmingLanguage, sourceCodeFileContent.toString()));
+            return new types_1.ProgrammingLanguageManifest(programmingLanguageManifest.id, programmingLanguageManifest.slug, programmingLanguageManifest.programmingLanguage, (0, dependencies_1.dependenciesFromFile)(programmingLanguageManifest.programmingLanguage, sourceCodeFileContent.toString()), this.readInheritedDependencies(programmingLanguageManifest.programmingLanguage));
         }
         catch (error) {
             throw new errors_1.LocalProgrammingLanguageManifestNotFound(error, slug);
         }
     }
     getSourceCodeFileName(programmingLanguageManifest) {
-        return programmingLanguageManifest.programmingLanguage === 'JAVASCRIPT' ? 'package.json' : 'requirements.txt';
+        return this.getSourceCodeFileNameFor(programmingLanguageManifest.programmingLanguage);
+    }
+    getSourceCodeFileNameFor(programmingLanguage) {
+        return programmingLanguage === 'JAVASCRIPT' ? 'package.json' : 'requirements.txt';
+    }
+    /**
+     * The inherited dependencies of one language, collapsed into a single file the way inherited
+     * variables are (`variables.inherited.env`) rather than one file per parent: two versions of the
+     * same package cannot be installed side by side, so there is only ever one winner per name and
+     * the platform has already picked it.
+     */
+    getInheritedFileName(programmingLanguage) {
+        return exports.INHERITED_FILE_NAME[programmingLanguage];
+    }
+    getInheritedPath(programmingLanguage) {
+        return path.join(this._repositoryName, this.getInheritedFileName(programmingLanguage));
+    }
+    readInheritedDependencies(programmingLanguage) {
+        const inheritedPath = this.getInheritedPath(programmingLanguage);
+        if (!fs.existsSync(inheritedPath)) {
+            return [];
+        }
+        return (0, dependencies_1.dependenciesFromFile)(programmingLanguage, fs.readFileSync(inheritedPath).toString());
     }
     getResourceDirectory(programmingLanguageManifest) {
         return this._repositoryName;
@@ -40,6 +73,7 @@ class ProgrammingLanguageManifestRepository extends resource_1.default {
         await new Promise((resolve, reject) => {
             try {
                 fs.removeSync(this.getResourcePath(programmingLanguageManifest));
+                this.removeInheritedFile(programmingLanguageManifest.programmingLanguage);
                 this.removeDirectoryIfEmpty(this.getResourceDirectory(programmingLanguageManifest));
                 resolve(true);
             }
@@ -57,6 +91,26 @@ class ProgrammingLanguageManifestRepository extends resource_1.default {
     }
     async saveFiles(programmingLanguageManifest) {
         (0, file_utils_1.outputFileSyncIfChanged)(this.getResourcePath(programmingLanguageManifest), (0, dependencies_1.dependenciesToFile)(programmingLanguageManifest.programmingLanguage, programmingLanguageManifest.dependencies));
+        const { programmingLanguage, inheritedDependencies } = programmingLanguageManifest;
+        if (inheritedDependencies.length === 0) {
+            // The workspace stopped inheriting anything (a parent was removed, or emptied its manifest):
+            // a stale file would keep being installed locally and keep showing in `status`.
+            this.removeInheritedFile(programmingLanguage);
+            return;
+        }
+        // Read-only, like inherited locales and modules: these belong to a parent workspace, and
+        // editing one here would change nothing — declare the name in package.json to override it.
+        (0, file_utils_1.outputFileSyncIfChanged)(this.getInheritedPath(programmingLanguage), (0, dependencies_1.dependenciesToFile)(programmingLanguage, inheritedDependencies), {
+            readOnly: true,
+        });
+    }
+    removeInheritedFile(programmingLanguage) {
+        const inheritedPath = this.getInheritedPath(programmingLanguage);
+        if (fs.existsSync(inheritedPath)) {
+            // Written read-only, so it has to be made writable before it can go.
+            fs.chmodSync(inheritedPath, 0o644);
+            fs.removeSync(inheritedPath);
+        }
     }
     async metadataFromFiles(slug) {
         if (slug === 'JAVASCRIPT') {
@@ -81,6 +135,46 @@ class ProgrammingLanguageManifestRepository extends resource_1.default {
     slugFormatMessage() {
         return 'Only JAVASCRIPT or PYTHON are allowed.';
     }
+    /**
+     * Published snapshots live under `dependencies/versions/<tag>/`, one manifest file per language,
+     * mirroring the `versions/` folders of processes and modules. Written read-only: unlike those,
+     * these are pulled for visibility only — `fcode settings:versions:create` is what publishes them, and
+     * editing one here would push nothing.
+     */
+    versionsDirectory() {
+        return path.join(this._repositoryName, VERSIONS_DIR);
+    }
+    versionDirectory(tag) {
+        return path.join(this.versionsDirectory(), tag);
+    }
+    versionPath(version) {
+        return path.join(this.versionDirectory(version.tag), this.getSourceCodeFileNameFor(version.programmingLanguage));
+    }
+    getLocalVersionTags() {
+        const versionsDir = this.versionsDirectory();
+        if (!fs.pathExistsSync(versionsDir)) {
+            return [];
+        }
+        return fs.readdirSync(versionsDir).filter((name) => this.validVersion(name));
+    }
+    versionExistsLocally(version) {
+        return fs.pathExistsSync(this.versionPath(version));
+    }
+    removeVersion(tag) {
+        const versionDirectory = this.versionDirectory(tag);
+        if (!fs.pathExistsSync(versionDirectory)) {
+            return;
+        }
+        // Written read-only, so every file has to be made writable before the directory can go.
+        for (const fileName of fs.readdirSync(versionDirectory)) {
+            fs.chmodSync(path.join(versionDirectory, fileName), 0o644);
+        }
+        fs.removeSync(versionDirectory);
+        this.removeDirectoryIfEmpty(this.versionsDirectory());
+    }
+    async saveVersion(version) {
+        (0, file_utils_1.outputFileSyncIfChanged)(this.versionPath(version), (0, dependencies_1.dependenciesToFile)(version.programmingLanguage, version.dependencies), { readOnly: true });
+    }
     async findSlugsNotAdded() {
         const slugsNotAdded = [];
         if (!(await this.workspaceConfig.exists('dependencies', 'JAVASCRIPT')) && fs.existsSync(path.join(this._repositoryName, 'package.json'))) {

package/dist/repositories/settings.d.ts

@@ -0,0 +1,52 @@
+import { RawTeamSettings, TeamVersion, TeamVersionAlias, WorkspaceSettings } from '../core/types';
+import WorkspaceConfig from '../config/workspace';
+export declare const SETTINGS_FILENAME = "settings.json";
+/**
+ * Workspaces cloned before the file was renamed carry team.json. Renaming it on first access keeps
+ * the stored sync hash valid (it is computed over the content, not the name), so the workspace does
+ * not report a phantom conflict. Only fires when the new name is absent, so a workspace holding both
+ * is left alone.
+ */
+export declare function migrateLegacySettingsFile(workspaceDir?: string): void;
+/**
+ * Reads/writes the singleton settings.json (timezone, error handler, inheritance, webhook auth) at
+ * the workspace root. Unlike collection resources this is not a ResourceRepositoryBase:
+ * a workspace has exactly one settings file, so there is no slug-keyed collection to manage.
+ *
+ * settings.json references the error-handler process by slug for portability; the cloud
+ * references it by id, so this repository resolves slug<->id against the tracked
+ * process metadata in .fcode/.
+ */
+export default class SettingsRepository {
+    protected workspaceConfig: WorkspaceConfig;
+    exists(): boolean;
+    find(): Promise<WorkspaceSettings>;
+    save(settings: WorkspaceSettings): void;
+    /** Builds the settings from the cloud's raw payload, resolving the error-handler id to a slug. */
+    fromRaw(raw: RawTeamSettings): Promise<WorkspaceSettings>;
+    /**
+     * Writes the cloud's workspace versions and aliases into the settings as the settings.json
+     * versioning fields (sorted for stable git diffs). Cloud entries always carry a createdAt; only
+     * hand-added local entries lack one, and those never pass through here.
+     */
+    applyCloudVersioning(settings: WorkspaceSettings, versions: TeamVersion[], aliases: TeamVersionAlias[]): void;
+    resolveSlugToId(processSlug: string): Promise<string>;
+    resolveIdToSlug(processId: string): Promise<string>;
+    private parseErrorHandler;
+    /**
+     * settings.json is hand-edited to declare versions, so entries without a tag are dropped and a
+     * duplicated tag keeps its first entry (a tag names one immutable snapshot).
+     */
+    private parseVersions;
+    /**
+     * An alias is a name->tag pointer; entries missing either half are dropped and a duplicated
+     * name keeps its first entry.
+     */
+    private parseAliases;
+    /** A configuration without a variable key is meaningless, so it is read as absent. */
+    private parseWebhookAuth;
+    /** Accepts plain slugs (unpinned) next to { slug, version } objects, in file order. */
+    private parseParentTeams;
+    /** The settings.json shape. Public so `fcode diff` renders cloud settings into the same bytes a pull would write. */
+    toFile(settings: WorkspaceSettings): Record<string, any>;
+}

package/dist/repositories/settings.js

@@ -0,0 +1,214 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SETTINGS_FILENAME = void 0;
+exports.migrateLegacySettingsFile = migrateLegacySettingsFile;
+const fs = require("fs-extra");
+const path = require("node:path");
+const types_1 = require("../core/types");
+const workspace_1 = require("../config/workspace");
+const file_utils_1 = require("../utils/file-utils");
+exports.SETTINGS_FILENAME = 'settings.json';
+const LEGACY_SETTINGS_FILENAME = 'team.json';
+/**
+ * Workspaces cloned before the file was renamed carry team.json. Renaming it on first access keeps
+ * the stored sync hash valid (it is computed over the content, not the name), so the workspace does
+ * not report a phantom conflict. Only fires when the new name is absent, so a workspace holding both
+ * is left alone.
+ */
+function migrateLegacySettingsFile(workspaceDir = process.cwd()) {
+    const legacy = path.join(workspaceDir, LEGACY_SETTINGS_FILENAME);
+    const current = path.join(workspaceDir, exports.SETTINGS_FILENAME);
+    if (fs.pathExistsSync(legacy) && !fs.pathExistsSync(current)) {
+        fs.renameSync(legacy, current);
+    }
+}
+/**
+ * Reads/writes the singleton settings.json (timezone, error handler, inheritance, webhook auth) at
+ * the workspace root. Unlike collection resources this is not a ResourceRepositoryBase:
+ * a workspace has exactly one settings file, so there is no slug-keyed collection to manage.
+ *
+ * settings.json references the error-handler process by slug for portability; the cloud
+ * references it by id, so this repository resolves slug<->id against the tracked
+ * process metadata in .fcode/.
+ */
+class SettingsRepository {
+    constructor() {
+        this.workspaceConfig = new workspace_1.default();
+    }
+    exists() {
+        migrateLegacySettingsFile();
+        return fs.pathExistsSync(exports.SETTINGS_FILENAME);
+    }
+    async find() {
+        migrateLegacySettingsFile();
+        const slug = await this.workspaceConfig.getActiveTeamSlug();
+        let raw = {};
+        try {
+            raw = fs.readJsonSync(exports.SETTINGS_FILENAME) || {};
+        }
+        catch { }
+        const settings = new types_1.WorkspaceSettings(slug, this.parseParentTeams(raw.parentTeams), raw.zoneId, this.parseErrorHandler(raw.errorHandlerConfig), this.parseWebhookAuth(raw.webhookAuth), typeof raw.primaryLocale === 'string' && raw.primaryLocale.length > 0 ? raw.primaryLocale : undefined);
+        if (Array.isArray(raw.versions)) {
+            settings.versions = this.parseVersions(raw.versions);
+        }
+        if (Array.isArray(raw.aliases)) {
+            settings.aliases = this.parseAliases(raw.aliases);
+        }
+        return settings;
+    }
+    save(settings) {
+        migrateLegacySettingsFile();
+        (0, file_utils_1.outputFileSyncIfChanged)(exports.SETTINGS_FILENAME, JSON.stringify(this.toFile(settings), null, 2));
+    }
+    /** Builds the settings from the cloud's raw payload, resolving the error-handler id to a slug. */
+    async fromRaw(raw) {
+        let errorHandlerConfig;
+        if (raw.errorHandlerConfig?.processId) {
+            errorHandlerConfig = {
+                processSlug: await this.resolveIdToSlug(raw.errorHandlerConfig.processId),
+                tag: raw.errorHandlerConfig.tag ?? null,
+            };
+        }
+        return new types_1.WorkspaceSettings(raw.slug, raw.parentTeams ?? [], raw.zoneId, errorHandlerConfig, this.parseWebhookAuth(raw.webhookAuth), raw.primaryLocale ?? undefined);
+    }
+    /**
+     * Writes the cloud's workspace versions and aliases into the settings as the settings.json
+     * versioning fields (sorted for stable git diffs). Cloud entries always carry a createdAt; only
+     * hand-added local entries lack one, and those never pass through here.
+     */
+    applyCloudVersioning(settings, versions, aliases) {
+        settings.versions = versions
+            .map((version) => {
+            const entry = { tag: version.tag, createdAt: version.createdAt };
+            if (version.comment) {
+                entry.comment = version.comment;
+            }
+            return entry;
+        })
+            .sort((a, b) => (a.createdAt ?? '').localeCompare(b.createdAt ?? ''));
+        settings.aliases = aliases
+            .map((alias) => ({ name: alias.name, tag: alias.tag }))
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async resolveSlugToId(processSlug) {
+        const { processes } = await this.workspaceConfig.getActiveTeam();
+        return processes[processSlug]?.id ?? processSlug;
+    }
+    async resolveIdToSlug(processId) {
+        const { processes } = await this.workspaceConfig.getActiveTeam();
+        const match = Object.values(processes).find((process) => process.id === processId);
+        return match?.slug ?? processId;
+    }
+    parseErrorHandler(raw) {
+        if (!raw || !raw.processSlug) {
+            return undefined;
+        }
+        return { processSlug: raw.processSlug, tag: raw.tag ?? null };
+    }
+    /**
+     * settings.json is hand-edited to declare versions, so entries without a tag are dropped and a
+     * duplicated tag keeps its first entry (a tag names one immutable snapshot).
+     */
+    parseVersions(raw) {
+        const versions = [];
+        for (const candidate of raw) {
+            if (!candidate || typeof candidate.tag !== 'string' || candidate.tag.length === 0) {
+                continue;
+            }
+            if (versions.some(({ tag }) => tag === candidate.tag)) {
+                continue;
+            }
+            const entry = { tag: candidate.tag };
+            if (typeof candidate.comment === 'string' && candidate.comment.length > 0) {
+                entry.comment = candidate.comment;
+            }
+            if (typeof candidate.createdAt === 'string' && candidate.createdAt.length > 0) {
+                entry.createdAt = candidate.createdAt;
+            }
+            versions.push(entry);
+        }
+        return versions;
+    }
+    /**
+     * An alias is a name->tag pointer; entries missing either half are dropped and a duplicated
+     * name keeps its first entry.
+     */
+    parseAliases(raw) {
+        const aliases = [];
+        for (const candidate of raw) {
+            if (!candidate || typeof candidate.name !== 'string' || candidate.name.length === 0) {
+                continue;
+            }
+            if (typeof candidate.tag !== 'string' || candidate.tag.length === 0) {
+                continue;
+            }
+            if (aliases.some(({ name }) => name === candidate.name)) {
+                continue;
+            }
+            aliases.push({ name: candidate.name, tag: candidate.tag });
+        }
+        return aliases;
+    }
+    /** A configuration without a variable key is meaningless, so it is read as absent. */
+    parseWebhookAuth(raw) {
+        if (!raw || typeof raw.variableKey !== 'string' || raw.variableKey.length === 0) {
+            return undefined;
+        }
+        const webhookAuth = { variableKey: raw.variableKey };
+        // The default header is left out so a pull writes the minimal form.
+        if (typeof raw.headerName === 'string' && raw.headerName.length > 0 && raw.headerName !== types_1.DEFAULT_WEBHOOK_AUTH_HEADER) {
+            webhookAuth.headerName = raw.headerName;
+        }
+        return webhookAuth;
+    }
+    /** Accepts plain slugs (unpinned) next to { slug, version } objects, in file order. */
+    parseParentTeams(raw) {
+        if (!Array.isArray(raw)) {
+            return [];
+        }
+        const refs = [];
+        for (const entry of raw) {
+            if (typeof entry === 'string' && entry.length > 0) {
+                refs.push({ slug: entry });
+            }
+            else if (entry && typeof entry === 'object' && typeof entry.slug === 'string' && entry.slug.length > 0) {
+                const ref = { slug: entry.slug };
+                if (typeof entry.version === 'string' && entry.version.length > 0) {
+                    ref.version = entry.version;
+                }
+                refs.push(ref);
+            }
+        }
+        return refs;
+    }
+    /** The settings.json shape. Public so `fcode diff` renders cloud settings into the same bytes a pull would write. */
+    toFile(settings) {
+        // Unpinned parents are written as plain slugs (the minimal form, and what a hand-written
+        // settings.json most likely contains); pinned ones as { slug, version } objects.
+        const file = {
+            parentTeams: (settings.parentTeams ?? []).map((ref) => (ref.version ? { slug: ref.slug, version: ref.version } : ref.slug)),
+        };
+        if (settings.zoneId !== undefined) {
+            file.zoneId = settings.zoneId;
+        }
+        if (settings.errorHandlerConfig !== undefined) {
+            file.errorHandlerConfig = settings.errorHandlerConfig;
+        }
+        // Last, so adding webhook auth to an existing settings.json is a purely additive diff.
+        if (settings.webhookAuth !== undefined) {
+            file.webhookAuth = settings.webhookAuth;
+        }
+        if (settings.primaryLocale !== undefined) {
+            file.primaryLocale = settings.primaryLocale;
+        }
+        // Global versioning fields, appended after the scalar settings.
+        if (settings.versions !== undefined) {
+            file.versions = settings.versions;
+        }
+        if (settings.aliases !== undefined) {
+            file.aliases = settings.aliases;
+        }
+        return file;
+    }
+}
+exports.default = SettingsRepository;

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

@@ -81,22 +81,32 @@ class Processes(dict):
 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.
+    The CLI has already layered the chosen locale over the workspace's primary one, so the base
+    map that arrives here is flat. ``byLocale`` carries each locale's own files, so a call naming
+    a locale (``{"locale": "es"}``) resolves against that locale first and falls back key by key
+    to the base map, exactly like the cloud executors. Nothing raises: a key with no translation
+    resolves to the key itself, and a placeholder with no argument is left exactly as written.
+
+    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.__by_locale = payload.get("byLocale") or {}
         self.locale = payload.get("locale")
 
     def __call__(self, key, args=None, options=None):
-        template = self.__translations.get(key)
+        locale = options.get("locale") if isinstance(options, dict) else None
+        template = None
+        for locale_map in self.__locale_chain(str(locale) if locale is not None else None):
+            template = locale_map.get(key)
+            if template is not None:
+                break
+        if template is None:
+            template = self.__translations.get(key)
         if template is None:
             return key
         if not isinstance(args, dict):
@@ -111,6 +121,30 @@ class I18n:
         # Single pass, so a substituted value containing %{...} is never rescanned.
         return re.sub(r"%\{([^}]*)\}", replace, template)
 
+    def __locale_chain(self, locale):
+        """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.
+        """
+        if locale is None or not self.__by_locale:
+            return []
+        names = list(self.__by_locale.keys())
+        chain = []
+        candidate = locale
+        while 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
+            if match is not None and match not in chain:
+                chain.append(match)
+            last_separator = max(candidate.rfind("-"), candidate.rfind("_"))
+            candidate = candidate[:last_separator] if last_separator > 0 else None
+        return [self.__by_locale[name] for name in chain if self.__by_locale[name]]
+
 
 class FcodeGlobal:
     def __init__(self, context, execution, env, datastore, storage, schedule, variables, i18n=None):