@factorialco/fcode-cli 2.0.0 → 2.2.0

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;
@@ -205,7 +229,7 @@ export declare class Variable extends Resource {
     key: string;
     value: string;
     overriddenLocally?: boolean;
-    constructor(id: string | undefined, key: string, value: string, isSensitive: boolean);
+    constructor(id: string | undefined, key: string, value: string, isSensitive: boolean, resolvingTeamSlug?: string);
     static validate(variable: Variable): Variable;
     get contentHash(): string;
 }
@@ -221,6 +245,40 @@ export interface ErrorHandlerConfig {
     processSlug: string;
     tag?: string | null;
 }
+export interface TeamVersionManifestEntry {
+    resourceType: 'MODULE' | 'PROCESS';
+    resourceId: string;
+    slug: string;
+    outcome: 'CREATED' | 'FAILED' | 'SKIPPED_EXISTS' | 'SKIPPED_NO_TAG' | 'UPDATED';
+    error?: string | null;
+}
+export interface TeamVersion {
+    id: string;
+    tag: string;
+    comment?: string | null;
+    manifest: TeamVersionManifestEntry[];
+    createdAt: string;
+    createdBy?: {
+        id: string;
+        name: string;
+    } | null;
+}
+export interface TeamVersionAlias {
+    id: string;
+    name: string;
+    tag: string;
+    createdAt: string;
+    updatedAt?: string | null;
+}
+export interface TeamVersionFileEntry {
+    tag: string;
+    comment?: string;
+    createdAt: string;
+}
+export interface TeamAliasFileEntry {
+    name: string;
+    tag: string;
+}
 export declare class Team extends Resource {
     id: string | undefined;
     slug: string;
@@ -228,7 +286,10 @@ export declare class Team extends Resource {
     errorHandlerConfig?: ErrorHandlerConfig;
     parentTeamSlugs: string[];
     webhookAuth?: WebhookAuth;
-    constructor(slug: string, parentTeamSlugs: string[], zoneId?: string, errorHandlerConfig?: ErrorHandlerConfig, webhookAuth?: WebhookAuth);
+    primaryLocale?: string;
+    versions?: TeamVersionFileEntry[];
+    aliases?: TeamAliasFileEntry[];
+    constructor(slug: string, parentTeamSlugs: string[], zoneId?: string, errorHandlerConfig?: ErrorHandlerConfig, webhookAuth?: WebhookAuth, primaryLocale?: string);
     get contentHash(): string;
 }
 export interface RawErrorHandlerConfig {
@@ -241,6 +302,7 @@ export interface RawTeamSettings {
     errorHandlerConfig?: RawErrorHandlerConfig | null;
     parentTeamSlugs: string[];
     webhookAuth?: WebhookAuth | null;
+    primaryLocale?: string | null;
 }
 export interface TeamUpdateInput {
     zoneId?: string;
@@ -250,6 +312,7 @@ export interface TeamUpdateInput {
         headerName?: string | null;
         variableKey?: string | null;
     } | null;
+    primaryLocale?: string;
 }
 export type ResourceMetadata = {
     [key: string]: any;
@@ -281,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();
@@ -118,13 +153,14 @@ class VersionedScriptLibrary extends Resource {
 }
 exports.VersionedScriptLibrary = VersionedScriptLibrary;
 class Variable extends Resource {
-    constructor(id, key, value, isSensitive) {
+    constructor(id, key, value, isSensitive, resolvingTeamSlug) {
         super();
         this.id = id;
         this.slug = key;
         this.key = key;
         this.value = value;
         this.isSensitive = isSensitive;
+        this.resolvingTeamSlug = resolvingTeamSlug;
     }
     static validate(variable) {
         if (!Variable.ENV_KEY_REGEX.test(variable.key)) {
@@ -165,13 +201,14 @@ 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 = {
@@ -185,6 +222,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/env.d.ts

@@ -27,7 +27,7 @@ export declare const envSchema: z.ZodObject<{
         false: "false";
     }>>;
     CLI_UX_SKIP_TTY_CHECK: z.ZodOptional<z.ZodString>;
-    YC_COMMAND: z.ZodOptional<z.ZodString>;
+    FC_COMMAND: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const env: {
     FCODE_CLOUD_URL: string;
@@ -38,6 +38,6 @@ export declare const env: {
     FCODE_DISABLE_UPDATE_NOTIFIER?: "true" | "false" | undefined;
     SILENT_MODE?: "true" | "false" | undefined;
     CLI_UX_SKIP_TTY_CHECK?: string | undefined;
-    YC_COMMAND?: string | undefined;
+    FC_COMMAND?: string | undefined;
 };
 export default env;

package/dist/env.js

@@ -25,7 +25,7 @@ exports.envSchema = zod_1.z.object({
     SILENT_MODE: zod_1.z.enum(['true', 'false']).optional(),
     CLI_UX_SKIP_TTY_CHECK: zod_1.z.string().min(1).optional(),
     // --- Debug tooling ---
-    YC_COMMAND: zod_1.z.string().min(1).optional(),
+    FC_COMMAND: zod_1.z.string().min(1).optional(),
 });
 /** Treat empty strings (e.g. an unset shell/dotenv var rendered as "") as missing. */
 const raw = Object.fromEntries(Object.entries(process.env).filter(([, value]) => value !== ''));

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.d.ts

@@ -1,4 +1,4 @@
-import { RawTeamSettings, Team } from '../core/types';
+import { RawTeamSettings, Team, TeamVersion, TeamVersionAlias } from '../core/types';
 import WorkspaceConfig from '../config/workspace';
 /**
  * Reads/writes the singleton team.json (timezone, error handler, inheritance, webhook auth) at the
@@ -16,6 +16,12 @@ export default class TeamRepository {
     save(team: Team): void;
     /** Builds a Team from the cloud's raw settings, resolving the error-handler id to a slug. */
     fromRaw(raw: RawTeamSettings): Promise<Team>;
+    /**
+     * Writes the cloud's team versions and aliases into the Team as the pull-only team.json
+     * fields (sorted for stable git diffs). These fields never enter the content hash and are
+     * stripped from pushes: all writes go through the team:versions/team:aliases commands.
+     */
+    applyCloudVersioning(team: Team, versions: TeamVersion[], aliases: TeamVersionAlias[]): void;
     resolveSlugToId(processSlug: string): Promise<string>;
     resolveIdToSlug(processId: string): Promise<string>;
     private parseErrorHandler;

package/dist/repositories/team.js

@@ -29,7 +29,15 @@ class TeamRepository {
         }
         catch { }
         const parentTeamSlugs = Array.isArray(raw.parentTeamSlugs) ? raw.parentTeamSlugs : [];
-        return 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;
+        }
+        if (Array.isArray(raw.aliases)) {
+            team.aliases = raw.aliases;
+        }
+        return team;
     }
     save(team) {
         (0, file_utils_1.outputFileSyncIfChanged)(TEAM_FILENAME, JSON.stringify(this.toFile(team), null, 2));
@@ -43,7 +51,26 @@ 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
+     * fields (sorted for stable git diffs). These fields never enter the content hash and are
+     * stripped from pushes: all writes go through the team:versions/team:aliases commands.
+     */
+    applyCloudVersioning(team, versions, aliases) {
+        team.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));
+        team.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();
@@ -84,6 +111,16 @@ 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;
+        }
+        if (team.aliases !== undefined) {
+            file.aliases = team.aliases;
+        }
         return file;
     }
 }

package/dist/repositories/variable.d.ts

@@ -4,16 +4,40 @@ export declare const DEFAULT_SENSITIVE_VALUE = "********";
 declare class VariableRepository extends ResourceRepositoryBase<Variable> {
     private filename;
     private localFilename;
+    private inheritedFilename;
     private filenameInitPromise;
     constructor();
     private ensureFilenamesInitialized;
     findAll(): Promise<Variable[]>;
+    /**
+     * Values as a local run sees them. Precedence, lowest first: variables inherited from
+     * parent workspaces, this workspace's own variables, and the local overrides file — the
+     * same order the platform applies, where a workspace's own value wins over an inherited one.
+     * An empty value is not an override but an unset one: the platform rejects blank values, and
+     * a variable emptied in variables.env is a removal (see `mapResourceStatus`), so an empty
+     * entry falls through to the layer below rather than blanking it.
+     */
     findAllForExecution(): Promise<Variable[]>;
+    /**
+     * An inherited key the workspace has given a value of its own, overriding it. An empty entry
+     * does not count: the platform has no empty values, so it reads as "not set" here too.
+     */
+    private overridesInherited;
     find(slug: string): Promise<Variable>;
+    /**
+     * Keys declared in the workspace's own variables file that its metadata does not claim yet.
+     * A key the workspace inherits counts as one of those: the metadata still points at the
+     * parent's variable, and adding it is what turns the entry into this workspace's own.
+     */
     findSlugsNotAdded(): Promise<Array<string>>;
     protected getResourcePath(_resource: Variable): string;
     protected removeFiles(variable: Variable): Promise<void>;
     protected resourceToMetadata(variable: Variable): ResourceMetadata;
+    /**
+     * A variable owned by this workspace goes to the committed variables file; one inherited
+     * from a parent workspace goes to the gitignored inherited file, so a local run can use it
+     * without the child workspace's git history carrying a copy of its parent's values.
+     */
     protected saveFiles(variable: Variable): Promise<void>;
     metadataFromFiles(slug: string, opts: AddResourceOptions): Promise<ResourceMetadata>;
     private readVariablesMeta;