@factorialco/fcode-cli 3.1.0 → 3.3.0

package/dist/services/dashboard-client.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DashboardApiError = void 0;
 exports.dashboardApiUrl = dashboardApiUrl;
 const node_fetch_1 = require("node-fetch");
 const auth_service_1 = require("./auth-service");
@@ -12,6 +13,45 @@ const global_1 = require("../config/global");
  */
 /** Max the dashboard's list endpoints accept (`listQuerySchema`), so a team is one round trip. */
 const PAGE_SIZE = 200;
+/** A non-2xx answer from the dashboard, carrying the RFC 9457 problem details it sent. */
+class DashboardApiError extends Error {
+    constructor(status, path, detail, code) {
+        super(`Dashboard API ${status} on ${path}: ${detail}`);
+        this.status = status;
+        this.path = path;
+        this.detail = detail;
+        this.code = code;
+        this.name = 'DashboardApiError';
+    }
+}
+exports.DashboardApiError = DashboardApiError;
+const appReadmePath = (id) => `/apps/${id}/readme`;
+function mapApp({ id, name, description, publication_state, logo_content_type }) {
+    return { id, name, description, publicationState: publication_state, logoContentType: logo_content_type ?? null };
+}
+function mapMarketplaceMetadata(raw) {
+    return {
+        fullDescription: raw.full_description,
+        tagline: raw.tagline,
+        datoCategoryId: raw.dato_category_id,
+        supportLink: raw.support_link,
+        helpLink: raw.help_link,
+        datocmsId: raw.datocms_id,
+    };
+}
+function mapRelease(raw) {
+    return {
+        id: raw.id,
+        version: raw.version,
+        comments: raw.comments,
+        status: raw.status,
+        error: raw.error,
+        requestedBy: raw.requested_by,
+        deployedAt: raw.deployed_at,
+        stableAt: raw.stable_at,
+        createdAt: raw.created_at,
+    };
+}
 /**
  * `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
@@ -43,7 +83,43 @@ class DashboardClient {
             sort_by: 'name',
             sort_dir: 'asc',
         });
-        return items.map(({ id, name, description }) => ({ id, name, description }));
+        return items.map(mapApp);
+    }
+    async getApp(appId) {
+        return mapApp(await this.request('GET', `/apps/${appId}`));
+    }
+    async getAppReadme(appId) {
+        const { readme } = await this.request('GET', appReadmePath(appId));
+        return { readme: readme ?? null };
+    }
+    async putAppReadme(appId, readme) {
+        const response = await this.request('PUT', appReadmePath(appId), { body: { readme } });
+        return { readme: response.readme ?? null };
+    }
+    async getAppMarketplace(appId) {
+        const { metadata } = await this.request('GET', `/apps/${appId}/marketplace`);
+        return { metadata: metadata ? mapMarketplaceMetadata(metadata) : null };
+    }
+    /** Full replace: every field travels, nulls included, since an absent key clears on the dashboard. */
+    async putAppMarketplace(appId, input) {
+        const raw = await this.request('PUT', `/apps/${appId}/marketplace`, {
+            body: {
+                full_description: input.fullDescription,
+                tagline: input.tagline,
+                dato_category_id: input.datoCategoryId,
+                support_link: input.supportLink,
+                help_link: input.helpLink,
+            },
+        });
+        return mapMarketplaceMetadata(raw);
+    }
+    async listAppReleases(appId) {
+        const items = await this.getAllPages(`/apps/${appId}/releases`);
+        return items.map(mapRelease);
+    }
+    /** The App's logo bytes, or null when it has none. */
+    async getAppLogo(appId) {
+        return this.getBinary(`/apps/${appId}/logo`);
     }
     /** The global workspaces owned by a development team. */
     async listTeamGlobalWorkspaces(teamId) {
@@ -76,32 +152,62 @@ class DashboardClient {
         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() });
+        return this.request('GET', path, { query });
+    }
+    async request(method, path, options = {}) {
+        const response = await this.send(method, path, options);
+        return (await response.json());
+    }
+    async getBinary(path) {
+        try {
+            const response = await this.send('GET', path, { accept: 'image/*' });
+            return { buffer: await response.buffer(), contentType: response.headers.get('content-type') ?? '' };
+        }
+        catch (error) {
+            if (error instanceof DashboardApiError && error.status === 404) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    async send(method, path, { query, body, accept }) {
+        const search = query ? `?${new URLSearchParams(query).toString()}` : '';
+        const url = `${this.baseUrl}${path}${search}`;
+        const init = async () => ({
+            method,
+            headers: await this.headers(accept, body !== undefined),
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        let response = await (0, node_fetch_1.default)(url, await init());
         // 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() });
+                response = await (0, node_fetch_1.default)(url, await init());
             }
         }
         if (!response.ok) {
-            throw new Error(`Dashboard API ${response.status} on ${path}: ${await this.errorDetail(response)}`);
+            const { detail, code } = await this.errorDetail(response);
+            throw new DashboardApiError(response.status, path, detail, code);
         }
-        return (await response.json());
+        return response;
     }
-    async headers() {
+    async headers(accept = 'application/json', withBody = false) {
         const { token } = await this.globalConfig.getAuthInfo(this.cloudUrl);
-        return { accept: 'application/json', authorization: `Bearer ${token.access_token}` };
+        return {
+            accept,
+            authorization: `Bearer ${token.access_token}`,
+            ...(withBody ? { 'content-type': 'application/json' } : {}),
+        };
     }
     async errorDetail(response) {
         try {
             const body = await response.text();
             const parsed = JSON.parse(body);
-            return parsed.detail ?? parsed.message ?? body;
+            return { detail: parsed.detail ?? parsed.message ?? body, code: parsed.code };
         }
         catch {
-            return 'no response body';
+            return { detail: 'no response body' };
         }
     }
 }

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

@@ -1,5 +1,6 @@
 import DashboardClient, { DevelopmentTeam, DevelopmentTeamApp, DevelopmentTeamGlobalWorkspace } from './dashboard-client';
 import { DevTeamMetadata } from '../config/dev-team';
+import { AppMetadataSource } from './app-metadata-files';
 /** What the dashboard currently says the team holds. */
 export interface DevTeamRemote {
     apps: DevelopmentTeamApp[];
@@ -33,6 +34,8 @@ export interface TeamSyncOutcome {
     folder: string;
     action: 'cloned' | 'pulled';
     error?: Error;
+    /** Metadata files kept or not refreshed; reported, never a failure. */
+    warnings?: string[];
 }
 export interface TeamSyncResult {
     outcomes: TeamSyncOutcome[];
@@ -45,7 +48,7 @@ export interface TeamSyncResult {
  * 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.
  */
-export declare function syncTeam(rootDir: string, metadata: DevTeamMetadata, remote: DevTeamRemote): Promise<TeamSyncResult>;
+export declare function syncTeam(rootDir: string, metadata: DevTeamMetadata, remote: DevTeamRemote, source: AppMetadataSource): Promise<TeamSyncResult>;
 /** Prints the per-workspace result and reports whether anything failed. */
 export declare function reportOutcomes({ outcomes, removedFolders }: TeamSyncResult): boolean;
 /**

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

@@ -11,6 +11,7 @@ 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 app_metadata_files_1 = require("./app-metadata-files");
 const skills_installer_1 = require("./skills-installer");
 const dev_slug_1 = require("../utils/dev-slug");
 const workspace_cloner_1 = require("./workspace-cloner");
@@ -61,34 +62,39 @@ function writeSkillsGitIgnore(dir) {
     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".
+ * Metadata warnings go into the caller's sink rather than the return value: the workspace pull
+ * that follows may throw, and what was said about the files before that still holds.
  */
-async function cloneApp(rootDir, app, folder, metadata) {
+async function cloneApp(context, app, folder, warnings) {
+    const { rootDir, metadata, source } = context;
     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 };
+    const recorded = { name: app.name, description: app.description, folder, devWorkspaceSlug: slug };
+    metadata.apps[app.id] = recorded;
     (0, dev_team_1.writeAppSettings)(appDir, { id: app.id, name: app.name, description: app.description });
+    warnings.push(...(await (0, app_metadata_files_1.syncAppMetadata)(source, appDir, app, recorded)).warnings);
     writeSkillsGitIgnore(appDir);
     linkSkills(rootDir, appDir, workspaceDir);
     await (0, workspace_cloner_1.runInWorkspace)(workspaceDir, () => pull_1.default.run([]));
 }
-async function refreshApp(rootDir, cloudUrl, app, recorded) {
+async function refreshApp(context, app, recorded, warnings) {
+    const { rootDir, metadata, source } = context;
     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 });
+        await (0, workspace_cloner_1.scaffoldWorkspace)(workspaceDir, { url: metadata.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.
+    // pull. There is deliberately no team:push — code is pushed inside a workspace, and the App's
+    // README.md / MARKETPLACE.md with `fcode app:push`.
     (0, dev_team_1.writeAppSettings)(appDir, { id: app.id, name: app.name, description: app.description });
+    warnings.push(...(await (0, app_metadata_files_1.syncAppMetadata)(source, appDir, app, recorded)).warnings);
     writeSkillsGitIgnore(appDir);
     recorded.name = app.name;
     recorded.description = app.description;
@@ -113,27 +119,32 @@ async function syncGlobalWorkspace(rootDir, workspace, metadata) {
     (0, skills_installer_1.linkSkillsInto)(workspaceDir, rootDir);
     await (0, workspace_cloner_1.runInWorkspace)(workspaceDir, () => pull_1.default.run([]));
 }
-async function syncApps(rootDir, metadata, plan) {
+async function syncApps(rootDir, metadata, plan, source) {
     const outcomes = [];
+    const context = { rootDir, metadata, source };
     for (const app of plan.toClone) {
         const folder = assignFolder(app, metadata);
+        const warnings = [];
+        const outcome = { name: app.name, folder, action: 'cloned', warnings };
         try {
-            await cloneApp(rootDir, app, folder, metadata);
-            outcomes.push({ name: app.name, folder, action: 'cloned' });
+            await cloneApp(context, app, folder, warnings);
         }
         catch (error) {
-            outcomes.push({ name: app.name, folder, action: 'cloned', error: error });
+            outcome.error = error;
         }
+        outcomes.push(outcome);
     }
     for (const app of plan.toRefresh) {
         const recorded = metadata.apps[app.id];
+        const warnings = [];
+        const outcome = { name: app.name, folder: recorded.folder, action: 'pulled', warnings };
         try {
-            await refreshApp(rootDir, metadata.cloudUrl, app, recorded);
-            outcomes.push({ name: app.name, folder: recorded.folder, action: 'pulled' });
+            await refreshApp(context, app, recorded, warnings);
         }
         catch (error) {
-            outcomes.push({ name: app.name, folder: recorded.folder, action: 'pulled', error: error });
+            outcome.error = error;
         }
+        outcomes.push(outcome);
     }
     return outcomes;
 }
@@ -162,12 +173,12 @@ async function syncGlobalWorkspaces(rootDir, metadata, plan) {
  * 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) {
+async function syncTeam(rootDir, metadata, remote, source) {
     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)),
+        ...(await syncApps(rootDir, metadata, appPlan, source)),
     ];
     const removedFolders = [
         ...globalWorkspacePlan.removed.map(({ recorded }) => (0, dev_team_1.globalWorkspaceFolder)(recorded.slug)),
@@ -185,6 +196,9 @@ function reportOutcomes({ outcomes, removedFolders }) {
         else {
             cli_1.default.log(color_1.default.green(`✅ ${outcome.folder} (${outcome.action})`));
         }
+        for (const warning of outcome.warnings ?? []) {
+            cli_1.default.log(color_1.default.yellow(`   ⚠️  ${warning}`));
+        }
     }
     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`));

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

@@ -1,5 +1,14 @@
 import { GraphQLClient } from 'graphql-request';
 import { Locale, Process, ProgrammingLanguage, ProgrammingLanguageManifest, RawTeamSettings, ScriptLibrary, TeamUpdateInput, TeamVersion, TeamVersionAlias, Variable, VersionedProcess, VersionedProgrammingLanguageManifest, VersionedScriptLibrary, ServiceAccount } from '../core/types';
+/**
+ * What a delete mutation answers. `deletedAt` is set when the entity was kept as deleted because a
+ * workspace version still contains it; `retainingVersionTags` names those versions.
+ */
+export interface RemovedResource {
+    id: string;
+    deletedAt: string | null;
+    retainingVersionTags: string[];
+}
 export type FcodeGraphQLClientOptions = {
     url: string;
     accessToken: string;
@@ -16,10 +25,17 @@ declare class FcodeGraphQLClient {
     cleanError(error: any): any;
     private cloudUnavailableMessage;
     private isNetworkError;
-    allProcesses(): Promise<Array<Process>>;
+    /**
+     * Every process of the workspace, the deleted ones a workspace version still contains included:
+     * they are pulled read-only with their versions, so the local copy keeps what the versions run.
+     * An api that predates deleted-marked processes rejects the query over the unknown field, and
+     * the fallback lists the live ones as it always did.
+     */
+    allProcesses(includeDeleted?: boolean): Promise<Array<Process>>;
     allVersionedProcesses(processId: string): Promise<Array<VersionedProcess>>;
     createVersionedProcesses(versionedProcess: VersionedProcess): Promise<void>;
-    allScriptLibraries(): Promise<Array<ScriptLibrary>>;
+    /** Same deleted-inclusive listing, and the same fallback, as {@link allProcesses}. */
+    allScriptLibraries(includeDeleted?: boolean): Promise<Array<ScriptLibrary>>;
     allVersionedScriptLibraries(scriptLibraryId: string): Promise<Array<VersionedScriptLibrary>>;
     createVersionedScriptLibrary(versionedScriptLibrary: VersionedScriptLibrary): Promise<void>;
     allVariables(): Promise<Array<Variable>>;
@@ -29,26 +45,29 @@ declare class FcodeGraphQLClient {
      * kept twice here — an override is layered over the parent's file key by key, so the parent's
      * keys are still what the ones it does not mention resolve to.
      */
-    allLocales(): Promise<Array<Locale>>;
+    allLocales(includeDeleted?: boolean): Promise<Array<Locale>>;
+    private fetchLocales;
     pushLocale(locale: Locale): Promise<Locale>;
     updateLocale(locale: Locale): Promise<Locale>;
-    removeLocale(locale: string | undefined): Promise<void>;
+    removeLocale(locale: string | undefined): Promise<RemovedResource>;
     private toProcessInput;
     pushProcess(process: Process): Promise<Process>;
-    removeProcess(id: String | undefined): Promise<Process>;
+    removeProcess(id: String | undefined): Promise<RemovedResource>;
     pushScriptLibrary(scriptLibrary: ScriptLibrary): Promise<ScriptLibrary>;
-    removeScriptLibrary(id: String | undefined): Promise<Process>;
+    removeScriptLibrary(id: String | undefined): Promise<RemovedResource>;
     pushVariable(variable: Variable): Promise<Variable>;
     updateVariable(variable: Variable): Promise<Variable>;
     removeVariable(id: String | undefined): Promise<Process>;
     programmingLanguageManifest(programmingLanguage: ProgrammingLanguage): Promise<ProgrammingLanguageManifest>;
     private inheritedTeam;
+    private deletionOf;
+    private isUndefinedDeletionFieldError;
     /**
      * The public mode and the default header name are left out, so a public webhook — or one
      * using the default header — keeps the metadata.json it already had on disk.
      */
     private mapWebhook;
-    mapProcess({ id, slug, name, description, tags, script, readme, manifest, settings, triggers, resolvingTeamSlug }: any): Process;
+    mapProcess({ id, slug, name, description, tags, script, readme, manifest, settings, triggers, resolvingTeamSlug, deletedAt, retainingVersionTags }: any): Process;
     /**
      * 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

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

@@ -33,6 +33,13 @@ const TEAM_VERSION_ALIAS_FIELDS = `
   createdAt
   updatedAt
 `;
+// What a list query adds to know a deleted resource a workspace version still contains. Asked
+// for together with `includeDeleted`, and dropped as one when the api predates them.
+const DELETION_FIELDS = `
+  deletedAt
+  retainingVersionTags
+`;
+const DELETION_QUERY_FIELDS = ['includeDeleted', 'deletedAt', 'retainingVersionTags'];
 // Shared process selection so pull queries and push mutations return the same
 // fields, keeping mapProcess (and therefore contentHash) consistent.
 const PROCESS_FIELDS = `
@@ -154,24 +161,35 @@ class FcodeGraphQLClient {
         const message = typeof error?.message === 'string' ? error.message : '';
         return NETWORK_ERROR_CODES.some((code) => message.includes(code)) || message.includes('fetch failed');
     }
-    allProcesses() {
+    /**
+     * Every process of the workspace, the deleted ones a workspace version still contains included:
+     * they are pulled read-only with their versions, so the local copy keeps what the versions run.
+     * An api that predates deleted-marked processes rejects the query over the unknown field, and
+     * the fallback lists the live ones as it always did.
+     */
+    allProcesses(includeDeleted = true) {
         return this.client
             .request((0, graphql_request_1.gql) `
-          query processes($first: Int!, $after: String) {
-            processes(first: $first, after: $after) {
+          query processes($filter: ProcessesFilter, $first: Int!, $after: String) {
+            processes(filter: $filter, first: $first, after: $after) {
               edges {
                 node {
                   ${PROCESS_FIELDS}
+                  ${includeDeleted ? DELETION_FIELDS : ''}
                 }
               }
             }
           }
         `, {
+            filter: includeDeleted ? { includeDeleted: true } : null,
             after: null,
             first: 200,
         })
             .then(({ processes: { edges } }) => edges.map(({ node: process }) => this.mapProcess(process)))
             .catch((error) => {
+            if (includeDeleted && this.isUndefinedDeletionFieldError(error)) {
+                return this.allProcesses(false);
+            }
             return Promise.reject(this.cleanError(error));
         });
     }
@@ -217,11 +235,12 @@ class FcodeGraphQLClient {
             return Promise.reject(this.cleanError(error));
         });
     }
-    allScriptLibraries() {
+    /** Same deleted-inclusive listing, and the same fallback, as {@link allProcesses}. */
+    allScriptLibraries(includeDeleted = true) {
         return this.client
             .request((0, graphql_request_1.gql) `
-          query scriptLibraries($first: Int!, $after: String) {
-            scriptLibraries(first: $first, after: $after) {
+          query scriptLibraries($filter: ScriptLibrariesFilter, $first: Int!, $after: String) {
+            scriptLibraries(filter: $filter, first: $first, after: $after) {
               edges {
                 node {
                   id
@@ -229,16 +248,21 @@ class FcodeGraphQLClient {
                   sourceCode
                   programmingLanguage
                   resolvingTeamSlug
+                  ${includeDeleted ? DELETION_FIELDS : ''}
                 }
               }
             }
           }
         `, {
+            filter: includeDeleted ? { includeDeleted: true } : null,
             after: null,
             first: 200,
         })
-            .then(({ scriptLibraries: { edges } }) => edges.map(({ node: { id, name, programmingLanguage, sourceCode, resolvingTeamSlug } }) => new types_1.ScriptLibrary(id, name, sourceCode || '', programmingLanguage, this.inheritedTeam(resolvingTeamSlug))))
+            .then(({ scriptLibraries: { edges } }) => edges.map(({ node: { id, name, programmingLanguage, sourceCode, resolvingTeamSlug, deletedAt, retainingVersionTags } }) => new types_1.ScriptLibrary(id, name, sourceCode || '', programmingLanguage, this.inheritedTeam(resolvingTeamSlug), this.deletionOf(deletedAt, retainingVersionTags))))
             .catch((error) => {
+            if (includeDeleted && this.isUndefinedDeletionFieldError(error)) {
+                return this.allScriptLibraries(false);
+            }
             return Promise.reject(this.cleanError(error));
         });
     }
@@ -325,40 +349,16 @@ class FcodeGraphQLClient {
      * kept twice here — an override is layered over the parent's file key by key, so the parent's
      * keys are still what the ones it does not mention resolve to.
      */
-    async allLocales() {
-        const pageSize = 200;
-        const locales = [];
-        let after = null;
+    async allLocales(includeDeleted = true) {
+        let locales;
         try {
-            do {
-                const { locales: { edges, pageInfo }, } = await this.client.request((0, graphql_request_1.gql) `
-            query locales($first: Int!, $after: String) {
-              locales(first: $first, after: $after) {
-                edges {
-                  node {
-                    id
-                    locale
-                    content
-                    resolvingTeamSlug
-                  }
-                }
-                pageInfo {
-                  hasNextPage
-                  endCursor
-                }
-              }
-            }
-          `, {
-                    after,
-                    first: pageSize,
-                });
-                for (const { node: { id, locale, content, resolvingTeamSlug }, } of edges) {
-                    locales.push(new types_1.Locale(id, locale, content, this.inheritedTeam(resolvingTeamSlug)));
-                }
-                after = pageInfo?.hasNextPage ? pageInfo.endCursor : null;
-            } while (after);
+            locales = await this.fetchLocales(includeDeleted);
         }
         catch (error) {
+            // Same fallback as allProcesses: an api that predates deleted-marked locales lists the live ones.
+            if (includeDeleted && this.isUndefinedDeletionFieldError(error)) {
+                return this.allLocales(false);
+            }
             return Promise.reject(this.cleanError(error));
         }
         // The cloud team's parent order is the inheritance precedence the merge must replicate; the
@@ -368,6 +368,41 @@ class FcodeGraphQLClient {
         (0, locale_merger_1.assertLocaleFilesCanCoexist)(merged);
         return merged;
     }
+    async fetchLocales(includeDeleted) {
+        const pageSize = 200;
+        const locales = [];
+        let after = null;
+        do {
+            const { locales: { edges, pageInfo }, } = await this.client.request((0, graphql_request_1.gql) `
+          query locales($filter: LocalesFilter, $first: Int!, $after: String) {
+            locales(filter: $filter, first: $first, after: $after) {
+              edges {
+                node {
+                  id
+                  locale
+                  content
+                  resolvingTeamSlug
+                  ${includeDeleted ? DELETION_FIELDS : ''}
+                }
+              }
+              pageInfo {
+                hasNextPage
+                endCursor
+              }
+            }
+          }
+        `, {
+                filter: includeDeleted ? { includeDeleted: true } : null,
+                after,
+                first: pageSize,
+            });
+            for (const { node: { id, locale, content, resolvingTeamSlug, deletedAt, retainingVersionTags }, } of edges) {
+                locales.push(new types_1.Locale(id, locale, content, this.inheritedTeam(resolvingTeamSlug), this.deletionOf(deletedAt, retainingVersionTags)));
+            }
+            after = pageInfo?.hasNextPage ? pageInfo.endCursor : null;
+        } while (after);
+        return locales;
+    }
     pushLocale(locale) {
         return this.client
             .request((0, graphql_request_1.gql) `
@@ -417,12 +452,14 @@ class FcodeGraphQLClient {
           mutation deleteLocale($locale: String!) {
             deleteLocale(locale: $locale) {
               id
+              deletedAt
+              retainingVersionTags
             }
           }
         `, {
             locale,
         })
-            .then(() => undefined)
+            .then((data) => data.deleteLocale)
             .catch((error) => {
             return Promise.reject(this.cleanError(error));
         });
@@ -531,11 +568,14 @@ class FcodeGraphQLClient {
           mutation deleteProcess($id: ID!) {
             deleteProcess(id: $id) {
               id
+              deletedAt
+              retainingVersionTags
             }
           }
         `, {
             id,
         })
+            .then((data) => data.deleteProcess)
             .catch((error) => {
             return Promise.reject(this.cleanError(error));
         });
@@ -590,11 +630,14 @@ class FcodeGraphQLClient {
           mutation deleteScriptLibrary($id: ID!) {
             deleteScriptLibrary(id: $id) {
               id
+              deletedAt
+              retainingVersionTags
             }
           }
         `, {
             id,
         })
+            .then((data) => data.deleteScriptLibrary)
             .catch((error) => {
             return Promise.reject(this.cleanError(error));
         });
@@ -725,6 +768,12 @@ class FcodeGraphQLClient {
     inheritedTeam(resolvingTeamSlug) {
         return resolvingTeamSlug && resolvingTeamSlug !== this.teamSlug ? resolvingTeamSlug : undefined;
     }
+    deletionOf(deletedAt, retainingVersionTags) {
+        return deletedAt ? { deletedAt, retainingVersionTags: retainingVersionTags ?? [] } : undefined;
+    }
+    isUndefinedDeletionFieldError(error) {
+        return DELETION_QUERY_FIELDS.some((field) => this.isUndefinedFieldError(error, field));
+    }
     /**
      * The public mode and the default header name are left out, so a public webhook — or one
      * using the default header — keeps the metadata.json it already had on disk.
@@ -747,7 +796,7 @@ class FcodeGraphQLClient {
         }
         return webhook;
     }
-    mapProcess({ id, slug, name, description, tags, script, readme, manifest, settings, triggers, resolvingTeamSlug }) {
+    mapProcess({ id, slug, name, description, tags, script, readme, manifest, settings, triggers, resolvingTeamSlug, deletedAt, retainingVersionTags }) {
         const dependencies = _.map(manifest?.dependencies, (dependency) => {
             return { name: dependency.name, specifier: dependency.gitUrl ?? dependency.semVer };
         });
@@ -783,7 +832,7 @@ class FcodeGraphQLClient {
                 metadata.uiTrigger.awaitResult = true;
             }
         }
-        return new types_1.Process(id, slug, script, readme, { dependencies }, settings, metadata, this.inheritedTeam(resolvingTeamSlug));
+        return new types_1.Process(id, slug, script, readme, { dependencies }, settings, metadata, this.inheritedTeam(resolvingTeamSlug), this.deletionOf(deletedAt, retainingVersionTags));
     }
     /**
      * GraphQL nests the webhook configuration under `settings`, while settings.json and the REST API

package/dist/services/skills-installer.js

@@ -3,9 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.installSkillsAt = installSkillsAt;
 exports.skillsInstalledAt = skillsInstalledAt;
 exports.linkSkillsInto = linkSkillsInto;
-const node_child_process_1 = require("node:child_process");
 const fs = require("fs-extra");
 const path = require("node:path");
+const child_process_1 = require("../utils/child-process");
 const cli_1 = require("../utils/cli");
 // Skill sources installed on clone. `release-sdk` in factorial-api-sdks is a
 // maintainer-only skill, so we pick `factorial-api-sdks` explicitly there.
@@ -24,7 +24,7 @@ async function installSkills(repo, skills, cwd) {
     // the skills CLI defaults: project scope (no -g), symlinked (no --copy).
     const skillsArgs = ['--yes', 'skills', 'add', repo, '-s', skills, '-y'];
     await new Promise((resolve) => {
-        const child = (0, node_child_process_1.spawn)('npx', skillsArgs, { cwd, stdio: 'inherit' });
+        const child = (0, child_process_1.spawnCommand)('npx', skillsArgs, { cwd, stdio: 'inherit' });
         child.on('error', () => {
             // npx not available (or failed to launch) — don't fail the clone, just tell the user how to do it.
             cli_1.default.log("\n⚠️  Couldn't run npx automatically (is Node.js / npx installed?).");