figmanage 1.0.1 → 1.2.0

package/dist/cli/format.js

@@ -2,13 +2,158 @@
 export function isTTY() {
     return process.stdout.isTTY === true;
 }
+/** Get terminal width, defaulting to 80 if unavailable */
+function termWidth() {
+    return process.stdout.columns || 80;
+}
+/** Format a value for display in a table cell */
+function formatCell(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (Array.isArray(value))
+        return `[${value.length} items]`;
+    if (typeof value === 'object')
+        return '{...}';
+    return String(value);
+}
+/** Truncate a string to maxLen, appending ... if truncated */
+function truncate(str, maxLen) {
+    if (maxLen < 4)
+        return str.slice(0, maxLen);
+    if (str.length <= maxLen)
+        return str;
+    return str.slice(0, maxLen - 3) + '...';
+}
+/** Pad a string to the right with spaces */
+function padRight(str, width) {
+    if (str.length >= width)
+        return str;
+    return str + ' '.repeat(width - str.length);
+}
+/**
+ * Render an array of objects as an aligned table.
+ * Columns are auto-sized to content, then shrunk proportionally if they
+ * exceed terminal width. A minimum gap of 2 spaces separates columns.
+ */
+function formatTable(rows) {
+    if (rows.length === 0)
+        return '';
+    // Collect all keys across all rows (preserving insertion order)
+    const keySet = new Set();
+    for (const row of rows) {
+        for (const key of Object.keys(row)) {
+            keySet.add(key);
+        }
+    }
+    const keys = Array.from(keySet);
+    // Build string grid: headers + data
+    const headers = keys.map((k) => k.toUpperCase());
+    const grid = rows.map((row) => keys.map((k) => formatCell(row[k])));
+    // Compute natural column widths (max of header and all data cells)
+    const colWidths = keys.map((_, i) => {
+        let max = headers[i].length;
+        for (const row of grid) {
+            if (row[i].length > max)
+                max = row[i].length;
+        }
+        return max;
+    });
+    const gap = 2;
+    const maxWidth = termWidth();
+    const totalGap = gap * (keys.length - 1);
+    const totalNatural = colWidths.reduce((a, b) => a + b, 0) + totalGap;
+    // If columns exceed terminal width, shrink the widest columns first
+    if (totalNatural > maxWidth && keys.length > 0) {
+        const budget = maxWidth - totalGap;
+        if (budget > 0) {
+            // Give each column at least 4 chars, distribute remaining proportionally
+            const minCol = 4;
+            const guaranteed = Math.min(minCol, Math.floor(budget / keys.length));
+            let remaining = budget;
+            // First pass: cap each column to its natural width or proportional share
+            const totalContent = colWidths.reduce((a, b) => a + b, 0);
+            for (let i = 0; i < colWidths.length; i++) {
+                const share = Math.max(guaranteed, Math.floor((colWidths[i] / totalContent) * budget));
+                colWidths[i] = Math.min(colWidths[i], share);
+                remaining -= colWidths[i];
+            }
+            // Distribute leftover to columns that were truncated
+            if (remaining > 0) {
+                for (let i = 0; i < colWidths.length && remaining > 0; i++) {
+                    const natural = headers[i].length;
+                    const canGrow = Math.max(0, natural - colWidths[i]);
+                    const give = Math.min(canGrow, remaining);
+                    colWidths[i] += give;
+                    remaining -= give;
+                }
+            }
+        }
+    }
+    // Render rows
+    const lines = [];
+    // Header row
+    const headerLine = keys
+        .map((_, i) => padRight(truncate(headers[i], colWidths[i]), colWidths[i]))
+        .join(' '.repeat(gap));
+    lines.push(headerLine.trimEnd());
+    // Data rows
+    for (const row of grid) {
+        const line = keys
+            .map((_, i) => padRight(truncate(row[i], colWidths[i]), colWidths[i]))
+            .join(' '.repeat(gap));
+        lines.push(line.trimEnd());
+    }
+    return lines.join('\n');
+}
+/**
+ * Render a single object as key-value pairs.
+ * Falls back to JSON for deeply nested objects.
+ */
+function formatKeyValue(obj) {
+    // If every value is a nested object/array, this won't be readable as k/v.
+    // Check if the majority of values are complex -- if so, fall back to JSON.
+    const values = Object.values(obj);
+    const complexCount = values.filter((v) => v !== null && typeof v === 'object').length;
+    if (complexCount > values.length / 2) {
+        return JSON.stringify(obj, null, 2);
+    }
+    const entries = Object.entries(obj);
+    if (entries.length === 0)
+        return '{}';
+    return entries.map(([key, val]) => `${key}: ${formatCell(val)}`).join('\n');
+}
 /** Format output: JSON if piped or --json flag, human-readable if TTY */
 export function formatOutput(data, options) {
     if (options.json || !isTTY()) {
         return JSON.stringify(data, null, 2);
     }
-    // Table formatting will be added later; fall back to JSON for now
-    return JSON.stringify(data, null, 2);
+    // Primitives: render as-is
+    if (data === null || data === undefined)
+        return '';
+    if (typeof data === 'string')
+        return data;
+    if (typeof data === 'number' || typeof data === 'boolean')
+        return String(data);
+    // Array of objects: table
+    if (Array.isArray(data)) {
+        if (data.length === 0)
+            return '';
+        // If every element is a plain object, render as table
+        if (data.every((item) => item !== null && typeof item === 'object' && !Array.isArray(item))) {
+            return formatTable(data);
+        }
+        // Array of primitives or mixed: one per line
+        return data.map((item) => formatCell(item)).join('\n');
+    }
+    // Single object
+    if (typeof data === 'object') {
+        return formatKeyValue(data);
+    }
+    return String(data);
 }
 /** Print formatted output to stdout */
 export function output(data, options = {}) {

package/dist/cli/helpers.d.ts

@@ -0,0 +1,7 @@
+import { type AuthConfig } from '../auth/client.js';
+export declare function validateId(value: string, label: string): string;
+export declare function parsePositiveInt(value: string, label: string, fallback: number): number;
+export declare function requireAuth(): AuthConfig;
+export declare function requirePat(): AuthConfig;
+export declare function requireCookie(): AuthConfig;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/cli/helpers.js

@@ -0,0 +1,43 @@
+import { loadAuthConfig, hasPat, hasCookie } from '../auth/client.js';
+import { error } from './format.js';
+const ID_PATTERN = /^[\w.:-]+$/;
+export 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;
+}
+export 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;
+}
+export function requireAuth() {
+    const config = loadAuthConfig();
+    if (!hasPat(config) && !hasCookie(config)) {
+        error('Not authenticated. Run `figmanage login` first.');
+        process.exit(1);
+    }
+    return config;
+}
+export function requirePat() {
+    const config = loadAuthConfig();
+    if (!hasPat(config)) {
+        error('This command requires a Personal Access Token. Run `figmanage login` first.');
+        process.exit(1);
+    }
+    return config;
+}
+export function requireCookie() {
+    const config = loadAuthConfig();
+    if (!hasCookie(config)) {
+        error('This command requires cookie auth. Run `figmanage login` (not --pat-only).');
+        process.exit(1);
+    }
+    return config;
+}
+//# sourceMappingURL=helpers.js.map

package/dist/cli/index.js

@@ -1,5 +1,23 @@
+import { navigateCommand } from './navigate.js';
+import { filesCommand } from './files.js';
+import { projectsCommand } from './projects.js';
+import { permissionsCommand } from './permissions.js';
+import { versionsCommand } from './versions.js';
+import { branchingCommand } from './branching.js';
+import { commentsCommand } from './comments.js';
+import { exportCommand } from './export.js';
+import { readingCommand } from './reading.js';
+import { componentsCommand } from './components.js';
+import { webhooksCommand } from './webhooks.js';
+import { variablesCommand } from './variables.js';
+import { analyticsCommand } from './analytics.js';
+import { orgCommand } from './org.js';
+import { librariesCommand } from './libraries.js';
+import { teamsCommand } from './teams.js';
+import { completionCommand } from './completion.js';
+import { fileSummaryCommand, workspaceOverviewCommand, openCommentsCommand, cleanupStaleFilesCommand, organizeProjectCommand, setupProjectStructureCommand, seatOptimizationCommand, permissionAuditCommand, branchCleanupCommand, offboardUserCommand, onboardUserCommand, quarterlyReportCommand, } from './compound-commands.js';
 export function registerCliCommands(program) {
-    // Auth commands -- handlers live in cli/login.ts (built by another agent)
+    // Auth commands (flat -- not resource-scoped)
     program
         .command('login')
         .description('Authenticate with Figma')
@@ -23,93 +41,54 @@ export function registerCliCommands(program) {
         const { handleLogout } = await import('./login.js');
         await handleLogout();
     });
-    // Workspace management commands
-    program
-        .command('seat-optimization')
-        .description('Identify inactive paid seats and calculate savings')
-        .option('--days-inactive <days>', 'Days threshold (default: 90)', '90')
-        .option('--no-cost', 'Skip cost analysis')
-        .option('--json', 'Force JSON output')
-        .action(async (options) => {
-        const { runSeatOptimization } = await import('./commands.js');
-        await runSeatOptimization(options);
-    });
-    program
-        .command('offboard <user>')
-        .description('Audit or execute user offboarding')
-        .option('--execute', 'Execute the offboarding (default: audit only)')
-        .option('--transfer-to <user>', 'Transfer file ownership to this user')
-        .option('--json', 'Force JSON output')
-        .action(async (user, options) => {
-        const { runOffboard } = await import('./commands.js');
-        await runOffboard(user, options);
-    });
-    program
-        .command('onboard <email>')
-        .description('Invite user to teams and set up access')
-        .option('--teams <ids>', 'Comma-separated team IDs', (v) => v.split(','))
-        .option('--role <role>', 'Role: editor or viewer (default: editor)', 'editor')
-        .option('--share-files <keys>', 'Comma-separated file keys to share (viewer access)', (v) => v.split(','))
-        .option('--seat <type>', 'Seat type: full, dev, collab, view')
-        .option('--confirm', 'Confirm seat change')
-        .option('--json', 'Force JSON output')
-        .action(async (email, options) => {
-        const { runOnboard } = await import('./commands.js');
-        await runOnboard(email, options);
-    });
-    program
-        .command('quarterly-report')
-        .description('Org-wide design ops snapshot')
-        .option('--days <days>', 'Lookback period (default: 90)', '90')
-        .option('--json', 'Force JSON output')
-        .action(async (options) => {
-        const { runQuarterlyReport } = await import('./commands.js');
-        await runQuarterlyReport(options);
-    });
-    program
-        .command('members')
-        .description('List org members')
-        .option('--search <query>', 'Filter by name or email')
-        .option('--json', 'Force JSON output')
-        .action(async (options) => {
-        const { runMembers } = await import('./commands.js');
-        await runMembers(options);
-    });
-    program
-        .command('teams')
-        .description('List org teams')
-        .option('--json', 'Force JSON output')
-        .action(async (options) => {
-        const { runTeams } = await import('./commands.js');
-        await runTeams(options);
-    });
-    program
-        .command('permissions <type> <id>')
-        .description('Show who has access to a file, project, or team')
-        .option('--json', 'Force JSON output')
-        .action(async (type, id, options) => {
-        const { runPermissions } = await import('./commands.js');
-        await runPermissions(type, id, options);
-    });
-    program
-        .command('permission-audit')
-        .description('Audit permissions across a team or project')
-        .option('--scope <type>', 'Scope: team or project', 'team')
-        .option('--id <id>', 'Team or project ID')
-        .option('--json', 'Force JSON output')
-        .action(async (options) => {
-        const { runPermissionAudit } = await import('./commands.js');
-        await runPermissionAudit(options);
-    });
-    program
-        .command('branch-cleanup <project-id>')
-        .description('Find and optionally archive stale branches')
-        .option('--days-stale <days>', 'Days threshold (default: 60)', '60')
-        .option('--execute', 'Archive stale branches (default: dry run)')
-        .option('--json', 'Force JSON output')
-        .action(async (projectId, options) => {
-        const { runBranchCleanup } = await import('./commands.js');
-        await runBranchCleanup(projectId, options);
-    });
+    // Noun-verb subcommand groups
+    const navigate = navigateCommand();
+    const files = filesCommand();
+    const projects = projectsCommand();
+    const permissions = permissionsCommand();
+    const versions = versionsCommand();
+    const branches = branchingCommand();
+    const comments = commentsCommand();
+    const exp = exportCommand();
+    const reading = readingCommand();
+    const components = componentsCommand();
+    const webhooks = webhooksCommand();
+    const variables = variablesCommand();
+    const analytics = analyticsCommand();
+    const org = orgCommand();
+    const libraries = librariesCommand();
+    const teams = teamsCommand();
+    // Route compound commands into noun groups
+    files.addCommand(fileSummaryCommand());
+    files.addCommand(cleanupStaleFilesCommand());
+    projects.addCommand(organizeProjectCommand());
+    projects.addCommand(setupProjectStructureCommand());
+    comments.addCommand(openCommentsCommand());
+    permissions.addCommand(permissionAuditCommand());
+    branches.addCommand(branchCleanupCommand());
+    org.addCommand(workspaceOverviewCommand());
+    org.addCommand(seatOptimizationCommand());
+    org.addCommand(offboardUserCommand());
+    org.addCommand(onboardUserCommand());
+    org.addCommand(quarterlyReportCommand());
+    // Register all groups
+    program.addCommand(navigate);
+    program.addCommand(files);
+    program.addCommand(projects);
+    program.addCommand(permissions);
+    program.addCommand(versions);
+    program.addCommand(branches);
+    program.addCommand(comments);
+    program.addCommand(exp);
+    program.addCommand(reading);
+    program.addCommand(components);
+    program.addCommand(webhooks);
+    program.addCommand(variables);
+    program.addCommand(analytics);
+    program.addCommand(org);
+    program.addCommand(libraries);
+    program.addCommand(teams);
+    // Completion must be registered last so it can introspect all commands above
+    program.addCommand(completionCommand(program));
 }
 //# sourceMappingURL=index.js.map

package/dist/cli/libraries.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function librariesCommand(): Command;
+//# sourceMappingURL=libraries.d.ts.map

package/dist/cli/libraries.js

@@ -0,0 +1,26 @@
+import { Command } from 'commander';
+import { listOrgLibraries } from '../operations/libraries.js';
+import { output, error } from './format.js';
+import { requireCookie } from './helpers.js';
+export function librariesCommand() {
+    const libraries = new Command('libraries')
+        .description('Manage org design system libraries');
+    libraries
+        .command('list')
+        .description('List all design system libraries in the org')
+        .option('--org-id <id>', 'Org ID override (defaults to current workspace)')
+        .option('--json', 'Force JSON output')
+        .action(async (options) => {
+        try {
+            const config = requireCookie();
+            const result = await listOrgLibraries(config, { org_id: options.orgId });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    return libraries;
+}
+//# sourceMappingURL=libraries.js.map

package/dist/cli/navigate.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function navigateCommand(): Command;
+//# sourceMappingURL=navigate.d.ts.map

package/dist/cli/navigate.js

@@ -0,0 +1,192 @@
+import { Command } from 'commander';
+import { checkAuthStatus, listOrgs, switchOrg, listTeams, listProjects, listFiles, listRecentFiles, search, getFileInfo, listFavorites, } from '../operations/navigate.js';
+import { output, error } from './format.js';
+import { requireAuth, requireCookie } from './helpers.js';
+export function navigateCommand() {
+    const nav = new Command('navigate')
+        .description('Browse workspaces, teams, projects, and files');
+    nav
+        .command('check-auth')
+        .description('Check authentication status for PAT and session cookie')
+        .option('--json', 'Force JSON output')
+        .action(async (options) => {
+        try {
+            const config = requireAuth();
+            const result = await checkAuthStatus(config);
+            if (options.json) {
+                output(result.status, options);
+            }
+            else {
+                console.log(result.formatted);
+            }
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    nav
+        .command('list-orgs')
+        .description('List all workspaces you belong to')
+        .option('--json', 'Force JSON output')
+        .action(async (options) => {
+        try {
+            const config = requireCookie();
+            const orgs = await listOrgs(config);
+            if (orgs.length === 0) {
+                console.log('No workspaces found. You may be on a free/starter plan.');
+                return;
+            }
+            output(orgs, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    nav
+        .command('switch-org <org>')
+        .description('Switch active workspace (name or ID)')
+        .option('--json', 'Force JSON output')
+        .action(async (org, options) => {
+        try {
+            const config = requireCookie();
+            const result = await switchOrg(config, { org });
+            output({
+                previous: result.previous,
+                current: result.current,
+            }, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    nav
+        .command('list-teams')
+        .description('List all teams you belong to')
+        .option('--json', 'Force JSON output')
+        .action(async (options) => {
+        try {
+            const config = requireCookie();
+            const teams = await listTeams(config);
+            output(teams, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    nav
+        .command('list-projects <team-id>')
+        .description('List projects (folders) in a team')
+        .option('--json', 'Force JSON output')
+        .action(async (teamId, options) => {
+        try {
+            const config = requireAuth();
+            const projects = await listProjects(config, { team_id: teamId });
+            output(projects, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    nav
+        .command('list-files <project-id>')
+        .description('List files in a project')
+        .option('--page-size <n>', 'Results per page (default 25, max 100)')
+        .option('--page-token <token>', 'Pagination token from previous response')
+        .option('--json', 'Force JSON output')
+        .action(async (projectId, options) => {
+        try {
+            const config = requireAuth();
+            const result = await listFiles(config, {
+                project_id: projectId,
+                page_size: options.pageSize ? parseInt(options.pageSize, 10) : undefined,
+                page_token: options.pageToken,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    nav
+        .command('list-recent-files')
+        .description('List recently viewed/edited files')
+        .option('--json', 'Force JSON output')
+        .action(async (options) => {
+        try {
+            const config = requireCookie();
+            const files = await listRecentFiles(config);
+            output(files, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    nav
+        .command('search <query>')
+        .description('Search for files across the workspace')
+        .option('--sort <order>', 'Sort order: relevancy or last_modified')
+        .option('--org-id <id>', 'Org ID override')
+        .option('--json', 'Force JSON output')
+        .action(async (query, options) => {
+        try {
+            const config = requireCookie();
+            const results = await search(config, {
+                query,
+                sort: options.sort,
+                org_id: options.orgId,
+            });
+            if (results.length === 0) {
+                console.log('No results found.');
+                return;
+            }
+            output(results, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    nav
+        .command('file-info <file-key>')
+        .description('Get metadata for a file')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, options) => {
+        try {
+            const config = requireAuth();
+            const info = await getFileInfo(config, { file_key: fileKey });
+            output(info, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    nav
+        .command('list-favorites')
+        .description('List starred/favorited files')
+        .option('--json', 'Force JSON output')
+        .action(async (options) => {
+        try {
+            const config = requireCookie();
+            const favorites = await listFavorites(config);
+            if (favorites.length === 0) {
+                console.log('No favorites found.');
+                return;
+            }
+            output(favorites, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    return nav;
+}
+//# sourceMappingURL=navigate.js.map

package/dist/cli/org.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function orgCommand(): Command;
+//# sourceMappingURL=org.d.ts.map