@factorialco/fcode-cli 2.4.0 → 3.0.0

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

@@ -17,6 +17,7 @@ exports.INHERITED_FILE_NAME = {
     PYTHON: 'requirements.inherited.txt',
 };
 exports.DEPENDENCIES_DIR = 'dependencies';
+const VERSIONS_DIR = 'versions';
 class ProgrammingLanguageManifestRepository extends resource_1.default {
     constructor() {
         super({
@@ -38,7 +39,10 @@ class ProgrammingLanguageManifestRepository extends resource_1.default {
         }
     }
     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
@@ -131,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

@@ -100,8 +100,11 @@ class I18n:
 
     def __call__(self, key, args=None, options=None):
         locale = options.get("locale") if isinstance(options, dict) else None
-        locale_map = self.__by_locale.get(str(locale)) if locale is not None else None
-        template = locale_map.get(key) if locale_map is not None 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:
@@ -118,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):

package/dist/services/dashboard-client.d.ts

@@ -0,0 +1,31 @@
+import GlobalConfig from '../config/global';
+export interface DevelopmentTeam {
+    id: string;
+    name: string;
+}
+export interface DevelopmentTeamApp {
+    id: string;
+    name: string;
+    description: string | null;
+}
+/**
+ * `https://code.factorialhr.com/platform` → `https://code.factorialhr.com/dashboard/api/v1`.
+ * The dashboard is served under `/dashboard` on the same origin as the platform; environments
+ * that split them can point `FCODE_DASHBOARD_URL` at the API base directly.
+ */
+export declare function dashboardApiUrl(cloudUrl: string): string;
+export default class DashboardClient {
+    private readonly cloudUrl;
+    private readonly baseUrl;
+    /** Instance property so tests can supply a stub instead of the real `~/.fcode/fcode.json`. */
+    globalConfig: GlobalConfig;
+    constructor(cloudUrl: string);
+    /** The development teams the session belongs to. Operators get every team. */
+    listDevelopmentTeams(): Promise<DevelopmentTeam[]>;
+    /** The Apps owned by a development team, narrowed by the API to the ones the session can see. */
+    listTeamApps(teamId: string): Promise<DevelopmentTeamApp[]>;
+    private getAllPages;
+    private get;
+    private headers;
+    private errorDetail;
+}

package/dist/services/dashboard-client.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dashboardApiUrl = dashboardApiUrl;
+const node_fetch_1 = require("node-fetch");
+const auth_service_1 = require("./auth-service");
+const global_1 = require("../config/global");
+/**
+ * The dashboard's control plane — where Apps and development teams live — as opposed to the
+ * platform GraphQL API that `FcodeGraphQLClient` talks to. Both sit behind the same host and
+ * accept the same Keycloak token: the dashboard verifies the realm signature and issuer, so the
+ * session `fcode login` already established is enough.
+ */
+/** Max the dashboard's list endpoints accept (`listQuerySchema`), so a team is one round trip. */
+const PAGE_SIZE = 200;
+/**
+ * `https://code.factorialhr.com/platform` → `https://code.factorialhr.com/dashboard/api/v1`.
+ * The dashboard is served under `/dashboard` on the same origin as the platform; environments
+ * that split them can point `FCODE_DASHBOARD_URL` at the API base directly.
+ */
+function dashboardApiUrl(cloudUrl) {
+    const override = process.env.FCODE_DASHBOARD_URL;
+    if (override) {
+        return override.replace(/\/+$/, '');
+    }
+    return `${new URL(cloudUrl).origin}/dashboard/api/v1`;
+}
+class DashboardClient {
+    constructor(cloudUrl) {
+        this.cloudUrl = cloudUrl;
+        /** Instance property so tests can supply a stub instead of the real `~/.fcode/fcode.json`. */
+        this.globalConfig = new global_1.default();
+        this.baseUrl = dashboardApiUrl(cloudUrl);
+    }
+    /** The development teams the session belongs to. Operators get every team. */
+    async listDevelopmentTeams() {
+        const items = await this.getAllPages('/development-teams');
+        return items.map(({ id, company_name }) => ({ id, name: company_name }));
+    }
+    /** The Apps owned by a development team, narrowed by the API to the ones the session can see. */
+    async listTeamApps(teamId) {
+        const items = await this.getAllPages('/apps', {
+            development_team_id: teamId,
+            sort_by: 'name',
+            sort_dir: 'asc',
+        });
+        return items.map(({ id, name, description }) => ({ id, name, description }));
+    }
+    async getAllPages(path, query = {}) {
+        const items = [];
+        let offset = 0;
+        // `total` is authoritative rather than "a short page means the end": a page can come back
+        // short when the API narrows it to what the session may see.
+        let total = Number.POSITIVE_INFINITY;
+        while (items.length < total) {
+            const page = await this.get(path, {
+                ...query,
+                limit: String(PAGE_SIZE),
+                offset: String(offset),
+            });
+            items.push(...page.items);
+            total = page.total;
+            if (page.items.length === 0) {
+                break;
+            }
+            offset += page.items.length;
+        }
+        return items;
+    }
+    async get(path, query) {
+        const url = `${this.baseUrl}${path}?${new URLSearchParams(query).toString()}`;
+        let response = await (0, node_fetch_1.default)(url, { headers: await this.headers() });
+        // The token's group membership is snapshotted at issuance (FCT-61231), so a team joined after
+        // login reads as a denial. Re-mint once and retry before believing it.
+        if (response.status === 401 || response.status === 403) {
+            if (await auth_service_1.default.refreshSession(this.cloudUrl)) {
+                response = await (0, node_fetch_1.default)(url, { headers: await this.headers() });
+            }
+        }
+        if (!response.ok) {
+            throw new Error(`Dashboard API ${response.status} on ${path}: ${await this.errorDetail(response)}`);
+        }
+        return (await response.json());
+    }
+    async headers() {
+        const { token } = await this.globalConfig.getAuthInfo(this.cloudUrl);
+        return { accept: 'application/json', authorization: `Bearer ${token.access_token}` };
+    }
+    async errorDetail(response) {
+        try {
+            const body = await response.text();
+            const parsed = JSON.parse(body);
+            return parsed.detail ?? parsed.message ?? body;
+        }
+        catch {
+            return 'no response body';
+        }
+    }
+}
+exports.default = DashboardClient;

package/dist/services/dev-team-service.d.ts

@@ -0,0 +1,41 @@
+import DashboardClient, { DevelopmentTeam, DevelopmentTeamApp } from './dashboard-client';
+import { DevTeamApp, DevTeamMetadata } from '../config/dev-team';
+/** What a team folder has to do to match the team as the dashboard currently describes it. */
+export interface AppSyncPlan {
+    /** In the team, with no folder yet — cloned. */
+    toClone: DevelopmentTeamApp[];
+    /** In the team and already cloned — refreshed and pulled. */
+    toRefresh: DevelopmentTeamApp[];
+    /** Recorded locally but no longer in the team — reported, never deleted. */
+    removed: Array<{
+        id: string;
+        app: DevTeamApp;
+    }>;
+}
+export declare function planAppSync(metadata: DevTeamMetadata, apps: DevelopmentTeamApp[]): AppSyncPlan;
+/**
+ * The folder an App gets inside the team root. Names are free text and two Apps may well slugify
+ * the same, so the first claimant keeps the plain slug and the next ones are suffixed. Only ever
+ * called for an App without a recorded folder — afterwards the team metadata is authoritative, so
+ * a renamed App keeps the folder it was cloned into.
+ */
+export declare function assignFolder(app: DevelopmentTeamApp, metadata: DevTeamMetadata): string;
+export interface AppSyncOutcome {
+    name: string;
+    folder: string;
+    action: 'cloned' | 'pulled';
+    error?: Error;
+}
+/**
+ * Applies the plan, one App at a time, recording the metadata of each App that lands. A failing
+ * App is reported and the run carries on: with a dozen Apps, one bad workspace must not cost the
+ * other eleven.
+ */
+export declare function syncApps(rootDir: string, metadata: DevTeamMetadata, plan: AppSyncPlan): Promise<AppSyncOutcome[]>;
+/** Prints the per-App result and reports whether anything failed. */
+export declare function reportOutcomes(outcomes: AppSyncOutcome[], removed: AppSyncPlan['removed']): boolean;
+/**
+ * The team to operate on: the one named, the only one the session belongs to, or — when there are
+ * several — none, after listing them so the user can pass an id.
+ */
+export declare function resolveTeam(client: DashboardClient, teamId?: string): Promise<DevelopmentTeam | undefined>;