figmanage 1.0.1 → 1.2.0

package/dist/cli/commands.js

@@ -1,1204 +0,0 @@
-/**
- * CLI command handlers. Each replicates the API calls from the
- * corresponding MCP tool handler, adapted for CLI output.
- */
-import { loadAuthConfig, hasPat, hasCookie } from '../auth/client.js';
-import { internalClient } from '../clients/internal-api.js';
-import { publicClient } from '../clients/public-api.js';
-import { requireOrgId } from '../tools/register.js';
-import { output, error } from './format.js';
-// -- Shared helpers --
-const ID_PATTERN = /^[\w.:-]+$/;
-function validateId(value, label) {
-    if (!ID_PATTERN.test(value)) {
-        error(`Invalid ${label}: must contain only letters, numbers, hyphens, underscores, dots, or colons.`);
-        process.exit(1);
-    }
-    return value;
-}
-function parsePositiveInt(value, label, fallback) {
-    const n = parseInt(value, 10);
-    if (isNaN(n) || n < 1) {
-        error(`${label} must be a positive number.`);
-        process.exit(1);
-    }
-    return n;
-}
-function requireAuth() {
-    const config = loadAuthConfig();
-    if (!hasPat(config) && !hasCookie(config)) {
-        error('Not authenticated. Run `figmanage login` first.');
-        process.exit(1);
-    }
-    return config;
-}
-function requireCookie() {
-    const config = requireAuth();
-    if (!hasCookie(config)) {
-        error('This command requires cookie auth. Run `figmanage login` (not --pat-only).');
-        process.exit(1);
-    }
-    return config;
-}
-const BATCH_SIZE = 5;
-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;
-}
-const SEAT_KEY_MAP = {
-    expert: 'full',
-    developer: 'dev',
-    collaborator: 'collab',
-};
-const LEVEL_NAMES = { 999: 'owner', 300: 'editor', 100: 'viewer' };
-function levelName(level) {
-    return LEVEL_NAMES[level] || `level:${level}`;
-}
-// -- seat-optimization --
-export async function runSeatOptimization(options) {
-    try {
-        const config = requireCookie();
-        const orgId = requireOrgId(config);
-        const api = internalClient(config);
-        const daysInactive = parsePositiveInt(options.daysInactive || '90', '--days-inactive', 90);
-        const includeCost = options.cost !== false;
-        const cutoff = Date.now() - daysInactive * 86400000;
-        const paidKeys = new Set(['expert', 'developer', 'collaborator']);
-        // Paginate org members (cursor-based)
-        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 (includeCost) {
-            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 (includeCost && 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 ${daysInactive}+ 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,
-        };
-        output(result, options);
-    }
-    catch (e) {
-        error(e.response?.status ? `API error: ${e.response.status}` : e.message);
-        process.exit(1);
-    }
-}
-// -- offboard --
-const MAX_REVOCATIONS = 25;
-export async function runOffboard(user, options) {
-    try {
-        const config = requireCookie();
-        const orgId = requireOrgId(config);
-        const api = internalClient(config);
-        const execute = options.execute === true;
-        // Step 1: Resolve user
-        const userRes = await api.get(`/api/v2/orgs/${orgId}/org_users`, {
-            params: user.includes('@') ? { search_query: user } : {},
-        });
-        const rawUsers = userRes.data?.meta?.users || userRes.data?.meta || userRes.data || [];
-        const members = Array.isArray(rawUsers) ? rawUsers : [];
-        const member = members.find((m) => user.includes('@')
-            ? m.user?.email === user
-            : String(m.user_id) === String(user));
-        if (!member) {
-            error(`User not found: ${user}`);
-            process.exit(1);
-        }
-        const userId = String(member.user_id);
-        // Block self-offboarding
-        if (userId === String(config.userId)) {
-            error('Cannot audit yourself for offboarding.');
-            process.exit(1);
-        }
-        const userInfo = {
-            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 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 (userInfo.seat_type) {
-            transferPlan.push(`Downgrade or remove ${userInfo.seat_type} seat.`);
-        }
-        // Audit-only mode
-        if (!execute) {
-            const result = {
-                user: userInfo,
-                team_memberships: teamMemberships,
-                project_permissions: projectPermissions,
-                file_ownership: fileOwnership,
-                summary,
-                transfer_plan: transferPlan,
-                note: 'Run with --execute to perform offboarding. Use --transfer-to if the user owns files.',
-            };
-            output(result, options);
-            return;
-        }
-        // --- Execute mode ---
-        // Validate: if user owns files, transfer_to is required
-        if (fileOwnership.length > 0 && !options.transferTo) {
-            error(`User owns ${fileOwnership.length} file(s). Use --transfer-to <email|user_id> to transfer ownership before revoking access.`);
-            process.exit(1);
-        }
-        // Resolve transfer_to user
-        let transferToUserId;
-        if (options.transferTo) {
-            const tRes = await api.get(`/api/v2/orgs/${orgId}/org_users`, {
-                params: options.transferTo.includes('@') ? { search_query: options.transferTo } : {},
-            });
-            const tUsers = tRes.data?.meta?.users || tRes.data?.meta || tRes.data || [];
-            const tList = Array.isArray(tUsers) ? tUsers : [];
-            const tMatch = tList.find((m) => options.transferTo.includes('@')
-                ? m.user?.email === options.transferTo
-                : String(m.user_id) === String(options.transferTo));
-            if (!tMatch) {
-                error(`Transfer target not found: ${options.transferTo}`);
-                process.exit(1);
-            }
-            transferToUserId = String(tMatch.user_id);
-        }
-        // Cap total mutations
-        const totalMutations = fileOwnership.length + teamMemberships.length + projectPermissions.length + 1;
-        if (totalMutations > MAX_REVOCATIONS) {
-            error(`Offboarding would require ${totalMutations} mutations (cap: ${MAX_REVOCATIONS}). ` +
-                `Reduce scope or execute manually with revoke_access and set_permissions.`);
-            process.exit(1);
-        }
-        const actions = [];
-        // Step A: Transfer file ownership
-        if (fileOwnership.length > 0 && transferToUserId) {
-            for (const file of fileOwnership) {
-                try {
-                    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);
-                    if (transfereeRole) {
-                        await api.put(`/api/roles/${transfereeRole.id}`, { level: 999 });
-                    }
-                    else {
-                        await api.post('/api/invites', {
-                            resource_type: 'file',
-                            resource_id_or_key: file.file_key,
-                            emails: [options.transferTo],
-                            level: 300,
-                        });
-                        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 });
-                        }
-                    }
-                    if (ownerRole) {
-                        await api.put(`/api/roles/${ownerRole.id}`, { level: 300 });
-                    }
-                    actions.push({ action: 'transfer_ownership', status: 'done', detail: `${file.file_name} -> ${options.transferTo}` });
-                }
-                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 (userInfo.seat_type) {
-            try {
-                const viewStatuses = { collaborator: 'starter', developer: 'starter', expert: 'starter' };
-                await api.put(`/api/orgs/${orgId}/org_users`, {
-                    org_user_ids: [userInfo.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: `${userInfo.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: userInfo,
-            executed: true,
-            actions,
-            summary: { succeeded, failed, total: actions.length },
-            note: failed > 0
-                ? `${failed} action(s) failed. Review and retry manually.`
-                : 'Offboarding complete.',
-        };
-        output(result, options);
-    }
-    catch (e) {
-        error(e.response?.status ? `API error: ${e.response.status}` : e.message);
-        process.exit(1);
-    }
-}
-// -- onboard --
-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 };
-export async function runOnboard(email, options) {
-    try {
-        const config = requireCookie();
-        const orgId = requireOrgId(config);
-        const api = internalClient(config);
-        const teamIds = options.teams || [];
-        if (teamIds.length === 0) {
-            error('At least one team ID is required. Use --teams <id1,id2>.');
-            process.exit(1);
-        }
-        if (teamIds.length > 10) {
-            error(`Too many teams: ${teamIds.length}. Maximum is 10.`);
-            process.exit(1);
-        }
-        for (const id of teamIds)
-            validateId(id, 'team ID');
-        const shareFiles = options.shareFiles || [];
-        if (shareFiles.length > 20) {
-            error(`Too many files: ${shareFiles.length}. Maximum is 20.`);
-            process.exit(1);
-        }
-        for (const key of shareFiles)
-            validateId(key, 'file key');
-        const role = options.role || 'editor';
-        const level = LEVEL_MAP[role] || 300;
-        // 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 = teamIds.filter(id => !orgTeamMap.has(id));
-        if (invalidTeams.length > 0) {
-            error(`Team(s) not found in org: ${invalidTeams.join(', ')}`);
-            process.exit(1);
-        }
-        // Invite to teams (batched)
-        const teamsJoined = [];
-        const teamInviteResults = await batchProcess(teamIds, 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 < teamIds.length; i++) {
-            const r = teamInviteResults[i];
-            teamsJoined.push({
-                team_id: teamIds[i],
-                team_name: orgTeamMap.get(teamIds[i]) || 'unknown',
-                role,
-                status: r.status === 'fulfilled' ? 'invited' : 'failed',
-            });
-        }
-        // Share files (batched, viewer access)
-        const filesShared = [];
-        if (shareFiles.length > 0) {
-            const fileShareResults = await batchProcess(shareFiles, 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 < shareFiles.length; i++) {
-                const r = fileShareResults[i];
-                filesShared.push({
-                    file_key: shareFiles[i],
-                    role: 'viewer',
-                    status: r.status === 'fulfilled' ? 'shared' : 'failed',
-                });
-            }
-        }
-        // Seat change
-        let seatChange = { status: 'skipped', note: 'No seat type specified.' };
-        const seatType = options.seat;
-        if (seatType && options.confirm) {
-            if (!PAID_STATUSES[seatType]) {
-                error(`Invalid seat type: ${seatType}. Must be one of: full, dev, collab, view.`);
-                process.exit(1);
-            }
-            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[seatType],
-                        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 ${seatType}.` };
-                }
-                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 (seatType && !options.confirm) {
-            seatChange = { status: 'skipped', note: `Use --confirm to apply ${seatType} 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.',
-            ],
-        };
-        output(result, options);
-    }
-    catch (e) {
-        error(e.response?.status ? `API error: ${e.response.status}` : e.message);
-        process.exit(1);
-    }
-}
-// -- quarterly-report --
-export async function runQuarterlyReport(options) {
-    try {
-        const config = requireCookie();
-        const orgId = requireOrgId(config);
-        const api = internalClient(config);
-        const days = parsePositiveInt(options.days || '90', '--days', 90);
-        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)
-        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;
-        output(result, options);
-    }
-    catch (e) {
-        error(e.response?.status ? `API error: ${e.response.status}` : e.message);
-        process.exit(1);
-    }
-}
-// -- members --
-export async function runMembers(options) {
-    try {
-        const config = requireCookie();
-        const orgId = requireOrgId(config);
-        const api = internalClient(config);
-        // Paginate org members (cursor-based)
-        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;
-            if (options.search)
-                params.search_query = options.search;
-            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;
-        }
-        const result = allMembers.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_seen || null,
-        }));
-        output(result, options);
-    }
-    catch (e) {
-        error(e.response?.status ? `API error: ${e.response.status}` : e.message);
-        process.exit(1);
-    }
-}
-// -- teams --
-export async function runTeams(options) {
-    try {
-        const config = requireCookie();
-        const orgId = requireOrgId(config);
-        const api = internalClient(config);
-        const res = await api.get(`/api/orgs/${orgId}/teams`, {
-            params: { include_member_count: true, include_project_count: true },
-        });
-        const teamsRaw = res.data?.meta || res.data || [];
-        const teams = (Array.isArray(teamsRaw) ? teamsRaw : []).map((t) => ({
-            team_id: String(t.id),
-            name: t.name,
-            member_count: t.member_count || 0,
-            project_count: t.project_count || 0,
-        }));
-        output(teams, options);
-    }
-    catch (e) {
-        error(e.response?.status ? `API error: ${e.response.status}` : e.message);
-        process.exit(1);
-    }
-}
-// -- permissions --
-export async function runPermissions(type, id, options) {
-    try {
-        const validTypes = ['file', 'folder', 'team'];
-        if (!validTypes.includes(type)) {
-            error(`Invalid type: ${type}. Must be one of: ${validTypes.join(', ')}`);
-            process.exit(1);
-        }
-        validateId(id, 'resource ID');
-        const config = requireCookie();
-        const api = internalClient(config);
-        const res = await api.get(`/api/roles/${type}/${id}`);
-        const roles = Array.isArray(res.data?.meta) ? res.data.meta : [];
-        const result = roles.map((r) => ({
-            user_id: r.user_id ? String(r.user_id) : null,
-            email: r.user?.email || r.pending_email || null,
-            name: r.user?.handle || null,
-            role: levelName(r.level),
-            level: r.level,
-        }));
-        output(result, options);
-    }
-    catch (e) {
-        error(e.response?.status ? `API error: ${e.response.status}` : e.message);
-        process.exit(1);
-    }
-}
-// -- permission-audit --
-export async function runPermissionAudit(options) {
-    try {
-        if (!options.id) {
-            error('--id is required. Provide a team or project ID.');
-            process.exit(1);
-        }
-        validateId(options.id, 'scope ID');
-        const scopeType = options.scope || 'team';
-        if (scopeType !== 'team' && scopeType !== 'project') {
-            error(`Invalid scope: ${scopeType}. Must be "team" or "project".`);
-            process.exit(1);
-        }
-        const config = requireCookie();
-        const api = internalClient(config);
-        // Resolve org for domain lookup
-        let orgId;
-        let domainCheckSkipped = false;
-        try {
-            orgId = requireOrgId(config);
-        }
-        catch {
-            domainCheckSkipped = true;
-        }
-        // Fetch org verified domains for external detection
-        let verifiedDomains = new Set();
-        if (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 */ }
-        }
-        // Collect file keys to scan
-        let fileKeys = [];
-        const scopeId = options.id;
-        if (scopeType === 'team') {
-            const projectsRes = await api.get(`/api/teams/${scopeId}/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 {
-            const filesRes = await api.get(`/api/folders/${scopeId}/paginated_files`, {
-                params: { folderId: scopeId, 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 roleName = 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 u = allUsers.get(userId);
-                        u.files_accessed.push({
-                            file_key: file.key,
-                            file_name: file.name,
-                            role: roleName,
-                        });
-                    }
-                    // External editor detection
-                    if (email && verifiedDomains.size > 0) {
-                        const domain = email.split('@')[1]?.toLowerCase();
-                        if (domain && !verifiedDomains.has(domain) && (roleName === 'editor' || roleName === 'owner')) {
-                            flags.push({
-                                severity: 'high',
-                                type: 'external_editor',
-                                details: `${email} (external) has ${roleName} 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: scopeType, id: scopeId },
-            summary: {
-                unique_users: allUsers.size,
-                files_scanned: filesScanned,
-                total_files: fileKeys.length,
-                flags_found: flags.length,
-            },
-            users: Array.from(allUsers.values()),
-            flags,
-        };
-        output(result, options);
-    }
-    catch (e) {
-        error(e.response?.status ? `API error: ${e.response.status}` : e.message);
-        process.exit(1);
-    }
-}
-// -- branch-cleanup --
-export async function runBranchCleanup(projectId, options) {
-    try {
-        validateId(projectId, 'project ID');
-        const config = requireAuth();
-        const daysStale = parsePositiveInt(options.daysStale || '60', '--days-stale', 60);
-        const dryRun = !options.execute;
-        if (!dryRun && !hasCookie(config)) {
-            error('Cookie auth required to archive branches. Omit --execute to preview, or run `figmanage login`.');
-            process.exit(1);
-        }
-        // Fetch project files
-        const MAX_FILES = 20;
-        let files;
-        if (hasPat(config)) {
-            const res = await publicClient(config).get(`/v1/projects/${projectId}/files`);
-            files = res.data?.files || [];
-        }
-        else {
-            const res = await internalClient(config).get(`/api/folders/${projectId}/paginated_files`, { params: { folderId: projectId, sort_column: 'touched_at', sort_order: 'desc', page_size: MAX_FILES, file_type: '' } });
-            const meta = res.data?.meta || res.data;
-            files = meta?.files || meta || [];
-        }
-        const capped = files.length > 20;
-        files = files.slice(0, 20);
-        // Fetch branch data for each file in parallel
-        const cutoff = Date.now() - daysStale * 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 (!dryRun && staleBranches.length > 0) {
-            if (staleBranches.length > MAX_ARCHIVE_BATCH) {
-                error(`${staleBranches.length} stale branches exceeds safety limit of ${MAX_ARCHIVE_BATCH}. ` +
-                    `Omit --execute to review, then archive in smaller batches.`);
-                process.exit(1);
-            }
-            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 ${daysStale}+ days. ${dryRun ? 'Use --execute 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: projectId,
-            summary: {
-                files_scanned: filesScanned,
-                total_branches: totalBranches,
-                stale: staleBranches.length,
-                active: activeBranches.length,
-            },
-            stale_branches: staleBranches,
-            active_branches: activeBranches,
-            dry_run: dryRun,
-            archived,
-            recommendations,
-        };
-        output(result, options);
-    }
-    catch (e) {
-        error(e.response?.status ? `API error: ${e.response.status}` : e.message);
-        process.exit(1);
-    }
-}
-//# sourceMappingURL=commands.js.map