figmanage 0.2.1 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 MCP server for managing your Figma workspace.
 
-Manages Figma workspaces through AI assistants. 79 tools covering files, projects, teams, permissions, comments, versions, components, webhooks, org admin, and more. Works with Claude Code, Claude Desktop, ChatGPT, and any MCP-compatible client.
+Manages Figma workspaces through AI assistants. 85 tools covering files, projects, teams, permissions, comments, versions, components, webhooks, org admin, and more. Works with Claude Code, Claude Desktop, ChatGPT, and any MCP-compatible client.
 
 ## quick start
 
@@ -16,13 +16,13 @@ claude mcp add figmanage -s user -e FIGMA_PAT=figd_xxx -- npx -y figmanage
 
 Restart Claude Code. Gives you 30+ tools (comments, reading, export, components, versions, webhooks).
 
-### full setup (2 minutes, all 79 tools)
+### full setup (2 minutes, all 85 tools)
 
 ```bash
 npx -y figmanage --setup
 ```
 
-Extracts your Chrome cookie, prompts for a PAT, registers with Claude Code automatically. Unlocks all 79 tools including workspace management, permissions, and org admin. Restart Claude Code.
+Extracts your Chrome cookie, prompts for a PAT, registers with Claude Code automatically. Unlocks all 85 tools including workspace management, permissions, and org admin. Restart Claude Code.
 
 Use `--no-prompt --pat figd_xxx` for non-interactive setup.
 
@@ -260,7 +260,7 @@ Tools are automatically filtered at startup based on available credentials. If y
 |------|------|-------------|
 | `list_org_libraries` | cookie | All design system libraries in the org with sharing group info |
 
-### compound (6 tools)
+### compound (12 tools)
 
 Multi-step operations that aggregate data from several API calls.
 
@@ -272,6 +272,12 @@ Multi-step operations that aggregate data from several API calls.
 | `cleanup_stale_files` | either | Find files not modified in N days, optionally trash them (dry run by default) |
 | `organize_project` | cookie | Batch-move files into a target project |
 | `setup_project_structure` | cookie | Create multiple projects in a team from a plan |
+| `seat_optimization` | cookie | Identify inactive paid seats and calculate potential savings |
+| `permission_audit` | cookie | Audit who has access to a team or project, flag oversharing |
+| `branch_cleanup` | either | Find stale branches across a project, optionally archive (dry run by default) |
+| `offboard_user` | cookie | Audit + execute user departure: transfer files, revoke access, downgrade seat |
+| `onboard_user` | cookie | Batch invite to teams, share files, set seat type in one call |
+| `quarterly_design_ops_report` | cookie | Org-wide snapshot: seat utilization, billing, teams, library adoption |
 
 ## transport modes
 
@@ -329,7 +335,8 @@ src/
     org.ts              Org admin, billing, seats, domains via internal API (9 tools)
     teams.ts            Team CRUD (3 tools)
     libraries.ts        Design system libraries via internal API (1 tool)
-    compound.ts         Multi-step aggregation tools (6 tools)
+    compound.ts         Multi-step aggregation tools (9 tools)
+    compound-manager.ts Manager workflow tools (3 tools)
   types/
     figma.ts            Shared types (Toolset, AuthConfig, etc.)
 ```

package/dist/index.d.ts

@@ -16,4 +16,5 @@ import './tools/org.js';
 import './tools/libraries.js';
 import './tools/teams.js';
 import './tools/compound.js';
+import './tools/compound-manager.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -28,6 +28,7 @@ import './tools/org.js';
 import './tools/libraries.js';
 import './tools/teams.js';
 import './tools/compound.js';
+import './tools/compound-manager.js';
 const ALL_TOOLSETS = [
     'navigate', 'files', 'projects', 'permissions', 'org',
     'versions', 'branching', 'comments', 'export',

package/dist/tools/compound-manager.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=compound-manager.d.ts.map

package/dist/tools/compound-manager.js

@@ -0,0 +1,719 @@
+import { z } from 'zod';
+import { internalClient } from '../clients/internal-api.js';
+import { defineTool, toolResult, toolError, figmaId, requireOrgId } from './register.js';
+const BATCH_SIZE = 5;
+const LEVEL_NAMES = { 999: 'owner', 300: 'editor', 100: 'viewer' };
+function levelName(level) {
+    return LEVEL_NAMES[level] || `level:${level}`;
+}
+/** Process items in batches of BATCH_SIZE using Promise.allSettled */
+async function batchProcess(items, fn) {
+    const results = [];
+    for (let i = 0; i < items.length; i += BATCH_SIZE) {
+        const batch = items.slice(i, i + BATCH_SIZE);
+        const batchResults = await Promise.allSettled(batch.map(fn));
+        results.push(...batchResults);
+    }
+    return results;
+}
+// -- offboard_user --
+const SEAT_KEY_TO_TYPE = {
+    expert: 'full',
+    developer: 'dev',
+    collaborator: 'collab',
+};
+const MAX_REVOCATIONS = 25;
+defineTool({
+    toolset: 'compound',
+    auth: 'cookie',
+    mutates: true,
+    destructive: true,
+    register(server, config) {
+        server.registerTool('offboard_user', {
+            description: 'Audit and optionally execute user offboarding. Default: read-only audit. With execute=true: transfers file ownership, revokes access, downgrades seat.',
+            inputSchema: {
+                user_identifier: z.string().describe('Email or user_id of the user to offboard'),
+                execute: z.boolean().optional().default(false).describe('Execute the offboarding (default: false, audit only)'),
+                transfer_to: z.string().optional().describe('Email or user_id to transfer file ownership to (required if user owns files and execute=true)'),
+                org_id: figmaId.optional().describe('Org ID override (defaults to current workspace)'),
+            },
+        }, async ({ user_identifier, execute: rawExecute, transfer_to, org_id }) => {
+            try {
+                let orgId;
+                try {
+                    orgId = requireOrgId(config, org_id);
+                }
+                catch (e) {
+                    return toolError(e.message);
+                }
+                const api = internalClient(config);
+                // Step 1: Resolve user
+                const userRes = await api.get(`/api/v2/orgs/${orgId}/org_users`, {
+                    params: user_identifier.includes('@') ? { search_query: user_identifier } : {},
+                });
+                const rawUsers = userRes.data?.meta?.users || userRes.data?.meta || userRes.data || [];
+                const members = Array.isArray(rawUsers) ? rawUsers : [];
+                const member = members.find((m) => user_identifier.includes('@')
+                    ? m.user?.email === user_identifier
+                    : String(m.user_id) === String(user_identifier));
+                if (!member) {
+                    return toolError(`User not found: ${user_identifier}`);
+                }
+                const userId = String(member.user_id);
+                // Block self-offboarding
+                if (userId === String(config.userId)) {
+                    return toolError('Cannot audit yourself for offboarding.');
+                }
+                const user = {
+                    org_user_id: String(member.id),
+                    user_id: userId,
+                    name: member.user?.handle || null,
+                    email: member.user?.email || null,
+                    seat_type: member.active_seat_type?.key || null,
+                    permission: member.permission || null,
+                };
+                // Step 2: Fetch all org teams
+                const teamsRes = await api.get(`/api/orgs/${orgId}/teams`);
+                const allTeams = (teamsRes.data?.meta || teamsRes.data || []);
+                const cappedTeams = allTeams.slice(0, 30);
+                // Step 3: Check team membership (batched)
+                const teamMemberships = [];
+                const memberResults = await batchProcess(cappedTeams, async (team) => {
+                    const res = await api.get(`/api/teams/${team.id}/members`);
+                    const teamMembers = res.data?.meta || res.data || [];
+                    const match = teamMembers.find((m) => String(m.id) === userId);
+                    return { team, match };
+                });
+                for (const r of memberResults) {
+                    if (r.status === 'fulfilled' && r.value.match) {
+                        const { team, match } = r.value;
+                        teamMemberships.push({
+                            team_id: String(team.id),
+                            team_name: team.name,
+                            role: match.team_role?.level ? levelName(match.team_role.level) : 'member',
+                        });
+                    }
+                }
+                // Step 4: For each team the user belongs to (cap 10), get projects
+                const userTeams = teamMemberships.slice(0, 10);
+                const allProjects = [];
+                const projectResults = await batchProcess(userTeams, async (tm) => {
+                    const res = await api.get(`/api/teams/${tm.team_id}/folders`);
+                    const raw = res.data?.meta?.folder_rows || res.data?.meta || res.data || [];
+                    const folders = Array.isArray(raw) ? raw : [];
+                    return { team_name: tm.team_name, folders };
+                });
+                for (const r of projectResults) {
+                    if (r.status === 'fulfilled') {
+                        for (const f of r.value.folders) {
+                            if (allProjects.length >= 50)
+                                break;
+                            allProjects.push({
+                                project_id: String(f.id),
+                                project_name: f.name,
+                                team_name: r.value.team_name,
+                            });
+                        }
+                    }
+                }
+                // Step 5: Check project roles (batched)
+                const projectPermissions = [];
+                const roleResults = await batchProcess(allProjects, async (proj) => {
+                    const res = await api.get(`/api/roles/folder/${proj.project_id}`);
+                    const roles = res.data?.meta || [];
+                    const match = roles.find((r) => String(r.user_id) === userId);
+                    return { proj, match };
+                });
+                for (const r of roleResults) {
+                    if (r.status === 'fulfilled' && r.value.match) {
+                        const { proj, match } = r.value;
+                        projectPermissions.push({
+                            project_id: proj.project_id,
+                            project_name: proj.project_name,
+                            team_name: proj.team_name,
+                            role: levelName(match.level),
+                        });
+                    }
+                }
+                // Step 6: Sample files from projects where user has access
+                const projectsWithAccess = projectPermissions.slice(0, 10);
+                const fileOwnership = [];
+                let totalFilesChecked = 0;
+                for (const proj of projectsWithAccess) {
+                    if (totalFilesChecked >= 50)
+                        break;
+                    try {
+                        const filesRes = await api.get(`/api/folders/${proj.project_id}/paginated_files`, {
+                            params: { folderId: proj.project_id, page_size: 10 },
+                        });
+                        const meta = filesRes.data?.meta || filesRes.data;
+                        const files = meta?.files || meta || [];
+                        const fileRoleResults = await batchProcess(files.slice(0, Math.min(10, 50 - totalFilesChecked)), async (file) => {
+                            const res = await api.get(`/api/roles/file/${file.key}`);
+                            const roles = res.data?.meta || [];
+                            const match = roles.find((r) => String(r.user_id) === userId && r.level === 999);
+                            return { file, match };
+                        });
+                        for (const r of fileRoleResults) {
+                            totalFilesChecked++;
+                            if (r.status === 'fulfilled' && r.value.match) {
+                                fileOwnership.push({
+                                    file_key: r.value.file.key,
+                                    file_name: r.value.file.name,
+                                    project_name: proj.project_name,
+                                    team_name: proj.team_name,
+                                });
+                            }
+                        }
+                    }
+                    catch {
+                        // Skip projects where file listing fails
+                    }
+                }
+                const execute = rawExecute ?? false;
+                const summary = {
+                    teams: teamMemberships.length,
+                    projects_with_access: projectPermissions.length,
+                    files_owned: fileOwnership.length,
+                };
+                const transferPlan = [];
+                if (fileOwnership.length > 0) {
+                    transferPlan.push(`${fileOwnership.length} file(s) need ownership transfer before removal.`);
+                }
+                if (teamMemberships.length > 0) {
+                    transferPlan.push(`Remove from ${teamMemberships.length} team(s).`);
+                }
+                if (projectPermissions.length > 0) {
+                    transferPlan.push(`Revoke access to ${projectPermissions.length} project(s).`);
+                }
+                if (user.seat_type) {
+                    transferPlan.push(`Downgrade or remove ${user.seat_type} seat.`);
+                }
+                // Audit-only mode
+                if (!execute) {
+                    const result = {
+                        user,
+                        team_memberships: teamMemberships,
+                        project_permissions: projectPermissions,
+                        file_ownership: fileOwnership,
+                        summary,
+                        transfer_plan: transferPlan,
+                        note: 'Run with execute=true to perform offboarding. Provide transfer_to if the user owns files.',
+                    };
+                    return toolResult(JSON.stringify(result, null, 2));
+                }
+                // --- Execute mode ---
+                // Validate: if user owns files, transfer_to is required
+                if (fileOwnership.length > 0 && !transfer_to) {
+                    return toolError(`User owns ${fileOwnership.length} file(s). Provide transfer_to (email or user_id) to transfer ownership before revoking access.`);
+                }
+                // Resolve transfer_to user
+                let transferToUserId;
+                if (transfer_to) {
+                    const tRes = await api.get(`/api/v2/orgs/${orgId}/org_users`, {
+                        params: transfer_to.includes('@') ? { search_query: transfer_to } : {},
+                    });
+                    const tUsers = tRes.data?.meta?.users || tRes.data?.meta || tRes.data || [];
+                    const tList = Array.isArray(tUsers) ? tUsers : [];
+                    const tMatch = tList.find((m) => transfer_to.includes('@')
+                        ? m.user?.email === transfer_to
+                        : String(m.user_id) === String(transfer_to));
+                    if (!tMatch)
+                        return toolError(`Transfer target not found: ${transfer_to}`);
+                    transferToUserId = String(tMatch.user_id);
+                }
+                // Cap total mutations
+                const totalMutations = fileOwnership.length + teamMemberships.length + projectPermissions.length + 1;
+                if (totalMutations > MAX_REVOCATIONS) {
+                    return toolError(`Offboarding would require ${totalMutations} mutations (cap: ${MAX_REVOCATIONS}). ` +
+                        `Reduce scope or execute manually with revoke_access and set_permissions.`);
+                }
+                const actions = [];
+                // Step A: Transfer file ownership
+                if (fileOwnership.length > 0 && transferToUserId) {
+                    for (const file of fileOwnership) {
+                        try {
+                            // Get the role entry for the file
+                            const rolesRes = await api.get(`/api/roles/file/${file.file_key}`);
+                            const roles = rolesRes.data?.meta || [];
+                            const ownerRole = roles.find((r) => String(r.user_id) === userId && r.level === 999);
+                            const transfereeRole = roles.find((r) => String(r.user_id) === transferToUserId);
+                            // Give transfer target owner access
+                            if (transfereeRole) {
+                                await api.put(`/api/roles/${transfereeRole.id}`, { level: 999 });
+                            }
+                            else {
+                                // Invite as editor first, then promote -- can't directly set owner on uninvited user
+                                await api.post('/api/invites', {
+                                    resource_type: 'file',
+                                    resource_id_or_key: file.file_key,
+                                    emails: [transfer_to],
+                                    level: 300,
+                                });
+                                // Re-fetch roles to get the new role ID
+                                const rolesRes2 = await api.get(`/api/roles/file/${file.file_key}`);
+                                const roles2 = rolesRes2.data?.meta || [];
+                                const newRole = roles2.find((r) => String(r.user_id) === transferToUserId);
+                                if (newRole) {
+                                    await api.put(`/api/roles/${newRole.id}`, { level: 999 });
+                                }
+                            }
+                            // Downgrade departing user from owner to editor (can't revoke owner directly)
+                            if (ownerRole) {
+                                await api.put(`/api/roles/${ownerRole.id}`, { level: 300 });
+                            }
+                            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}` });
+                        }
+                    }
+                }
+                // Step B: Revoke file access (now that they're no longer owner)
+                for (const file of fileOwnership) {
+                    try {
+                        const rolesRes = await api.get(`/api/roles/file/${file.file_key}`);
+                        const roles = rolesRes.data?.meta || [];
+                        const role = roles.find((r) => String(r.user_id) === userId);
+                        if (role) {
+                            await api.delete(`/api/roles/${role.id}`);
+                            actions.push({ action: 'revoke_file', status: 'done', detail: file.file_name });
+                        }
+                    }
+                    catch (e) {
+                        actions.push({ action: 'revoke_file', status: 'failed', detail: `${file.file_name}: ${e.response?.status || e.message}` });
+                    }
+                }
+                // Step C: Revoke project access
+                const projResults = await batchProcess(projectPermissions, async (proj) => {
+                    const rolesRes = await api.get(`/api/roles/folder/${proj.project_id}`);
+                    const roles = rolesRes.data?.meta || [];
+                    const role = roles.find((r) => String(r.user_id) === userId);
+                    if (role)
+                        await api.delete(`/api/roles/${role.id}`);
+                    return proj;
+                });
+                for (let i = 0; i < projectPermissions.length; i++) {
+                    const r = projResults[i];
+                    actions.push({
+                        action: 'revoke_project',
+                        status: r.status === 'fulfilled' ? 'done' : 'failed',
+                        detail: projectPermissions[i].project_name,
+                    });
+                }
+                // Step D: Revoke team memberships
+                const teamResults = await batchProcess(teamMemberships, async (tm) => {
+                    const rolesRes = await api.get(`/api/roles/team/${tm.team_id}`);
+                    const roles = rolesRes.data?.meta || [];
+                    const role = roles.find((r) => String(r.user_id) === userId);
+                    if (role)
+                        await api.delete(`/api/roles/${role.id}`);
+                    return tm;
+                });
+                for (let i = 0; i < teamMemberships.length; i++) {
+                    const r = teamResults[i];
+                    actions.push({
+                        action: 'revoke_team',
+                        status: r.status === 'fulfilled' ? 'done' : 'failed',
+                        detail: teamMemberships[i].team_name,
+                    });
+                }
+                // Step E: Downgrade seat to viewer
+                if (user.seat_type) {
+                    try {
+                        const viewStatuses = { collaborator: 'starter', developer: 'starter', expert: 'starter' };
+                        await api.put(`/api/orgs/${orgId}/org_users`, {
+                            org_user_ids: [user.org_user_id],
+                            paid_statuses: viewStatuses,
+                            entry_point: 'members_tab',
+                            seat_increase_authorized: 'true',
+                            seat_swap_intended: 'false',
+                            latest_ou_update: member.updated_at,
+                            showing_billing_groups: 'true',
+                        }, {
+                            'axios-retry': { retries: 0 },
+                        });
+                        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 });
+                    }
+                }
+                const succeeded = actions.filter(a => a.status === 'done').length;
+                const failed = actions.filter(a => a.status === 'failed').length;
+                const result = {
+                    user,
+                    executed: true,
+                    actions,
+                    summary: { succeeded, failed, total: actions.length },
+                    note: failed > 0
+                        ? `${failed} action(s) failed. Review and retry manually.`
+                        : 'Offboarding complete.',
+                };
+                return toolResult(JSON.stringify(result, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to audit user for offboarding: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- onboard_user --
+const PAID_STATUSES = {
+    full: { expert: 'full' },
+    dev: { developer: 'full' },
+    collab: { collaborator: 'full' },
+    view: { collaborator: 'starter', developer: 'starter', expert: 'starter' },
+};
+const LEVEL_MAP = { editor: 300, viewer: 100 };
+defineTool({
+    toolset: 'compound',
+    auth: 'cookie',
+    mutates: true,
+    register(server, config) {
+        server.registerTool('onboard_user', {
+            description: 'Invite a user to teams and optionally share files and set seat type. Sends invite emails per team.',
+            inputSchema: {
+                email: z.string().email().describe('Email address to invite'),
+                team_ids: z.array(figmaId).min(1).describe('Team IDs to invite the user to'),
+                role: z.enum(['editor', 'viewer']).optional().default('editor').describe('Role for team access (default: editor)'),
+                share_files: z.array(figmaId).optional().describe('File keys to share with the user (viewer access)'),
+                seat_type: z.enum(['full', 'dev', 'collab', 'view']).optional().describe('Seat type to assign after invite'),
+                confirm: z.boolean().optional().describe('Required to execute seat change'),
+                org_id: figmaId.optional().describe('Org ID override (defaults to current workspace)'),
+            },
+        }, async ({ email, team_ids, role, share_files, seat_type, confirm, org_id }) => {
+            try {
+                let orgId;
+                try {
+                    orgId = requireOrgId(config, org_id);
+                }
+                catch (e) {
+                    return toolError(e.message);
+                }
+                // Enforce caps
+                if (team_ids.length > 10) {
+                    return toolError(`Too many teams: ${team_ids.length}. Maximum is 10.`);
+                }
+                if (share_files && share_files.length > 20) {
+                    return toolError(`Too many files: ${share_files.length}. Maximum is 20.`);
+                }
+                const api = internalClient(config);
+                const level = LEVEL_MAP[role || 'editor'];
+                // Validate team_ids exist
+                const teamsRes = await api.get(`/api/orgs/${orgId}/teams`);
+                const orgTeams = teamsRes.data?.meta || teamsRes.data || [];
+                const orgTeamMap = new Map();
+                for (const t of orgTeams) {
+                    orgTeamMap.set(String(t.id), t.name);
+                }
+                const invalidTeams = team_ids.filter(id => !orgTeamMap.has(id));
+                if (invalidTeams.length > 0) {
+                    return toolError(`Team(s) not found in org: ${invalidTeams.join(', ')}`);
+                }
+                // Invite to teams (batched)
+                const teamsJoined = [];
+                const teamInviteResults = await batchProcess(team_ids, async (teamId) => {
+                    const res = await api.post('/api/invites', {
+                        resource_type: 'team',
+                        resource_id_or_key: teamId,
+                        emails: [email],
+                        level,
+                    });
+                    return { teamId, res };
+                });
+                for (let i = 0; i < team_ids.length; i++) {
+                    const r = teamInviteResults[i];
+                    teamsJoined.push({
+                        team_id: team_ids[i],
+                        team_name: orgTeamMap.get(team_ids[i]) || 'unknown',
+                        role: role || 'editor',
+                        status: r.status === 'fulfilled' ? 'invited' : 'failed',
+                    });
+                }
+                // Share files (batched, viewer access)
+                const filesShared = [];
+                if (share_files && share_files.length > 0) {
+                    const fileShareResults = await batchProcess(share_files, async (fileKey) => {
+                        await api.post('/api/invites', {
+                            resource_type: 'file',
+                            resource_id_or_key: fileKey,
+                            emails: [email],
+                            level: 100, // viewer
+                        });
+                        return fileKey;
+                    });
+                    for (let i = 0; i < share_files.length; i++) {
+                        const r = fileShareResults[i];
+                        filesShared.push({
+                            file_key: share_files[i],
+                            role: 'viewer',
+                            status: r.status === 'fulfilled' ? 'shared' : 'failed',
+                        });
+                    }
+                }
+                // Seat change
+                let seatChange = { status: 'skipped', note: 'No seat_type specified.' };
+                if (seat_type && confirm) {
+                    try {
+                        const userRes = await api.get(`/api/v2/orgs/${orgId}/org_users`, {
+                            params: { search_query: email },
+                        });
+                        const rawU = userRes.data?.meta?.users || userRes.data?.meta || userRes.data || [];
+                        const users = Array.isArray(rawU) ? rawU : [];
+                        const found = users.find((m) => m.user?.email === email);
+                        if (found) {
+                            await api.put(`/api/orgs/${orgId}/org_users`, {
+                                org_user_ids: [String(found.id)],
+                                paid_statuses: PAID_STATUSES[seat_type],
+                                entry_point: 'members_tab',
+                                seat_increase_authorized: 'true',
+                                seat_swap_intended: 'false',
+                                latest_ou_update: found.updated_at,
+                                showing_billing_groups: 'true',
+                            }, {
+                                'axios-retry': { retries: 0 },
+                            });
+                            seatChange = { status: 'changed', note: `Set to ${seat_type}.` };
+                        }
+                        else {
+                            seatChange = { status: 'skipped', note: 'User not yet in org (invite pending). Seat change will need to be applied after they accept.' };
+                        }
+                    }
+                    catch (e) {
+                        seatChange = { status: 'failed', note: `Seat change failed: ${e.response?.status || e.message}` };
+                    }
+                }
+                else if (seat_type && !confirm) {
+                    seatChange = { status: 'skipped', note: `Set confirm: true to apply ${seat_type} seat change.` };
+                }
+                const result = {
+                    user_email: email,
+                    setup_results: {
+                        teams_joined: teamsJoined,
+                        files_shared: filesShared,
+                        seat_change: seatChange,
+                    },
+                    next_steps: [
+                        'User will receive invite emails for each team.',
+                        'Team-level projects are automatically accessible once they accept.',
+                    ],
+                };
+                return toolResult(JSON.stringify(result, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to onboard user: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- quarterly_design_ops_report --
+defineTool({
+    toolset: 'compound',
+    auth: 'cookie',
+    register(server, config) {
+        server.registerTool('quarterly_design_ops_report', {
+            description: 'Org-wide design ops snapshot: seat utilization, team activity, billing, and library adoption over a given period.',
+            inputSchema: {
+                org_id: figmaId.optional().describe('Org ID override (defaults to current workspace)'),
+                days: z.number().min(1).max(365).optional().default(90).describe('Lookback period in days (default: 90)'),
+            },
+        }, async ({ org_id, days: rawDays }) => {
+            try {
+                let orgId;
+                try {
+                    orgId = requireOrgId(config, org_id);
+                }
+                catch (e) {
+                    return toolError(e.message);
+                }
+                const days = rawDays ?? 90;
+                const api = internalClient(config);
+                const now = new Date();
+                const periodStart = new Date(now.getTime() - days * 86400000);
+                // Phase 1: Parallel fetches
+                const [teamsResult, seatsResult, billingResult, upcomingResult, ratesResult] = await Promise.allSettled([
+                    api.get(`/api/orgs/${orgId}/teams`, {
+                        params: { include_member_count: true, include_project_count: true },
+                    }),
+                    api.get(`/api/orgs/${orgId}/org_users/filter_counts`),
+                    api.get(`/api/orgs/${orgId}/billing_data`),
+                    api.get(`/api/plans/organization/${orgId}/invoices/upcoming`),
+                    api.get(`/api/pricing/contract_rates`, {
+                        params: { plan_parent_id: orgId, plan_type: 'organization' },
+                    }),
+                ]);
+                // Paginate all members (cursor-based, max 500)
+                const allMembers = [];
+                let cursor;
+                const maxPages = 20;
+                for (let page = 0; page < maxPages; page++) {
+                    try {
+                        const params = { page_size: 25 };
+                        if (cursor)
+                            params.cursor = cursor;
+                        const res = await api.get(`/api/v2/orgs/${orgId}/org_users`, { params });
+                        const meta = res.data?.meta || {};
+                        const batch = meta.users || [];
+                        if (!Array.isArray(batch) || batch.length === 0)
+                            break;
+                        allMembers.push(...batch);
+                        cursor = Array.isArray(meta.cursor) ? meta.cursor[0] : meta.cursor;
+                        if (!cursor || batch.length < 25)
+                            break;
+                    }
+                    catch {
+                        break;
+                    }
+                }
+                // Process teams
+                const teamsRaw = teamsResult.status === 'fulfilled'
+                    ? (teamsResult.value.data?.meta || teamsResult.value.data || [])
+                    : [];
+                const teamsArray = Array.isArray(teamsRaw) ? teamsRaw : [];
+                const teams = teamsArray.map((t) => ({
+                    team_name: t.name,
+                    members: t.member_count || 0,
+                    projects: t.project_count || 0,
+                }));
+                // Seat utilization from member list
+                const paidKeys = new Set(['expert', 'developer', 'collaborator']);
+                const cutoffMs = now.getTime() - days * 86400000;
+                let totalPaid = 0;
+                let inactivePaid = 0;
+                const seatCounts = {};
+                for (const m of allMembers) {
+                    const seatKey = m.active_seat_type?.key;
+                    if (seatKey && paidKeys.has(seatKey)) {
+                        totalPaid++;
+                        seatCounts[seatKey] = (seatCounts[seatKey] || 0) + 1;
+                        const lastSeen = m.last_seen ? new Date(m.last_seen).getTime() : 0;
+                        if (!m.last_seen || lastSeen < cutoffMs) {
+                            inactivePaid++;
+                        }
+                    }
+                }
+                const activePaid = totalPaid - inactivePaid;
+                const utilizationRate = totalPaid > 0
+                    ? Number(((activePaid / totalPaid) * 100).toFixed(1))
+                    : 0;
+                // Billing
+                let billing = null;
+                const errors = [];
+                if (ratesResult.status === 'fulfilled') {
+                    const prices = ratesResult.value.data?.meta?.product_prices || [];
+                    const seatProducts = new Set(['expert', 'developer', 'collaborator']);
+                    let monthlySpendCents = 0;
+                    for (const p of prices) {
+                        if (seatProducts.has(p.billable_product_key)) {
+                            const count = seatCounts[p.billable_product_key] || 0;
+                            monthlySpendCents += count * (p.amount || 0);
+                        }
+                    }
+                    const monthlySpendDollars = Number((monthlySpendCents / 100).toFixed(2));
+                    const costPerActiveUser = activePaid > 0
+                        ? Number((monthlySpendDollars / activePaid).toFixed(2))
+                        : 0;
+                    billing = {
+                        monthly_spend_dollars: monthlySpendDollars,
+                        cost_per_active_user: costPerActiveUser,
+                    };
+                    if (upcomingResult.status === 'fulfilled') {
+                        const upcoming = upcomingResult.value.data;
+                        billing.upcoming_invoice_date = upcoming?.date || upcoming?.period_end || null;
+                        billing.upcoming_amount = upcoming?.amount_due ?? upcoming?.total ?? null;
+                    }
+                }
+                else {
+                    errors.push('billing: rates unavailable (may require admin)');
+                }
+                if (billingResult.status === 'fulfilled' && billing) {
+                    const rawBilling = billingResult.value.data?.meta || billingResult.value.data;
+                    if (rawBilling) {
+                        const { shipping_address, ...safeBilling } = rawBilling;
+                        billing.plan_name = safeBilling.plan_name || safeBilling.name || null;
+                    }
+                }
+                else if (billingResult.status === 'rejected') {
+                    errors.push('billing_data: 403 (admin required)');
+                }
+                // Phase 2: Library adoption
+                const libraryAdoption = [];
+                try {
+                    const libRes = await api.get('/api/design_systems/libraries', {
+                        params: { org_id: orgId },
+                    });
+                    const libraries = libRes.data?.libraries || libRes.data?.meta?.libraries || [];
+                    const cappedLibraries = libraries.slice(0, 5);
+                    const endTs = Math.floor(now.getTime() / 1000);
+                    const startTs = Math.floor(periodStart.getTime() / 1000);
+                    const libResults = await batchProcess(cappedLibraries, async (lib) => {
+                        const res = await api.get(`/api/dsa/library/${lib.file_key || lib.key}/team_usage`, {
+                            params: { start_ts: startTs, end_ts: endTs },
+                        });
+                        return { lib, data: res.data };
+                    });
+                    for (const r of libResults) {
+                        if (r.status === 'fulfilled') {
+                            const { lib, data } = r.value;
+                            const teamUsages = data?.rows || data?.teams || [];
+                            let totalInsertions = 0;
+                            for (const tu of teamUsages) {
+                                totalInsertions += tu.insertions || tu.num_insertions || 0;
+                            }
+                            libraryAdoption.push({
+                                library_name: lib.name || lib.file_name || 'unknown',
+                                file_key: lib.file_key || lib.key,
+                                insertions: totalInsertions,
+                            });
+                        }
+                    }
+                }
+                catch {
+                    errors.push('libraries: failed to fetch (may be 404)');
+                }
+                // Highlights
+                const highlights = [];
+                highlights.push(`${utilizationRate}% seat utilization (${activePaid} active of ${totalPaid} paid).`);
+                if (inactivePaid > 0) {
+                    highlights.push(`${inactivePaid} paid seat(s) inactive for ${days}+ days.`);
+                }
+                if (teams.length > 0) {
+                    highlights.push(`${teams.length} team(s), ${allMembers.length} total member(s).`);
+                }
+                if (libraryAdoption.length > 0) {
+                    const totalInsertions = libraryAdoption.reduce((sum, l) => sum + l.insertions, 0);
+                    highlights.push(`${totalInsertions} library component insertions across ${libraryAdoption.length} library/libraries.`);
+                }
+                const result = {
+                    period: {
+                        start: periodStart.toISOString().split('T')[0],
+                        end: now.toISOString().split('T')[0],
+                        days,
+                    },
+                    org_overview: {
+                        total_teams: teams.length,
+                        total_members: allMembers.length,
+                        total_paid_seats: totalPaid,
+                    },
+                    seat_utilization: {
+                        active_paid: activePaid,
+                        inactive_paid: inactivePaid,
+                        utilization_rate: utilizationRate,
+                    },
+                    teams,
+                    billing,
+                    library_adoption: libraryAdoption,
+                    highlights,
+                };
+                if (errors.length > 0)
+                    result.errors = errors;
+                return toolResult(JSON.stringify(result, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to generate design ops report: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+//# sourceMappingURL=compound-manager.js.map

package/dist/tools/compound.js

@@ -331,4 +331,434 @@ defineTool({
         });
     },
 });
+// -- seat_optimization --
+const SEAT_KEY_MAP = {
+    expert: 'full',
+    developer: 'dev',
+    collaborator: 'collab',
+};
+defineTool({
+    toolset: 'compound',
+    auth: 'cookie',
+    register(server, config) {
+        server.registerTool('seat_optimization', {
+            description: 'Identify inactive paid seats and calculate potential savings. Fetches members, seat counts, and pricing to find optimization opportunities.',
+            inputSchema: {
+                org_id: figmaId.optional().describe('Org ID override (defaults to current workspace)'),
+                days_inactive: z.number().min(1).max(365).optional().default(90).describe('Days without activity to flag as inactive (default: 90)'),
+                include_cost: z.boolean().optional().default(true).describe('Include cost analysis from contract rates (default: true)'),
+            },
+        }, async ({ org_id, days_inactive: rawDaysInactive, include_cost: rawIncludeCost }) => {
+            try {
+                const days_inactive = rawDaysInactive ?? 90;
+                const include_cost = rawIncludeCost ?? true;
+                let orgId;
+                try {
+                    orgId = requireOrgId(config, org_id);
+                }
+                catch (e) {
+                    return toolError(e.message);
+                }
+                const api = internalClient(config);
+                const cutoff = Date.now() - days_inactive * 86400000;
+                const paidKeys = new Set(['expert', 'developer', 'collaborator']);
+                // Paginate org members (cursor-based, max 500)
+                const allMembers = [];
+                const MAX_PAGES = 20;
+                let cursor;
+                for (let page = 0; page < MAX_PAGES; page++) {
+                    const params = { page_size: 25 };
+                    if (cursor)
+                        params.cursor = cursor;
+                    const res = await api.get(`/api/v2/orgs/${orgId}/org_users`, { params });
+                    const meta = res.data?.meta || {};
+                    const members = meta.users || [];
+                    if (!Array.isArray(members) || members.length === 0)
+                        break;
+                    allMembers.push(...members);
+                    cursor = Array.isArray(meta.cursor) ? meta.cursor[0] : meta.cursor;
+                    if (!cursor || members.length < 25)
+                        break;
+                }
+                // Fetch seat breakdown and optionally contract rates in parallel
+                const parallelCalls = [
+                    api.get(`/api/orgs/${orgId}/org_users/filter_counts`),
+                ];
+                if (include_cost) {
+                    parallelCalls.push(api.get('/api/pricing/contract_rates', {
+                        params: { plan_parent_id: orgId, plan_type: 'organization' },
+                    }));
+                }
+                const [seatsResult, ratesResult] = await Promise.allSettled(parallelCalls);
+                const seats = seatsResult.status === 'fulfilled' ? (seatsResult.value.data?.meta || seatsResult.value.data) : null;
+                // Build cost lookup: seat key -> monthly cents
+                const costMap = {};
+                if (include_cost && ratesResult?.status === 'fulfilled') {
+                    const prices = ratesResult.value.data?.meta?.product_prices || [];
+                    for (const p of prices) {
+                        if (paidKeys.has(p.billable_product_key)) {
+                            costMap[p.billable_product_key] = p.amount;
+                        }
+                    }
+                }
+                // Filter inactive paid members
+                const inactiveUsers = [];
+                let totalPaid = 0;
+                for (const m of allMembers) {
+                    const seatKey = m.active_seat_type?.key;
+                    if (!seatKey || !paidKeys.has(seatKey))
+                        continue;
+                    totalPaid++;
+                    const lastSeen = m.last_seen;
+                    const lastSeenMs = lastSeen ? new Date(lastSeen).getTime() : 0;
+                    const isInactive = !lastSeen || (lastSeenMs > 0 && lastSeenMs < cutoff) || isNaN(lastSeenMs);
+                    if (isInactive) {
+                        inactiveUsers.push({
+                            org_user_id: String(m.id),
+                            user_id: m.user_id,
+                            email: m.user?.email,
+                            name: m.user?.handle,
+                            seat_type: SEAT_KEY_MAP[seatKey] || seatKey,
+                            seat_key: seatKey,
+                            last_active: lastSeen || null,
+                            monthly_cost_cents: costMap[seatKey] || null,
+                        });
+                    }
+                }
+                const monthlyWasteCents = inactiveUsers.reduce((sum, u) => sum + (u.monthly_cost_cents || 0), 0);
+                const recommendations = [];
+                if (inactiveUsers.length > 0) {
+                    recommendations.push(`${inactiveUsers.length} paid seat(s) inactive for ${days_inactive}+ days. Review for downgrade to viewer.`);
+                }
+                const neverActive = inactiveUsers.filter((u) => !u.last_active);
+                if (neverActive.length > 0) {
+                    recommendations.push(`${neverActive.length} paid user(s) have never been active. Likely unused invites.`);
+                }
+                if (monthlyWasteCents > 0) {
+                    recommendations.push(`Potential monthly savings: $${(monthlyWasteCents / 100).toFixed(2)} ($${((monthlyWasteCents * 12) / 100).toFixed(2)}/yr).`);
+                }
+                const result = {
+                    summary: {
+                        total_paid: totalPaid,
+                        inactive_paid: inactiveUsers.length,
+                        monthly_waste_cents: monthlyWasteCents,
+                        annual_savings_cents: monthlyWasteCents * 12,
+                    },
+                    seat_breakdown: seats,
+                    inactive_users: inactiveUsers,
+                    recommendations,
+                };
+                return toolResult(JSON.stringify(result, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to analyze seat optimization: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- permission_audit --
+defineTool({
+    toolset: 'compound',
+    auth: 'cookie',
+    register(server, config) {
+        server.registerTool('permission_audit', {
+            description: 'Audit permissions across a team or project. Scans files for external editors, open link access, and elevated individual permissions.',
+            inputSchema: {
+                scope_type: z.enum(['project', 'team']).describe('Scope to audit'),
+                scope_id: figmaId.describe('Team ID or project ID'),
+                flag_external: z.boolean().optional().default(true).describe('Flag external users (default: true)'),
+                org_id: figmaId.optional().describe('Org ID override (defaults to current workspace)'),
+            },
+        }, async ({ scope_type, scope_id, flag_external: rawFlagExternal, org_id }) => {
+            try {
+                const flag_external = rawFlagExternal ?? true;
+                const api = internalClient(config);
+                // Resolve org for domain lookup
+                let orgId;
+                let domainCheckSkipped = false;
+                if (flag_external) {
+                    try {
+                        orgId = requireOrgId(config, org_id);
+                    }
+                    catch {
+                        domainCheckSkipped = true;
+                    }
+                }
+                // Fetch org verified domains for external detection
+                let verifiedDomains = new Set();
+                if (flag_external && orgId) {
+                    try {
+                        const domRes = await api.get(`/api/orgs/${orgId}/domains`);
+                        const domains = domRes.data?.meta || [];
+                        if (Array.isArray(domains)) {
+                            for (const d of domains) {
+                                if (d.domain)
+                                    verifiedDomains.add(d.domain.toLowerCase());
+                            }
+                        }
+                    }
+                    catch { /* domain lookup optional, continue without */ }
+                }
+                // Collect file keys to scan
+                let fileKeys = [];
+                if (scope_type === 'team') {
+                    // Fetch team projects, cap at 10
+                    const projectsRes = await api.get(`/api/teams/${scope_id}/folders`);
+                    const rows = projectsRes.data?.meta?.folder_rows || projectsRes.data || [];
+                    const projects = (Array.isArray(rows) ? rows : []).slice(0, 10);
+                    for (const proj of projects) {
+                        if (fileKeys.length >= 25)
+                            break;
+                        try {
+                            const filesRes = await api.get(`/api/folders/${proj.id}/paginated_files`, {
+                                params: { folderId: String(proj.id), page_size: 25, sort_column: 'touched_at', sort_order: 'desc', file_type: '' },
+                            });
+                            const meta = filesRes.data?.meta || filesRes.data;
+                            const files = meta?.files || meta || [];
+                            for (const f of (Array.isArray(files) ? files : [])) {
+                                if (fileKeys.length >= 25)
+                                    break;
+                                fileKeys.push({ key: f.key, name: f.name });
+                            }
+                        }
+                        catch { /* skip inaccessible projects */ }
+                    }
+                }
+                else {
+                    // Project scope
+                    const filesRes = await api.get(`/api/folders/${scope_id}/paginated_files`, {
+                        params: { folderId: scope_id, page_size: 25, sort_column: 'touched_at', sort_order: 'desc', file_type: '' },
+                    });
+                    const meta = filesRes.data?.meta || filesRes.data;
+                    const files = meta?.files || meta || [];
+                    for (const f of (Array.isArray(files) ? files : [])) {
+                        if (fileKeys.length >= 25)
+                            break;
+                        fileKeys.push({ key: f.key, name: f.name });
+                    }
+                }
+                // Fetch permissions and file metadata in parallel, batched 5 at a time
+                const allUsers = new Map();
+                const flags = [];
+                let filesScanned = 0;
+                for (let i = 0; i < fileKeys.length; i += 5) {
+                    const batch = fileKeys.slice(i, i + 5);
+                    const results = await Promise.allSettled(batch.map(async (file) => {
+                        const [rolesRes, fileMetaRes] = await Promise.allSettled([
+                            api.get(`/api/roles/file/${file.key}`),
+                            api.get(`/api/files/${file.key}`),
+                        ]);
+                        const roles = rolesRes.status === 'fulfilled'
+                            ? (Array.isArray(rolesRes.value.data?.meta) ? rolesRes.value.data.meta : [])
+                            : [];
+                        const fileMeta = fileMetaRes.status === 'fulfilled'
+                            ? (fileMetaRes.value.data?.meta || fileMetaRes.value.data || {})
+                            : {};
+                        return { file, roles, fileMeta };
+                    }));
+                    for (const r of results) {
+                        if (r.status === 'rejected')
+                            continue;
+                        filesScanned++;
+                        const { file, roles, fileMeta } = r.value;
+                        // Check link access
+                        const linkAccess = fileMeta.link_access;
+                        if (linkAccess === 'edit' || linkAccess === 'org_edit') {
+                            flags.push({
+                                severity: 'high',
+                                type: 'open_link_access',
+                                details: `${file.name} (${file.key}) has link_access="${linkAccess}"`,
+                            });
+                        }
+                        // Process roles
+                        for (const role of roles) {
+                            const email = role.user?.email || role.pending_email;
+                            const userId = role.user_id ? String(role.user_id) : email;
+                            const level = role.level;
+                            const levelName = level >= 999 ? 'owner' : level >= 300 ? 'editor' : 'viewer';
+                            if (userId && !allUsers.has(userId)) {
+                                allUsers.set(userId, {
+                                    user_id: userId,
+                                    email,
+                                    name: role.user?.handle,
+                                    files_accessed: [],
+                                });
+                            }
+                            if (userId) {
+                                const user = allUsers.get(userId);
+                                user.files_accessed.push({
+                                    file_key: file.key,
+                                    file_name: file.name,
+                                    role: levelName,
+                                });
+                            }
+                            // External editor detection
+                            if (flag_external && email && verifiedDomains.size > 0) {
+                                const domain = email.split('@')[1]?.toLowerCase();
+                                if (domain && !verifiedDomains.has(domain) && (levelName === 'editor' || levelName === 'owner')) {
+                                    flags.push({
+                                        severity: 'high',
+                                        type: 'external_editor',
+                                        details: `${email} (external) has ${levelName} access to ${file.name} (${file.key})`,
+                                    });
+                                }
+                            }
+                        }
+                    }
+                }
+                if (domainCheckSkipped) {
+                    flags.push({
+                        severity: 'info',
+                        type: 'domain_check_skipped',
+                        details: 'Could not resolve org ID; external user detection was skipped. Provide org_id or set FIGMA_ORG_ID.',
+                    });
+                }
+                const result = {
+                    scope: { type: scope_type, id: scope_id },
+                    summary: {
+                        unique_users: allUsers.size,
+                        files_scanned: filesScanned,
+                        total_files: fileKeys.length,
+                        flags_found: flags.length,
+                    },
+                    users: Array.from(allUsers.values()),
+                    flags,
+                };
+                return toolResult(JSON.stringify(result, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to audit permissions: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- branch_cleanup --
+defineTool({
+    toolset: 'compound',
+    auth: 'either',
+    mutates: true,
+    destructive: true,
+    register(server, config) {
+        server.registerTool('branch_cleanup', {
+            description: 'Find stale branches across a project and optionally archive them. Defaults to dry run.',
+            inputSchema: {
+                project_id: figmaId.describe('Project ID'),
+                days_stale: z.number().min(1).max(365).optional().default(60).describe('Days since last modification to flag as stale (default: 60)'),
+                dry_run: z.boolean().optional().default(true).describe('Preview only, no archiving (default: true)'),
+            },
+        }, async ({ project_id, days_stale: rawDaysStale, dry_run: rawDryRun }) => {
+            try {
+                const days_stale = rawDaysStale ?? 60;
+                const dry_run = rawDryRun ?? true;
+                if (!dry_run && !hasCookie(config)) {
+                    return toolError('Cookie auth required to archive branches. Run with dry_run=true to preview, or configure cookie auth.');
+                }
+                // Fetch project files
+                const MAX_FILES = 20;
+                let files;
+                if (hasPat(config)) {
+                    const res = await publicClient(config).get(`/v1/projects/${project_id}/files`);
+                    files = res.data?.files || [];
+                }
+                else {
+                    const res = await internalClient(config).get(`/api/folders/${project_id}/paginated_files`, { params: { folderId: project_id, sort_column: 'touched_at', sort_order: 'desc', page_size: MAX_FILES, file_type: '' } });
+                    const meta = res.data?.meta || res.data;
+                    files = meta?.files || meta || [];
+                }
+                // Cap at 20 files
+                const capped = files.length > 20;
+                files = files.slice(0, 20);
+                // Fetch branch data for each file in parallel
+                const cutoff = Date.now() - days_stale * 86400000;
+                const staleBranches = [];
+                const activeBranches = [];
+                let filesScanned = 0;
+                let totalBranches = 0;
+                const branchResults = await Promise.allSettled(files.map(async (file) => {
+                    let branches;
+                    if (hasPat(config)) {
+                        const res = await publicClient(config).get(`/v1/files/${file.key}`, {
+                            params: { branch_data: 'true', depth: '0' },
+                        });
+                        branches = res.data?.branches || [];
+                    }
+                    else {
+                        const res = await internalClient(config).get(`/api/files/${file.key}`);
+                        const f = res.data?.meta || res.data;
+                        branches = f.branches || [];
+                    }
+                    return { file, branches };
+                }));
+                for (const r of branchResults) {
+                    if (r.status === 'rejected')
+                        continue;
+                    filesScanned++;
+                    const { file, branches } = r.value;
+                    for (const branch of branches) {
+                        totalBranches++;
+                        const lastModified = branch.last_modified;
+                        const lastModifiedMs = lastModified ? new Date(lastModified).getTime() : 0;
+                        const isStale = !lastModified || (lastModifiedMs > 0 && lastModifiedMs < cutoff) || isNaN(lastModifiedMs);
+                        const entry = {
+                            branch_key: branch.key,
+                            branch_name: branch.name,
+                            parent_file_key: file.key,
+                            parent_file_name: file.name,
+                            last_modified: lastModified || null,
+                        };
+                        if (isStale) {
+                            staleBranches.push(entry);
+                        }
+                        else {
+                            activeBranches.push(entry);
+                        }
+                    }
+                }
+                const MAX_ARCHIVE_BATCH = 25;
+                let archived = false;
+                if (!dry_run && staleBranches.length > 0) {
+                    if (staleBranches.length > MAX_ARCHIVE_BATCH) {
+                        return toolError(`${staleBranches.length} stale branches exceeds safety limit of ${MAX_ARCHIVE_BATCH}. ` +
+                            `Run with dry_run=true to review, then archive in smaller batches using delete_branch.`);
+                    }
+                    await internalClient(config).delete('/api/files_batch', {
+                        data: {
+                            files: staleBranches.map(b => ({ key: b.branch_key })),
+                            trashed: true,
+                        },
+                    });
+                    archived = true;
+                }
+                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.'}`);
+                }
+                if (capped) {
+                    recommendations.push(`Project has more than 20 files; only the first 20 were scanned.`);
+                }
+                if (staleBranches.length === 0 && activeBranches.length === 0) {
+                    recommendations.push('No branches found in scanned files.');
+                }
+                const result = {
+                    project_id,
+                    summary: {
+                        files_scanned: filesScanned,
+                        total_branches: totalBranches,
+                        stale: staleBranches.length,
+                        active: activeBranches.length,
+                    },
+                    stale_branches: staleBranches,
+                    active_branches: activeBranches,
+                    dry_run,
+                    archived,
+                    recommendations,
+                };
+                return toolResult(JSON.stringify(result, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to cleanup branches: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
 //# sourceMappingURL=compound.js.map

package/dist/tools/org.js

@@ -332,14 +332,15 @@ defineTool({
                 if (search_query)
                     params.search_query = search_query;
                 const res = await internalClient(config).get(`/api/v2/orgs/${orgId}/org_users`, { params });
-                const members = (res.data?.meta || res.data || []).map((m) => ({
+                const users = res.data?.meta?.users || res.data?.meta || res.data || [];
+                const members = (Array.isArray(users) ? users : []).map((m) => ({
                     org_user_id: String(m.id),
                     user_id: m.user_id,
                     email: m.user?.email,
                     name: m.user?.handle,
                     permission: m.permission,
                     seat_type: m.active_seat_type?.key || null,
-                    last_active: m.last_active,
+                    last_active: m.last_seen || null,
                 }));
                 return toolResult(JSON.stringify(members, null, 2));
             }
@@ -436,7 +437,8 @@ defineTool({
                 const res = await internalClient(config).get(`/api/v2/orgs/${orgId}/org_users`, {
                     params: user_id.includes('@') ? { search_query: user_id } : {},
                 });
-                const members = res.data?.meta || res.data || [];
+                const users = res.data?.meta?.users || res.data?.meta || res.data || [];
+                const members = Array.isArray(users) ? users : [];
                 const member = members.find((m) => user_id.includes('@')
                     ? m.user?.email === user_id
                     : String(m.user_id) === String(user_id));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "figmanage",
   "mcpName": "io.github.dannykeane/figmanage",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "MCP server for managing your Figma workspace from the terminal.",
   "type": "module",
   "main": "dist/index.js",