figmanage 1.3.0 → 1.3.1

package/dist/cli/permissions.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { getPermissions, setPermissions, share, revokeAccess, listRoleRequests, approveRoleRequest, denyRoleRequest, } from '../operations/permissions.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requireCookie } from './helpers.js';
 export function permissionsCommand() {
     const permissions = new Command('permissions')
@@ -19,7 +20,7 @@ export function permissionsCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -39,7 +40,7 @@ export function permissionsCommand() {
             output({ message: msg }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -60,7 +61,7 @@ export function permissionsCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -71,6 +72,11 @@ export function permissionsCommand() {
         .action(async (resourceType, resourceId, userId, options) => {
         try {
             const config = requireCookie();
+            const { confirmAction } = await import('./helpers.js');
+            if (!await confirmAction(`Revoke ${userId}'s access to ${resourceType} ${resourceId}?`)) {
+                console.log('Cancelled.');
+                return;
+            }
             const msg = await revokeAccess(config, {
                 resource_type: resourceType,
                 resource_id: resourceId,
@@ -79,7 +85,7 @@ export function permissionsCommand() {
             output({ message: msg }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -94,7 +100,7 @@ export function permissionsCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -109,7 +115,7 @@ export function permissionsCommand() {
             output({ message: msg }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -124,7 +130,7 @@ export function permissionsCommand() {
             output({ message: msg }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });

package/dist/cli/projects.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { createProject, renameProject, moveProject, trashProject, restoreProject, setProjectDescription, } from '../operations/projects.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requireCookie } from './helpers.js';
 export function projectsCommand() {
     const projects = new Command('projects')
@@ -17,7 +18,7 @@ export function projectsCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -33,7 +34,7 @@ export function projectsCommand() {
             output({ renamed: projectId, name: options.name }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -52,7 +53,7 @@ export function projectsCommand() {
             output({ moved: projectId, destination_team_id: options.destination }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -63,11 +64,16 @@ export function projectsCommand() {
         .action(async (projectId, options) => {
         try {
             const config = requireCookie();
+            const { confirmAction } = await import('./helpers.js');
+            if (!await confirmAction(`Trash project ${projectId} and all its files?`)) {
+                console.log('Cancelled.');
+                return;
+            }
             await trashProject(config, { project_id: projectId });
             output({ trashed: projectId }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -82,7 +88,7 @@ export function projectsCommand() {
             output({ restored: projectId }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -101,7 +107,7 @@ export function projectsCommand() {
             output({ updated: projectId }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });

package/dist/cli/reading.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { getFile, getNodes } from '../operations/reading.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requirePat } from './helpers.js';
 export function readingCommand() {
     const reading = new Command('reading')
@@ -22,7 +23,7 @@ export function readingCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -42,7 +43,7 @@ export function readingCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });

package/dist/cli/teams.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { createTeam, renameTeam, deleteTeam } from '../operations/teams.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requireCookie } from './helpers.js';
 export function teamsCommand() {
     const teams = new Command('teams')
@@ -17,7 +18,7 @@ export function teamsCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -32,7 +33,7 @@ export function teamsCommand() {
             output({ message: msg }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -43,11 +44,16 @@ export function teamsCommand() {
         .action(async (teamId, options) => {
         try {
             const config = requireCookie();
+            const { confirmAction } = await import('./helpers.js');
+            if (!await confirmAction(`Permanently delete team ${teamId}? All projects and files will be lost.`)) {
+                console.log('Cancelled.');
+                return;
+            }
             const msg = await deleteTeam(config, { team_id: teamId });
             output({ message: msg }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });

package/dist/cli/variables.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { listLocalVariables, listPublishedVariables, updateVariables, isEnterpriseScopeError, ENTERPRISE_ERROR, } from '../operations/variables.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requirePat } from './helpers.js';
 export function variablesCommand() {
     const variables = new Command('variables')
@@ -13,6 +14,10 @@ export function variablesCommand() {
         try {
             const config = requirePat();
             const result = await listLocalVariables(config, { file_key: fileKey });
+            if (Object.keys(result.variables ?? {}).length === 0 && Object.keys(result.variableCollections ?? {}).length === 0) {
+                console.log('No variables found.');
+                return;
+            }
             output(result, options);
         }
         catch (e) {
@@ -20,7 +25,7 @@ export function variablesCommand() {
                 error(ENTERPRISE_ERROR);
             }
             else {
-                error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+                error(formatApiError(e));
             }
             process.exit(1);
         }
@@ -33,6 +38,10 @@ export function variablesCommand() {
         try {
             const config = requirePat();
             const result = await listPublishedVariables(config, { file_key: fileKey });
+            if (Object.keys(result.variables ?? {}).length === 0 && Object.keys(result.variableCollections ?? {}).length === 0) {
+                console.log('No published variables found.');
+                return;
+            }
             output(result, options);
         }
         catch (e) {
@@ -40,7 +49,7 @@ export function variablesCommand() {
                 error(ENTERPRISE_ERROR);
             }
             else {
-                error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+                error(formatApiError(e));
             }
             process.exit(1);
         }
@@ -56,12 +65,25 @@ export function variablesCommand() {
         .action(async (fileKey, options) => {
         try {
             const config = requirePat();
+            const variableCollections = options.variableCollections ? JSON.parse(options.variableCollections) : undefined;
+            const variableModes = options.variableModes ? JSON.parse(options.variableModes) : undefined;
+            const variables = options.variables ? JSON.parse(options.variables) : undefined;
+            const variableModeValues = options.variableModeValues ? JSON.parse(options.variableModeValues) : undefined;
+            const allOps = [...(variables || []), ...(variableCollections || []), ...(variableModes || []), ...(variableModeValues || [])];
+            const hasDeletes = allOps.some((op) => op.action === 'DELETE');
+            if (hasDeletes) {
+                const { confirmAction } = await import('./helpers.js');
+                if (!await confirmAction('This includes DELETE operations that cannot be undone. Continue?')) {
+                    console.log('Cancelled.');
+                    return;
+                }
+            }
             const result = await updateVariables(config, {
                 file_key: fileKey,
-                variable_collections: options.variableCollections ? JSON.parse(options.variableCollections) : undefined,
-                variable_modes: options.variableModes ? JSON.parse(options.variableModes) : undefined,
-                variables: options.variables ? JSON.parse(options.variables) : undefined,
-                variable_mode_values: options.variableModeValues ? JSON.parse(options.variableModeValues) : undefined,
+                variable_collections: variableCollections,
+                variable_modes: variableModes,
+                variables: variables,
+                variable_mode_values: variableModeValues,
             });
             output(result, options);
         }
@@ -70,7 +92,7 @@ export function variablesCommand() {
                 error(ENTERPRISE_ERROR);
             }
             else {
-                error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+                error(formatApiError(e));
             }
             process.exit(1);
         }

package/dist/cli/versions.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { listVersions, createVersion } from '../operations/versions.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requirePat, requireCookie } from './helpers.js';
 export function versionsCommand() {
     const versions = new Command('versions')
@@ -16,7 +17,7 @@ export function versionsCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -37,7 +38,7 @@ export function versionsCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });

package/dist/cli/webhooks.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { listWebhooks, createWebhook, updateWebhook, deleteWebhook, } from '../operations/webhooks.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requirePat } from './helpers.js';
 const VALID_EVENT_TYPES = [
     'FILE_UPDATE',
@@ -21,10 +22,14 @@ export function webhooksCommand() {
         try {
             const config = requirePat();
             const result = await listWebhooks(config, { team_id: teamId });
+            if (result.webhooks.length === 0) {
+                console.log('No webhooks found.');
+                return;
+            }
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -49,7 +54,7 @@ export function webhooksCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -76,7 +81,7 @@ export function webhooksCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -87,11 +92,16 @@ export function webhooksCommand() {
         .action(async (webhookId, options) => {
         try {
             const config = requirePat();
+            const { confirmAction } = await import('./helpers.js');
+            if (!await confirmAction(`Delete webhook ${webhookId}?`)) {
+                console.log('Cancelled.');
+                return;
+            }
             await deleteWebhook(config, { webhook_id: webhookId });
             output({ deleted: webhookId }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });

package/dist/helpers.d.ts

@@ -0,0 +1,11 @@
+import type { AuthConfig } from './auth/client.js';
+/**
+ * Extract actionable error info from Figma API errors.
+ * Includes response body when available, maps common status codes.
+ */
+export declare function formatApiError(e: any): string;
+/** Resolve an org ID from explicit param or config. Returns undefined if neither set. */
+export declare function resolveOrgId(config: AuthConfig, explicit?: string): string | undefined;
+/** Require an org ID, throwing with guidance if missing. */
+export declare function requireOrgId(config: AuthConfig, explicit?: string): string;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/helpers.js

@@ -0,0 +1,41 @@
+/**
+ * Extract actionable error info from Figma API errors.
+ * Includes response body when available, maps common status codes.
+ */
+export function formatApiError(e) {
+    const status = e.response?.status;
+    if (!status)
+        return e.message || 'Unknown error';
+    const body = e.response?.data;
+    const detail = typeof body === 'string'
+        ? body
+        : body?.message || body?.err || body?.error || '';
+    const statusMessages = {
+        400: 'Bad request',
+        401: 'Authentication expired or invalid. Re-run setup.',
+        403: 'Insufficient permissions for this action',
+        404: 'Resource not found. Check the ID.',
+        409: 'Conflict -- resource may already exist or be in use',
+        429: 'Rate limited. Try again in a moment.',
+        500: 'Figma server error. Try again later.',
+    };
+    const base = statusMessages[status] || `HTTP ${status}`;
+    return detail ? `${base}: ${detail}` : base;
+}
+/** Resolve an org ID from explicit param or config. Returns undefined if neither set. */
+export function resolveOrgId(config, explicit) {
+    const id = explicit || config.orgId;
+    if (id && !/^[\w.:-]+$/.test(id))
+        throw new Error('Invalid org ID format');
+    return id;
+}
+/** Require an org ID, throwing with guidance if missing. */
+export function requireOrgId(config, explicit) {
+    const id = explicit || config.orgId;
+    if (!id)
+        throw new Error('Org context required. Run list_orgs to see available workspaces, or set FIGMA_ORG_ID.');
+    if (!/^[\w.:-]+$/.test(id))
+        throw new Error('Invalid org ID format');
+    return id;
+}
+//# sourceMappingURL=helpers.js.map

package/dist/operations/analytics.js

@@ -1,5 +1,5 @@
 import { internalClient } from '../clients/internal-api.js';
-import { requireOrgId } from '../tools/register.js';
+import { requireOrgId } from '../helpers.js';
 export async function libraryUsage(config, params) {
     const lookback = params.days ?? 30;
     const end_ts = Math.floor(Date.now() / 1000);

package/dist/operations/components.d.ts

@@ -1,10 +1,16 @@
 import type { AuthConfig } from '../auth/client.js';
 export declare function listFileComponents(config: AuthConfig, params: {
     file_key: string;
-}): Promise<any[]>;
+}): Promise<{
+    count: number;
+    components: any[];
+}>;
 export declare function listFileStyles(config: AuthConfig, params: {
     file_key: string;
-}): Promise<any[]>;
+}): Promise<{
+    count: number;
+    styles: any[];
+}>;
 export declare function listTeamComponents(config: AuthConfig, params: {
     team_id: string;
     page_size?: number;

package/dist/operations/components.js

@@ -1,11 +1,13 @@
 import { publicClient } from '../clients/public-api.js';
 export async function listFileComponents(config, params) {
     const res = await publicClient(config).get(`/v1/files/${params.file_key}/components`);
-    return res.data?.meta?.components || [];
+    const components = res.data?.meta?.components || [];
+    return { count: components.length, components };
 }
 export async function listFileStyles(config, params) {
     const res = await publicClient(config).get(`/v1/files/${params.file_key}/styles`);
-    return res.data?.meta?.styles || [];
+    const styles = res.data?.meta?.styles || [];
+    return { count: styles.length, styles };
 }
 export async function listTeamComponents(config, params) {
     const queryParams = { page_size: params.page_size ?? 30 };

package/dist/operations/compound-manager.js

@@ -1,5 +1,5 @@
 import { internalClient } from '../clients/internal-api.js';
-import { requireOrgId } from '../tools/register.js';
+import { requireOrgId, formatApiError } from '../helpers.js';
 import { levelName } from './compound.js';
 // -- Shared helpers --
 const BATCH_SIZE = 5;
@@ -241,7 +241,7 @@ export async function offboardUser(config, params) {
                 actions.push({ action: 'transfer_ownership', status: 'done', detail: `${file.file_name} -> ${transfer_to}` });
             }
             catch (e) {
-                actions.push({ action: 'transfer_ownership', status: 'failed', detail: `${file.file_name}: ${e.response?.status || e.message}` });
+                actions.push({ action: 'transfer_ownership', status: 'failed', detail: `${file.file_name}: ${formatApiError(e)}` });
             }
         }
     }
@@ -257,7 +257,7 @@ export async function offboardUser(config, params) {
             }
         }
         catch (e) {
-            actions.push({ action: 'revoke_file', status: 'failed', detail: `${file.file_name}: ${e.response?.status || e.message}` });
+            actions.push({ action: 'revoke_file', status: 'failed', detail: `${file.file_name}: ${formatApiError(e)}` });
         }
     }
     // Step C: Revoke project access
@@ -312,7 +312,7 @@ export async function offboardUser(config, params) {
             actions.push({ action: 'downgrade_seat', status: 'done', detail: `${user.seat_type} -> viewer` });
         }
         catch (e) {
-            actions.push({ action: 'downgrade_seat', status: 'failed', detail: e.response?.status || e.message });
+            actions.push({ action: 'downgrade_seat', status: 'failed', detail: formatApiError(e) });
         }
     }
     const succeeded = actions.filter(a => a.status === 'done').length;
@@ -421,7 +421,7 @@ export async function onboardUser(config, params) {
             }
         }
         catch (e) {
-            seatChange = { status: 'failed', note: `Seat change failed: ${e.response?.status || e.message}` };
+            seatChange = { status: 'failed', note: `Seat change failed: ${formatApiError(e)}` };
         }
     }
     else if (seat_type && !confirm) {
@@ -482,7 +482,7 @@ export async function quarterlyDesignOpsReport(config, params) {
         }
         catch (e) {
             membersComplete = false;
-            errors.push(`members: pagination stopped at page ${page + 1} of ${maxPages}, fetched ${allMembers.length} members (${e.response?.status || e.message})`);
+            errors.push(`members: pagination stopped at page ${page + 1} of ${maxPages}, fetched ${allMembers.length} members (${formatApiError(e)})`);
             break;
         }
     }
@@ -609,6 +609,8 @@ export async function quarterlyDesignOpsReport(config, params) {
         highlights.push(`${totalInsertions} library component insertions across ${libraryAdoption.length} library/libraries.`);
     }
     const result = {
+        highlights,
+        ...(errors.length > 0 ? { errors } : {}),
         period: {
             start: periodStart.toISOString().split('T')[0],
             end: now.toISOString().split('T')[0],
@@ -628,10 +630,7 @@ export async function quarterlyDesignOpsReport(config, params) {
         teams,
         billing,
         library_adoption: libraryAdoption,
-        highlights,
     };
-    if (errors.length > 0)
-        result.errors = errors;
     return result;
 }
 //# sourceMappingURL=compound-manager.js.map

package/dist/operations/compound.d.ts

@@ -29,7 +29,9 @@ export declare function organizeProject(config: AuthConfig, params: {
     file_keys: string[];
     target_project_id: string;
 }): Promise<{
+    target_project_id: string;
     moved: number;
+    moved_file_keys: string[];
     failed: number;
     errors: any;
 }>;
@@ -87,6 +89,7 @@ export declare function branchCleanup(config: AuthConfig, params: {
     active_branches: any[];
     dry_run: boolean;
     archived: boolean;
+    archived_count: number;
     recommendations: string[];
 }>;
 //# sourceMappingURL=compound.d.ts.map

package/dist/operations/compound.js

@@ -1,7 +1,7 @@
 import { hasPat, hasCookie } from '../auth/client.js';
 import { publicClient } from '../clients/public-api.js';
 import { internalClient } from '../clients/internal-api.js';
-import { requireOrgId } from '../tools/register.js';
+import { requireOrgId, formatApiError } from '../helpers.js';
 // -- Shared helpers --
 const BATCH_SIZE = 5;
 async function batchProcess(items, fn) {
@@ -32,7 +32,7 @@ export async function fileSummary(config, params) {
         api.get(`/v1/files/${params.file_key}/comments`),
     ]);
     if (fileResult.status === 'rejected') {
-        throw new Error(`Failed to fetch file: ${fileResult.reason?.response?.status || fileResult.reason?.message}`);
+        throw new Error(`Failed to fetch file: ${formatApiError(fileResult.reason)}`);
     }
     const fileData = fileResult.value.data;
     const pages = (fileData.document?.children || []).map((c) => c.name);
@@ -78,11 +78,11 @@ export async function workspaceOverview(config, params) {
         delete billing.shipping_address;
     const errors = [];
     if (teamsResult.status === 'rejected')
-        errors.push(`teams: ${teamsResult.reason?.response?.status || teamsResult.reason?.message}`);
+        errors.push(`teams: ${formatApiError(teamsResult.reason)}`);
     if (seatsResult.status === 'rejected')
-        errors.push(`seats: ${seatsResult.reason?.response?.status || seatsResult.reason?.message}`);
+        errors.push(`seats: ${formatApiError(seatsResult.reason)}`);
     if (billingResult.status === 'rejected')
-        errors.push(`billing: ${billingResult.reason?.response?.status || billingResult.reason?.message}`);
+        errors.push(`billing: ${formatApiError(billingResult.reason)}`);
     const overview = { teams, seats, billing };
     if (errors.length > 0)
         overview.errors = errors;
@@ -104,7 +104,7 @@ export async function openComments(config, params) {
             commentResults.push({ file_key: f.key, file_name: f.name, comments });
         }
         catch (e) {
-            commentResults.push({ file_key: f.key, file_name: f.name, comments: [], error: e.response?.status || e.message });
+            commentResults.push({ file_key: f.key, file_name: f.name, comments: [], error: formatApiError(e) });
         }
     }
     const filesWithComments = commentResults
@@ -180,6 +180,8 @@ export async function cleanupStaleFiles(config, params) {
                 data: { files: staleFiles.map((f) => ({ key: f.key })), trashed: true },
             });
             result.trashed = true;
+            result.trashed_count = staleFiles.length;
+            result.trashed_file_keys = staleFiles.map((f) => f.key);
         }
     }
     return result;
@@ -199,7 +201,9 @@ export async function organizeProject(config, params) {
     const moved = Object.keys(data?.success || {}).length;
     const failed = Object.keys(data?.errors || {}).length;
     return {
+        target_project_id: params.target_project_id,
         moved: moved || (failed === 0 ? params.file_keys.length : 0),
+        moved_file_keys: params.file_keys,
         failed,
         errors: data?.errors || {},
     };
@@ -230,7 +234,7 @@ export async function setupProjectStructure(config, params) {
             created.push({ id: folderId, name: project.name, description: project.description || null });
         }
         catch (e) {
-            failed.push({ name: project.name, error: e.response?.status || e.message });
+            failed.push({ name: project.name, error: formatApiError(e) });
         }
     }
     return { created, failed };
@@ -265,7 +269,7 @@ export async function seatOptimization(config, params) {
         }
         catch (e) {
             membersComplete = false;
-            warnings.push(`members: pagination stopped at page ${page + 1}, fetched ${allMembers.length} members (${e.response?.status || e.message})`);
+            warnings.push(`members: pagination stopped at page ${page + 1}, fetched ${allMembers.length} members (${formatApiError(e)})`);
             break;
         }
     }
@@ -584,6 +588,7 @@ export async function branchCleanup(config, params) {
         });
         archived = true;
     }
+    const archived_count = archived ? staleBranches.length : 0;
     const recommendations = [];
     if (staleBranches.length > 0) {
         recommendations.push(`${staleBranches.length} branch(es) stale for ${days_stale}+ days. ${dry_run ? 'Set dry_run=false to archive.' : 'Archived.'}`);
@@ -606,6 +611,7 @@ export async function branchCleanup(config, params) {
         active_branches: activeBranches,
         dry_run,
         archived,
+        archived_count,
         recommendations,
     };
 }