@factorialco/fcode-cli 2.4.0 → 3.1.0

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

@@ -0,0 +1,221 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchTeamRemote = fetchTeamRemote;
+exports.planSync = planSync;
+exports.assignFolder = assignFolder;
+exports.syncTeam = syncTeam;
+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");
+async function fetchTeamRemote(client, teamId) {
+    const [apps, globalWorkspaces] = await Promise.all([client.listTeamApps(teamId), client.listTeamGlobalWorkspaces(teamId)]);
+    return { apps, globalWorkspaces };
+}
+function planSync(recorded, remote) {
+    const remoteIds = new Set(remote.map(({ id }) => id));
+    return {
+        toClone: remote.filter(({ id }) => recorded[id] === undefined),
+        toRefresh: remote.filter(({ id }) => recorded[id] !== undefined),
+        removed: Object.entries(recorded)
+            .filter(([id]) => !remoteIds.has(id))
+            .map(([id, entry]) => ({ id, recorded: entry })),
+    };
+}
+/**
+ * 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 keeping the skill links out of the repository: one in each App folder,
+ * since each is meant to become its own repository, and one over the global workspaces.
+ */
+function writeSkillsGitIgnore(dir) {
+    const gitIgnorePath = path.join(dir, '.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 });
+    writeSkillsGitIgnore(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 });
+    writeSkillsGitIgnore(appDir);
+    recorded.name = app.name;
+    recorded.description = app.description;
+    linkSkills(rootDir, appDir, workspaceDir);
+    await (0, workspace_cloner_1.runInWorkspace)(workspaceDir, () => pull_1.default.run([]));
+}
+/**
+ * Clones or refreshes one global workspace. Its slug is the platform team slug — fixed, unique and
+ * filesystem-safe — so the checkout goes straight to `global-workspaces/{slug}` with no folder to
+ * assign and no App-level settings to mirror. Recorded before the pull for the same reason as an
+ * App: a half-cloned checkout must read as cloned on the retry.
+ */
+async function syncGlobalWorkspace(rootDir, workspace, metadata) {
+    const folder = (0, dev_team_1.globalWorkspaceFolder)(workspace.slug);
+    const workspaceDir = path.join(rootDir, folder);
+    cli_1.default.log(color_1.default.cyan(`\n🌐 ${workspace.name} → ${folder}`));
+    if (!fs.pathExistsSync(path.join(workspaceDir, '.fcode'))) {
+        await (0, workspace_cloner_1.scaffoldWorkspace)(workspaceDir, { url: metadata.cloudUrl, slug: workspace.slug });
+    }
+    metadata.globalWorkspaces[workspace.id] = { name: workspace.name, description: workspace.description, slug: workspace.slug };
+    writeSkillsGitIgnore(path.join(rootDir, dev_team_1.GLOBAL_WORKSPACES_DIR));
+    (0, skills_installer_1.linkSkillsInto)(workspaceDir, rootDir);
+    await (0, workspace_cloner_1.runInWorkspace)(workspaceDir, () => pull_1.default.run([]));
+}
+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;
+}
+async function syncGlobalWorkspaces(rootDir, metadata, plan) {
+    const outcomes = [];
+    for (const [action, workspaces] of [
+        ['cloned', plan.toClone],
+        ['pulled', plan.toRefresh],
+    ]) {
+        for (const workspace of workspaces) {
+            const folder = (0, dev_team_1.globalWorkspaceFolder)(workspace.slug);
+            try {
+                await syncGlobalWorkspace(rootDir, workspace, metadata);
+                outcomes.push({ name: workspace.name, folder, action });
+            }
+            catch (error) {
+                outcomes.push({ name: workspace.name, folder, action, error: error });
+            }
+        }
+    }
+    return outcomes;
+}
+/**
+ * Brings the team folder in line with the dashboard — global workspaces first, since the Apps
+ * inherit from them, then the Apps — one workspace at a time, recording the metadata of each one
+ * that lands. A failing workspace is reported and the run carries on: with a dozen Apps, one bad
+ * workspace must not cost the other eleven.
+ */
+async function syncTeam(rootDir, metadata, remote) {
+    const globalWorkspacePlan = planSync(metadata.globalWorkspaces, remote.globalWorkspaces);
+    const appPlan = planSync(metadata.apps, remote.apps);
+    const outcomes = [
+        ...(await syncGlobalWorkspaces(rootDir, metadata, globalWorkspacePlan)),
+        ...(await syncApps(rootDir, metadata, appPlan)),
+    ];
+    const removedFolders = [
+        ...globalWorkspacePlan.removed.map(({ recorded }) => (0, dev_team_1.globalWorkspaceFolder)(recorded.slug)),
+        ...appPlan.removed.map(({ recorded }) => recorded.folder),
+    ];
+    return { outcomes, removedFolders };
+}
+/** Prints the per-workspace result and reports whether anything failed. */
+function reportOutcomes({ outcomes, removedFolders }) {
+    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 folder of removedFolders) {
+        cli_1.default.log(color_1.default.yellow(`⚠️  ${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.
      */
@@ -69,6 +69,20 @@ declare class FcodeGraphQLClient {
     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

@@ -362,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;
     }
@@ -786,7 +786,7 @@ class FcodeGraphQLClient {
         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.
      */
@@ -795,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) {
@@ -947,7 +947,10 @@ class FcodeGraphQLClient {
                 processId
                 tag
               }
-              parentTeamSlugs
+              parentTeams {
+                slug
+                version
+              }
               settings {
                 webhookAuth {
                   headerName
@@ -974,7 +977,10 @@ class FcodeGraphQLClient {
                 processId
                 tag
               }
-              parentTeamSlugs
+              parentTeams {
+                slug
+                version
+              }
               settings {
                 webhookAuth {
                   headerName
@@ -1010,6 +1016,49 @@ class FcodeGraphQLClient {
             .filter(Boolean)
             .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 = [];
         result.push(this.programmingLanguageManifest('JAVASCRIPT'));

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

@@ -8,13 +8,24 @@
  * 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,
- * 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
+ * @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;

package/dist/services/locale-resolver.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.flattenTranslations = flattenTranslations;
+exports.localeFallbackChain = localeFallbackChain;
 exports.resolveLocalTranslations = resolveLocalTranslations;
 const fs = require("fs-extra");
 const path = require("node:path");
@@ -8,6 +9,7 @@ const yaml_1 = require("yaml");
 const cli_1 = require("../utils/cli");
 const color_1 = require("@oclif/color");
 const types_1 = require("../core/types");
+const settings_1 = require("../repositories/settings");
 const I18N_DIRECTORY = 'i18n';
 const YAML_EXTENSION = '.yaml';
 const KEY_SEPARATOR = '.';
@@ -71,8 +73,9 @@ function readLocale(workspaceDir, locale) {
 }
 function chosenPrimaryLocaleOf(workspaceDir) {
     try {
-        const team = fs.readJsonSync(path.join(workspaceDir, 'team.json'));
-        return typeof team?.primaryLocale === 'string' && team.primaryLocale.length > 0 ? team.primaryLocale : undefined;
+        (0, settings_1.migrateLegacySettingsFile)(workspaceDir);
+        const settings = fs.readJsonSync(path.join(workspaceDir, settings_1.SETTINGS_FILENAME));
+        return typeof settings?.primaryLocale === 'string' && settings.primaryLocale.length > 0 ? settings.primaryLocale : undefined;
     }
     catch {
         return undefined;
@@ -95,7 +98,7 @@ function availableLocales(workspaceDir) {
     return [...new Set(localeFileSlugs(workspaceDir).map((slug) => identifierOf(slug)))].sort();
 }
 /**
- * The workspace's primary locale: the one chosen in `team.json`, or its first locale when none is
+ * The workspace's primary locale: the one chosen in `settings.json`, or its first locale when none is
  * chosen — or when the chosen one has no file anymore, which would otherwise resolve zero keys.
  * Mirrors the platform's `PrimaryLocale.resolve`, so a local run and the cloud agree on which
  * locale a process without an explicit one resolves against.
@@ -105,13 +108,55 @@ function primaryLocaleOf(workspaceDir) {
     const chosen = chosenPrimaryLocaleOf(workspaceDir);
     return chosen && available.includes(chosen) ? chosen : available[0];
 }
+/**
+ * The available locale a candidate opens: the one named exactly, or — only when no name matches —
+ * the one that differs from it in case alone, alphabetically first if there are several. Locale
+ * identifiers are case-sensitive, so `pt-BR` and `pt-br` are two files and each keeps answering its
+ * own name; ignoring case only ever rescues a lookup that would otherwise find nothing.
+ */
+function matchingLocale(candidate, available) {
+    if (available.includes(candidate)) {
+        return candidate;
+    }
+    return available.filter((locale) => locale.toLowerCase() === candidate.toLowerCase()).sort()[0];
+}
+/**
+ * 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.
+ */
+function localeFallbackChain(requested, primary, available) {
+    const chain = [];
+    const add = (candidate) => {
+        const match = candidate ? matchingLocale(candidate, available) : undefined;
+        if (match && !chain.includes(match)) {
+            chain.push(match);
+        }
+    };
+    add(primary);
+    const candidates = [];
+    let candidate = requested?.trim();
+    while (candidate) {
+        candidates.unshift(candidate);
+        const lastSeparator = Math.max(candidate.lastIndexOf('-'), candidate.lastIndexOf('_'));
+        candidate = lastSeparator > 0 ? candidate.slice(0, lastSeparator) : undefined;
+    }
+    for (const shorterOrExact of candidates)
+        add(shorterOrExact);
+    return chain;
+}
 /**
  * @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,
- * 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
+ * @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
  */
 function resolveLocalTranslations(requestedLocale, workspaceDir = process.cwd()) {
     const primary = primaryLocaleOf(workspaceDir);
@@ -120,8 +165,11 @@ function resolveLocalTranslations(requestedLocale, workspaceDir = process.cwd())
     if (!locale) {
         return { locale: undefined, translations: {}, byLocale };
     }
-    // `byLocale` already holds every locale's own file, so the merged map — the requested locale
-    // layered over the primary — is derived from it rather than read from disk a second time.
-    const fallback = primary ? byLocale[primary] : {};
-    return { locale, translations: { ...fallback, ...(byLocale[locale] ?? {}) }, byLocale };
+    // `byLocale` already holds every locale's own file, so the merged map — the fallback chain
+    // layered lowest precedence first — is derived from it rather than read from disk a second time.
+    const translations = {};
+    for (const layer of localeFallbackChain(requestedLocale, primary, Object.keys(byLocale))) {
+        Object.assign(translations, byLocale[layer]);
+    }
+    return { locale, translations, byLocale };
 }

package/dist/services/resource-differ.d.ts

@@ -0,0 +1,60 @@
+import { Locale, Process, ProgrammingLanguageManifest, Resource, ResourceStatus, ScriptLibrary, Variable } from '../core/types';
+import { PseudoFile } from '../utils/diff';
+/** Stands in for a variable's value wherever one side declares it sensitive, so no secret is ever printed. */
+export declare const SENSITIVE_PLACEHOLDER = "<sensitive value hidden>";
+export declare const VARIABLES_DIFF_PATH = "variables.env";
+/** What a workspace inherits is regenerated on pull into its own file, which the parent owns. */
+export declare const INHERITED_VARIABLES_DIFF_PATH = "variables.inherited.env";
+export declare const SETTINGS_DIFF_PATH = "settings.json";
+/**
+ * A resource as both sides hold it, kept whole. `ResourceMerger.mergeStatus` collapses the two into
+ * one object and loses the remote body, which is exactly what a diff needs.
+ */
+export type ResourcePair<R extends Resource> = {
+    slug: string;
+    remote?: R;
+    local?: R;
+    status: ResourceStatus;
+};
+/** A set of pseudo-files presented together under one heading (usually one resource). */
+export type DiffSection = {
+    label: string;
+    files: PseudoFile[];
+};
+/** Files keyed by the path they are stored at, for one side of a comparison. */
+type SideFiles = Record<string, string>;
+export declare function pairResources<R extends Resource>(remoteResources: Array<R>, localResources: Array<R>, existsMetadata: (slug: string) => Promise<boolean>): Promise<Array<ResourcePair<R>>>;
+/**
+ * The workspace a resource is inherited from, when it is. An overridden variable resolves to
+ * undefined on its local side, which is what makes an override diffable while the parent's copy
+ * stays read-only.
+ */
+export declare function inheritedFrom<R extends Resource>(pair: ResourcePair<R>): string | undefined;
+/** A process as the four files it is stored as, plus its own dependencies file when it scopes them. */
+export declare function processFiles(process: Process): SideFiles;
+export declare function moduleFiles(module: ScriptLibrary): SideFiles;
+export declare function localeFiles(locale: Locale): SideFiles;
+/**
+ * Only the workspace's own dependencies, matching what `contentHash` covers and what the manifest
+ * file holds: the inherited ones live in their own file and belong to a parent.
+ */
+export declare function manifestFiles(manifest: ProgrammingLanguageManifest): SideFiles;
+export declare const processDiffFiles: (pair: ResourcePair<Process>) => Array<PseudoFile>;
+export declare const moduleDiffFiles: (pair: ResourcePair<ScriptLibrary>) => Array<PseudoFile>;
+export declare const localeDiffFiles: (pair: ResourcePair<Locale>) => Array<PseudoFile>;
+export declare const manifestDiffFiles: (pair: ResourcePair<ProgrammingLanguageManifest>) => Array<PseudoFile>;
+/**
+ * Every variable as the .env files they share, rather than one pseudo-file each: that is how they
+ * are stored, and it keeps a rename or a reordering readable as one patch.
+ *
+ * The workspace's own keys and the inherited ones are separate files, because they are separate
+ * files on disk — a drifted inherited variable is a stale `variables.inherited.env` that a pull
+ * regenerates, not something to push. The inherited file only appears when something is inherited.
+ *
+ * A key either side marks sensitive is rendered as a placeholder on both, so a diff never prints a
+ * secret and a value-only change to a sensitive variable shows up as nothing (its status does).
+ */
+export declare function variablesEnvDiffFiles(pairs: Array<ResourcePair<Variable>>): Array<PseudoFile>;
+/** The singleton workspace settings file. Both sides arrive already serialized by `SettingsRepository.toFile`. */
+export declare function settingsDiffFile(remote: Record<string, any> | undefined, local: Record<string, any> | undefined): PseudoFile;
+export {};