figmanage 0.2.1 → 1.0.0

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": "1.0.0",
   "description": "MCP server for managing your Figma workspace from the terminal.",
   "type": "module",
   "main": "dist/index.js",
@@ -43,6 +43,7 @@
     "@modelcontextprotocol/sdk": "^1.25.0",
     "axios": "^1.7.0",
     "axios-retry": "^4.4.0",
+    "commander": "^14.0.3",
     "zod": "^3.23.0"
   },
   "devDependencies": {