@factorialco/fcode-cli 2.3.0 → 3.0.0

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>;

package/dist/services/dev-team-service.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planAppSync = planAppSync;
+exports.assignFolder = assignFolder;
+exports.syncApps = syncApps;
+exports.reportOutcomes = reportOutcomes;
+exports.resolveTeam = resolveTeam;
+const fs = require("fs-extra");
+const path = require("node:path");
+const color_1 = require("@oclif/color");
+const pull_1 = require("../commands/pull");
+const dev_team_1 = require("../config/dev-team");
+const skills_installer_1 = require("./skills-installer");
+const dev_slug_1 = require("../utils/dev-slug");
+const workspace_cloner_1 = require("./workspace-cloner");
+const slugify_1 = require("../utils/slugify");
+const cli_1 = require("../utils/cli");
+function planAppSync(metadata, apps) {
+    const remoteIds = new Set(apps.map(({ id }) => id));
+    return {
+        toClone: apps.filter(({ id }) => metadata.apps[id] === undefined),
+        toRefresh: apps.filter(({ id }) => metadata.apps[id] !== undefined),
+        removed: Object.entries(metadata.apps)
+            .filter(([id]) => !remoteIds.has(id))
+            .map(([id, app]) => ({ id, app })),
+    };
+}
+/**
+ * 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.
+ */
+function assignFolder(app, metadata) {
+    const taken = new Set(Object.values(metadata.apps).map(({ folder }) => folder));
+    return (0, slugify_1.uniqueSlug)((0, slugify_1.slugifyOr)(app.name, app.id), taken);
+}
+/**
+ * The team folder holds the skills once (installing them per App would download the same tree N
+ * times); the App and its workspace link to them, so an agent started in either place resolves
+ * them. The link stays out of git through the App's own .gitignore.
+ */
+function linkSkills(rootDir, appDir, workspaceDir) {
+    (0, skills_installer_1.linkSkillsInto)(appDir, rootDir);
+    (0, skills_installer_1.linkSkillsInto)(workspaceDir, rootDir);
+}
+/** A committed .gitignore, since each App folder is meant to become its own repository. */
+function writeAppGitIgnore(appDir) {
+    const gitIgnorePath = path.join(appDir, '.gitignore');
+    if (fs.pathExistsSync(gitIgnorePath)) {
+        return;
+    }
+    fs.outputFileSync(gitIgnorePath, ['# Agent skills are installed once at the development-team root and linked here.', '**/.claude/skills', ''].join('\n'));
+}
+/**
+ * Clones one App. The metadata entry is recorded as soon as the directory exists, before the
+ * pull that may fail: a half-cloned App has to be recognised as cloned next time, or the retry
+ * would try to create it again and stop at "already cloned".
+ */
+async function cloneApp(rootDir, app, folder, metadata) {
+    const slug = (0, dev_slug_1.devSlug)(app.id);
+    const appDir = path.join(rootDir, folder);
+    const workspaceDir = path.join(appDir, dev_team_1.APP_WORKSPACE_DIR);
+    cli_1.default.log(color_1.default.cyan(`\n📦 ${app.name} → ${folder}/${dev_team_1.APP_WORKSPACE_DIR} (${slug})`));
+    await (0, workspace_cloner_1.scaffoldWorkspace)(workspaceDir, { url: metadata.cloudUrl, slug });
+    metadata.apps[app.id] = { name: app.name, description: app.description, folder, devWorkspaceSlug: slug };
+    (0, dev_team_1.writeAppSettings)(appDir, { id: app.id, name: app.name, description: app.description });
+    writeAppGitIgnore(appDir);
+    linkSkills(rootDir, appDir, workspaceDir);
+    await (0, workspace_cloner_1.runInWorkspace)(workspaceDir, () => pull_1.default.run([]));
+}
+async function refreshApp(rootDir, cloudUrl, app, recorded) {
+    const appDir = path.join(rootDir, recorded.folder);
+    const workspaceDir = path.join(appDir, dev_team_1.APP_WORKSPACE_DIR);
+    cli_1.default.log(color_1.default.cyan(`\n📦 ${app.name} → ${recorded.folder}/${dev_team_1.APP_WORKSPACE_DIR}`));
+    // A recorded App whose workspace is gone — a failed first clone, or a directory the user
+    // removed — is laid out again rather than failing every pull from here on.
+    if (!fs.pathExistsSync(path.join(workspaceDir, '.fcode'))) {
+        await (0, workspace_cloner_1.scaffoldWorkspace)(workspaceDir, { url: cloudUrl, slug: recorded.devWorkspaceSlug });
+    }
+    // Name and description live in the dashboard; the local copy is a mirror refreshed on every
+    // pull. There is deliberately no team:push — pushing happens inside a workspace.
+    (0, dev_team_1.writeAppSettings)(appDir, { id: app.id, name: app.name, description: app.description });
+    writeAppGitIgnore(appDir);
+    recorded.name = app.name;
+    recorded.description = app.description;
+    linkSkills(rootDir, appDir, workspaceDir);
+    await (0, workspace_cloner_1.runInWorkspace)(workspaceDir, () => pull_1.default.run([]));
+}
+/**
+ * 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.
+ */
+async function syncApps(rootDir, metadata, plan) {
+    const outcomes = [];
+    for (const app of plan.toClone) {
+        const folder = assignFolder(app, metadata);
+        try {
+            await cloneApp(rootDir, app, folder, metadata);
+            outcomes.push({ name: app.name, folder, action: 'cloned' });
+        }
+        catch (error) {
+            outcomes.push({ name: app.name, folder, action: 'cloned', error: error });
+        }
+    }
+    for (const app of plan.toRefresh) {
+        const recorded = metadata.apps[app.id];
+        try {
+            await refreshApp(rootDir, metadata.cloudUrl, app, recorded);
+            outcomes.push({ name: app.name, folder: recorded.folder, action: 'pulled' });
+        }
+        catch (error) {
+            outcomes.push({ name: app.name, folder: recorded.folder, action: 'pulled', error: error });
+        }
+    }
+    return outcomes;
+}
+/** Prints the per-App result and reports whether anything failed. */
+function reportOutcomes(outcomes, removed) {
+    cli_1.default.log('');
+    for (const outcome of outcomes) {
+        if (outcome.error) {
+            cli_1.default.log(color_1.default.red(`❌ ${outcome.folder} — ${outcome.error.message}`));
+        }
+        else {
+            cli_1.default.log(color_1.default.green(`✅ ${outcome.folder} (${outcome.action})`));
+        }
+    }
+    for (const { app } of removed) {
+        cli_1.default.log(color_1.default.yellow(`⚠️  ${app.folder} is no longer in the team — the folder was kept, remove it yourself`));
+    }
+    return outcomes.some(({ error }) => error !== undefined);
+}
+/**
+ * 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.
+ */
+async function resolveTeam(client, teamId) {
+    const teams = await client.listDevelopmentTeams();
+    if (teamId) {
+        const team = teams.find(({ id }) => id === teamId);
+        if (!team) {
+            process.exitCode = 1;
+            cli_1.default.error(`Development team ${teamId} not found, or your session has no access to it`);
+        }
+        return team;
+    }
+    if (teams.length === 0) {
+        cli_1.default.log('ℹ️  Your session belongs to no development team. Ask your team admin to add you.');
+        return undefined;
+    }
+    if (teams.length === 1) {
+        return teams[0];
+    }
+    cli_1.default.log('🏢  Your development teams:\n');
+    for (const team of teams) {
+        cli_1.default.log(`  ${color_1.default.cyan(team.id)}  ${team.name}`);
+    }
+    cli_1.default.log(`\nClone one with ${color_1.default.cyan('fcode team:clone [teamId]')}`);
+    return undefined;
+}

package/dist/services/fcode-graphql-client.d.ts

@@ -1,5 +1,5 @@
 import { GraphQLClient } from 'graphql-request';
-import { Locale, Process, ProgrammingLanguage, ProgrammingLanguageManifest, RawTeamSettings, ScriptLibrary, TeamUpdateInput, TeamVersion, TeamVersionAlias, Variable, VersionedProcess, VersionedScriptLibrary, ServiceAccount } from '../core/types';
+import { Locale, Process, ProgrammingLanguage, ProgrammingLanguageManifest, RawTeamSettings, ScriptLibrary, TeamUpdateInput, TeamVersion, TeamVersionAlias, Variable, VersionedProcess, VersionedProgrammingLanguageManifest, VersionedScriptLibrary, ServiceAccount } from '../core/types';
 export type FcodeGraphQLClientOptions = {
     url: string;
     accessToken: string;
@@ -50,7 +50,7 @@ declare class FcodeGraphQLClient {
     private mapWebhook;
     mapProcess({ id, slug, name, description, tags, script, readme, manifest, settings, triggers, resolvingTeamSlug }: any): Process;
     /**
-     * GraphQL nests the webhook configuration under `settings`, while team.json and the REST API
+     * GraphQL nests the webhook configuration under `settings`, while settings.json and the REST API
      * keep it flat. Mapping it explicitly is what keeps that mismatch from silently reading as
      * undefined.
      */
@@ -68,6 +68,21 @@ declare class FcodeGraphQLClient {
     team(): Promise<RawTeamSettings>;
     pushTeam(update: TeamUpdateInput): Promise<RawTeamSettings>;
     mapProgrammingLanguageManifest(programmingLanguageManifest: any): ProgrammingLanguageManifest;
+    private mapDependencies;
+    /**
+     * The published dependency versions of one language, newest first. An fcode-api that predates
+     * dependency versioning rejects the query over the unknown field; that answers `null` — "the api
+     * cannot say" — so the pull skips versions entirely instead of reconciling (and deleting) local
+     * snapshot folders against an empty list. Only that schema-validation rejection is swallowed: a
+     * runtime failure of the field also mentions its name, and must fail the pull.
+     */
+    allVersionedDependencies(programmingLanguage: ProgrammingLanguage): Promise<Array<VersionedProgrammingLanguageManifest> | null>;
+    /**
+     * Whether the api rejected the query because it does not know {@code field} — as opposed to
+     * knowing it and failing to resolve it, whose message also contains the field name (graphql-java
+     * puts the path into runtime messages: "Exception while fetching data (/field) : ...").
+     */
+    private isUndefinedFieldError;
     allProgrammingLanguageManifest(): Promise<Array<ProgrammingLanguageManifest>>;
     pushProgrammingLanguageManifest(programmingLanguageManifest: ProgrammingLanguageManifest): Promise<ProgrammingLanguageManifest>;
     allServiceAccounts(): Promise<Array<ServiceAccount>>;

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

@@ -4,6 +4,10 @@ const graphql_request_1 = require("graphql-request");
 const types_1 = require("../core/types");
 const locale_merger_1 = require("./locale-merger");
 const _ = require("lodash");
+// Manifest fields an fcode-api older than this CLI may not know. The manifest query falls back to a
+// narrower selection when the error names one of them, so a CLI stays usable against an
+// on-premises api that has not been updated yet.
+const UNKNOWN_MANIFEST_FIELDS = ['isNative', 'inheritedDependencies'];
 // Shared team version selections so every query/mutation returns the same shape.
 const TEAM_VERSION_FIELDS = `
   id
@@ -67,6 +71,13 @@ const PROCESS_FIELDS = `
       appRole
       authMode
     }
+    uiTrigger {
+      enabled
+      locationId
+      label
+      icon
+      awaitResult
+    }
     dependencies {
       scopedToProcess
     }
@@ -351,9 +362,9 @@ class FcodeGraphQLClient {
             return Promise.reject(this.cleanError(error));
         }
         // The cloud team's parent order is the inheritance precedence the merge must replicate; the
-        // local team.json may lag behind it, so the cloud is asked, not the file.
-        const { parentTeamSlugs } = await this.team();
-        const merged = (0, locale_merger_1.mergeInheritedLocales)(locales, parentTeamSlugs ?? []);
+        // local settings.json may lag behind it, so the cloud is asked, not the file.
+        const { parentTeams } = await this.team();
+        const merged = (0, locale_merger_1.mergeInheritedLocales)(locales, (parentTeams ?? []).map(({ slug }) => slug));
         (0, locale_merger_1.assertLocaleFilesCanCoexist)(merged);
         return merged;
     }
@@ -429,6 +440,21 @@ class FcodeGraphQLClient {
                 settings.formSettings.authMode = process.form.authMode;
             }
         }
+        if (process.uiTrigger) {
+            settings.uiTrigger = { enabled: process.uiTrigger.enabled };
+            if (process.uiTrigger.locationId) {
+                settings.uiTrigger.locationId = process.uiTrigger.locationId;
+            }
+            if (process.uiTrigger.label) {
+                settings.uiTrigger.label = process.uiTrigger.label;
+            }
+            if (process.uiTrigger.icon) {
+                settings.uiTrigger.icon = process.uiTrigger.icon;
+            }
+            if (process.uiTrigger.awaitResult !== undefined) {
+                settings.uiTrigger.awaitResult = process.uiTrigger.awaitResult;
+            }
+        }
         const input = {
             name: process.name,
             parametersSchema: process.script.parametersSchema,
@@ -645,6 +671,13 @@ class FcodeGraphQLClient {
                 isNative
                 gitUrl
               }
+              inheritedDependencies {
+                name
+                semVer
+                isNative
+                gitUrl
+                resolvingTeamSlug
+              }
             }
           }
         `, { programmingLanguage })
@@ -654,7 +687,10 @@ class FcodeGraphQLClient {
             .catch((error) => {
             // TODO: This is a workaround backward compatibility with old versions of fcode-api.
             // Remove when full on-premises installations are updated.
-            if (error.response && error.response.errors && error.response.errors[0] && error.response.errors[0].message.includes('isNative')) {
+            // `inheritedDependencies` is listed for the same reason `isNative` is: an api predating
+            // dependency inheritance rejects the whole query over the unknown field, and the fallback
+            // below simply reads no inherited dependencies.
+            if (error.response?.errors?.[0]?.message && UNKNOWN_MANIFEST_FIELDS.some((field) => error.response.errors[0].message.includes(field))) {
                 return this.client
                     .request((0, graphql_request_1.gql) `
                 query getProgrammingLanguageManifest($programmingLanguage: ProgrammingLanguage!) {
@@ -732,10 +768,25 @@ class FcodeGraphQLClient {
                 metadata.form.authMode = settings.formSettings.authMode;
             }
         }
+        if (settings?.uiTrigger) {
+            metadata.uiTrigger = { enabled: Boolean(settings.uiTrigger.enabled) };
+            if (settings.uiTrigger.locationId) {
+                metadata.uiTrigger.locationId = settings.uiTrigger.locationId;
+            }
+            if (settings.uiTrigger.label) {
+                metadata.uiTrigger.label = settings.uiTrigger.label;
+            }
+            if (settings.uiTrigger.icon) {
+                metadata.uiTrigger.icon = settings.uiTrigger.icon;
+            }
+            if (settings.uiTrigger.awaitResult) {
+                metadata.uiTrigger.awaitResult = true;
+            }
+        }
         return new types_1.Process(id, slug, script, readme, { dependencies }, settings, metadata, this.inheritedTeam(resolvingTeamSlug));
     }
     /**
-     * GraphQL nests the webhook configuration under `settings`, while team.json and the REST API
+     * GraphQL nests the webhook configuration under `settings`, while settings.json and the REST API
      * keep it flat. Mapping it explicitly is what keeps that mismatch from silently reading as
      * undefined.
      */
@@ -744,7 +795,7 @@ class FcodeGraphQLClient {
             slug: team.slug,
             zoneId: team.zoneId,
             errorHandlerConfig: team.errorHandlerConfig,
-            parentTeamSlugs: team.parentTeamSlugs ?? [],
+            parentTeams: team.parentTeams ?? [],
         };
         const webhookAuth = team.settings?.webhookAuth;
         if (webhookAuth?.variableKey) {
@@ -896,7 +947,10 @@ class FcodeGraphQLClient {
                 processId
                 tag
               }
-              parentTeamSlugs
+              parentTeams {
+                slug
+                version
+              }
               settings {
                 webhookAuth {
                   headerName
@@ -923,7 +977,10 @@ class FcodeGraphQLClient {
                 processId
                 tag
               }
-              parentTeamSlugs
+              parentTeams {
+                slug
+                version
+              }
               settings {
                 webhookAuth {
                   headerName
@@ -941,15 +998,66 @@ class FcodeGraphQLClient {
     }
     mapProgrammingLanguageManifest(programmingLanguageManifest) {
         const allDependencies = programmingLanguageManifest.nextInstallation?.dependencies || programmingLanguageManifest.dependencies;
-        const dependencies = _.map(allDependencies, (dependency) => {
-            if (!dependency.isNative) {
-                return { name: dependency.name, specifier: dependency.gitUrl ?? dependency.semVer };
+        return new types_1.ProgrammingLanguageManifest(programmingLanguageManifest.id, programmingLanguageManifest.programmingLanguage, programmingLanguageManifest.programmingLanguage, this.mapDependencies(allDependencies), 
+        // Absent when the api predates dependency inheritance, or when the workspace has no parents.
+        this.mapDependencies(programmingLanguageManifest.inheritedDependencies));
+    }
+    mapDependencies(dependencies) {
+        return _.map(dependencies, (dependency) => {
+            if (dependency.isNative) {
+                return null;
             }
-            return null;
+            return {
+                name: dependency.name,
+                specifier: dependency.gitUrl ?? dependency.semVer,
+                ...(dependency.resolvingTeamSlug && { resolvingTeamSlug: dependency.resolvingTeamSlug }),
+            };
         })
             .filter(Boolean)
-            .sort((a, b) => a && b && a.name.localeCompare(b.name));
-        return new types_1.ProgrammingLanguageManifest(programmingLanguageManifest.id, programmingLanguageManifest.programmingLanguage, programmingLanguageManifest.programmingLanguage, dependencies);
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    /**
+     * The published dependency versions of one language, newest first. An fcode-api that predates
+     * dependency versioning rejects the query over the unknown field; that answers `null` — "the api
+     * cannot say" — so the pull skips versions entirely instead of reconciling (and deleting) local
+     * snapshot folders against an empty list. Only that schema-validation rejection is swallowed: a
+     * runtime failure of the field also mentions its name, and must fail the pull.
+     */
+    allVersionedDependencies(programmingLanguage) {
+        return this.client
+            .request((0, graphql_request_1.gql) `
+          query allVersionedDependencies($programmingLanguage: ProgrammingLanguage!) {
+            allVersionedDependencies(programmingLanguage: $programmingLanguage) {
+              tag
+              programmingLanguage
+              dependencies {
+                name
+                semVer
+                isNative
+                gitUrl
+              }
+            }
+          }
+        `, { programmingLanguage })
+            .then(({ allVersionedDependencies }) => allVersionedDependencies.map((versioned) => new types_1.VersionedProgrammingLanguageManifest(versioned.tag, versioned.programmingLanguage, this.mapDependencies(versioned.dependencies))))
+            .catch((error) => {
+            if (this.isUndefinedFieldError(error, 'allVersionedDependencies')) {
+                return null;
+            }
+            return Promise.reject(this.cleanError(error));
+        });
+    }
+    /**
+     * Whether the api rejected the query because it does not know {@code field} — as opposed to
+     * knowing it and failing to resolve it, whose message also contains the field name (graphql-java
+     * puts the path into runtime messages: "Exception while fetching data (/field) : ...").
+     */
+    isUndefinedFieldError(error, field) {
+        const first = error.response?.errors?.[0];
+        if (!first?.message?.includes(field)) {
+            return false;
+        }
+        return first.extensions?.classification === 'ValidationError' || first.message.startsWith('Validation error');
     }
     allProgrammingLanguageManifest() {
         const result = [];
@@ -983,7 +1091,11 @@ class FcodeGraphQLClient {
           }
         `, {
             id: programmingLanguageManifest.id,
-            input: { dependencies: programmingLanguageManifest.dependencies },
+            input: {
+                // Only name and specifier: DependencyUpdateInput has no other fields, and a workspace
+                // pushes its own list — inherited entries live in a separate file and never get here.
+                dependencies: programmingLanguageManifest.dependencies.map(({ name, specifier }) => ({ name, specifier })),
+            },
         })
             .then(({ updateProgrammingLanguageManifest: programmingLanguageManifest }) => {
             return this.client

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

@@ -8,11 +8,27 @@
  * ones, which `pull` writes into the same directory as `<locale>.inherited.yaml`.
  */
 export declare function flattenTranslations(document: unknown, prefix?: string, target?: Record<string, string>): Record<string, string>;
+/**
+ * The locale files that answer a requested identifier, lowest precedence first. Mirrors the
+ * platform's `LocaleFallbackChain`, so a local run and the cloud resolve the same text.
+ *
+ * A viewer's locale is usually a regional variant (`en-gb`, `pt-BR`) while a workspace usually
+ * publishes plain languages, so the request degrades one segment at a time — split on `-` or `_`,
+ * without parsing a language tag, since any short slug is a legal identifier here — and every step
+ * that matches stays in the chain: a variant file translates the keys that differ and leaves the
+ * rest to the language it came from.
+ */
+export declare function localeFallbackChain(requested: string | undefined, primary: string | undefined, available: Array<string>): Array<string>;
 /**
  * @param requestedLocale the locale to run with, or undefined to use the workspace's primary
- * @returns the locale actually used and its flat translations, with the primary locale underneath
+ * @returns the locale actually used and its flat translations, with the primary locale — and any
+ * shorter form of the requested one the workspace publishes — layered underneath, plus each
+ * locale's own map (inherited file layered under its own, but NOT merged over the primary) so a
+ * call naming a locale (`fcode.i18n(key, args, { locale })`) resolves like the cloud's `by_locale`:
+ * key by key in the requested locale first, falling back to the merged translations
  */
 export declare function resolveLocalTranslations(requestedLocale?: string, workspaceDir?: string): {
     locale?: string;
     translations: Record<string, string>;
+    byLocale: Record<string, Record<string, string>>;
 };