figmanage 0.3.0 → 1.0.1

package/dist/cli/format.d.ts

@@ -0,0 +1,13 @@
+/** Check if stdout is a TTY (interactive terminal) */
+export declare function isTTY(): boolean;
+/** Format output: JSON if piped or --json flag, human-readable if TTY */
+export declare function formatOutput(data: unknown, options: {
+    json?: boolean;
+}): string;
+/** Print formatted output to stdout */
+export declare function output(data: unknown, options?: {
+    json?: boolean;
+}): void;
+/** Print error message to stderr */
+export declare function error(message: string): void;
+//# sourceMappingURL=format.d.ts.map

package/dist/cli/format.js

@@ -0,0 +1,21 @@
+/** Check if stdout is a TTY (interactive terminal) */
+export function isTTY() {
+    return process.stdout.isTTY === true;
+}
+/** 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);
+}
+/** Print formatted output to stdout */
+export function output(data, options = {}) {
+    console.log(formatOutput(data, options));
+}
+/** Print error message to stderr */
+export function error(message) {
+    console.error(`error: ${message}`);
+}
+//# sourceMappingURL=format.js.map

package/dist/cli/index.d.ts

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

package/dist/cli/index.js

@@ -0,0 +1,115 @@
+export function registerCliCommands(program) {
+    // Auth commands -- handlers live in cli/login.ts (built by another agent)
+    program
+        .command('login')
+        .description('Authenticate with Figma')
+        .option('--refresh', 'Refresh cookie only')
+        .option('--pat-only', 'PAT authentication only')
+        .action(async (options) => {
+        const { handleLogin } = await import('./login.js');
+        await handleLogin(options);
+    });
+    program
+        .command('whoami')
+        .description('Show current authentication status')
+        .action(async () => {
+        const { handleWhoami } = await import('./whoami.js');
+        await handleWhoami();
+    });
+    program
+        .command('logout')
+        .description('Clear stored credentials')
+        .action(async () => {
+        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);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/login.d.ts

@@ -0,0 +1,7 @@
+export interface LoginOptions {
+    refresh?: boolean;
+    patOnly?: boolean;
+}
+export declare function handleLogin(options?: LoginOptions): Promise<void>;
+export declare function handleLogout(): Promise<void>;
+//# sourceMappingURL=login.d.ts.map

package/dist/cli/login.js

@@ -0,0 +1,135 @@
+import { createInterface } from 'node:readline';
+import { platform } from 'node:os';
+import { setActiveWorkspace, deleteConfig, getConfigPath } from '../config.js';
+import { extractCookies, validateSession, validatePat } from '../auth/cookie.js';
+async function prompt(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise(resolve => rl.question(question, resolve));
+    rl.close();
+    return answer.trim();
+}
+export async function handleLogin(options = {}) {
+    const workspace = {};
+    const os = platform();
+    // Cookie extraction (unless --pat-only)
+    if (!options.patOnly) {
+        if (os !== 'darwin' && os !== 'linux' && os !== 'win32') {
+            console.log(`Cookie extraction not supported on ${os}. Use --pat-only.`);
+        }
+        else {
+            const promptLabel = os === 'darwin' ? ' (Keychain prompt may appear)' : '';
+            console.log(`Reading Chrome cookies${promptLabel}...`);
+            try {
+                const accounts = extractCookies();
+                if (accounts.length === 0) {
+                    if (os === 'win32') {
+                        console.log('  No Figma cookies extracted. Windows extraction is best-effort.');
+                    }
+                    else {
+                        console.log('  No Figma cookies found. Log into figma.com in Chrome.');
+                    }
+                }
+                else {
+                    // Pick account if multiple
+                    let selected = accounts[0];
+                    if (accounts.length > 1) {
+                        console.log(`\n  Found ${accounts.length} Figma accounts:\n`);
+                        for (let i = 0; i < accounts.length; i++) {
+                            console.log(`  [${i + 1}] User ${accounts[i].userId} (${accounts[i].profile})`);
+                        }
+                        const answer = await prompt(`\n  Select account [1-${accounts.length}]: `);
+                        const idx = parseInt(answer, 10) - 1;
+                        if (idx < 0 || idx >= accounts.length) {
+                            console.error('  Invalid selection.');
+                            process.exit(1);
+                        }
+                        selected = accounts[idx];
+                    }
+                    console.log(`  Cookie found for user ${selected.userId}`);
+                    // Validate session and detect org
+                    console.log('Validating session...');
+                    try {
+                        const session = await validateSession(selected.cookieValue, selected.userId);
+                        console.log(`  Session valid (user ${selected.userId})`);
+                        if (session.teams.length > 0) {
+                            console.log(`  Teams: ${session.teams.map(t => t.name).join(', ')}`);
+                        }
+                        workspace.cookie = selected.cookieValue;
+                        workspace.user_id = selected.userId;
+                        workspace.cookie_extracted_at = new Date().toISOString();
+                        // Org selection
+                        let orgId = session.orgId;
+                        if (session.orgs.length > 1) {
+                            console.log(`\n  Found ${session.orgs.length} workspaces:\n`);
+                            for (let i = 0; i < session.orgs.length; i++) {
+                                const o = session.orgs[i];
+                                const marker = o.id === orgId ? ' (current)' : '';
+                                console.log(`  [${i + 1}] ${o.name} (${o.id})${marker}`);
+                            }
+                            const answer = await prompt(`\n  Default workspace [1-${session.orgs.length}] (Enter for 1): `);
+                            if (answer) {
+                                const idx = parseInt(answer, 10) - 1;
+                                if (idx >= 0 && idx < session.orgs.length) {
+                                    orgId = session.orgs[idx].id;
+                                }
+                            }
+                        }
+                        if (orgId) {
+                            workspace.org_id = orgId;
+                            const orgName = session.orgs.find(o => o.id === orgId)?.name;
+                            console.log(`  Workspace: ${orgName ? `${orgName} (${orgId})` : orgId}`);
+                        }
+                    }
+                    catch (e) {
+                        const status = e.response?.status;
+                        if (status === 401 || status === 403) {
+                            console.error('  Cookie expired. Log into figma.com in Chrome and try again.');
+                        }
+                        else {
+                            console.error(`  Session validation failed: ${e.message}`);
+                        }
+                        // Continue to PAT prompt -- cookie failed but PAT might work
+                    }
+                }
+            }
+            catch (e) {
+                if (os === 'win32') {
+                    console.log(`  Cookie extraction failed: ${e.message}`);
+                }
+                else {
+                    console.error(`  Cookie extraction failed: ${e.message}`);
+                }
+            }
+        }
+    }
+    // PAT prompt
+    console.log('\nA Personal Access Token enables comments, export, and version history.');
+    console.log('Generate one at: https://www.figma.com/settings (Security > Personal access tokens)');
+    const patInput = await prompt('Paste your PAT (or press Enter to skip): ');
+    if (patInput) {
+        console.log('Validating PAT...');
+        try {
+            const patUser = await validatePat(patInput);
+            console.log(`  PAT valid (${patUser})`);
+            workspace.pat = patInput;
+        }
+        catch {
+            console.log('  PAT invalid or expired -- skipping.');
+        }
+    }
+    // Must have at least one credential
+    if (!workspace.pat && !workspace.cookie) {
+        console.error('\nNo credentials configured. Need at least a PAT or browser cookie.');
+        process.exit(1);
+    }
+    // Derive a workspace name from the org or user
+    const workspaceName = workspace.org_id || workspace.user_id || 'default';
+    setActiveWorkspace(workspaceName, workspace);
+    console.log(`\nCredentials saved to ${getConfigPath()}`);
+    console.log('Done. figmanage will use these credentials automatically.');
+}
+export async function handleLogout() {
+    deleteConfig();
+    console.log('Logged out. Config file removed.');
+}
+//# sourceMappingURL=login.js.map

package/dist/cli/whoami.d.ts

@@ -0,0 +1,2 @@
+export declare function handleWhoami(): Promise<void>;
+//# sourceMappingURL=whoami.d.ts.map

package/dist/cli/whoami.js

@@ -0,0 +1,68 @@
+import axios from 'axios';
+import { loadAuthConfig, hasPat, hasCookie } from '../auth/client.js';
+export async function handleWhoami() {
+    const config = loadAuthConfig();
+    if (!hasPat(config) && !hasCookie(config)) {
+        console.error('No auth configured. Run `figmanage login` or set environment variables.');
+        process.exit(1);
+    }
+    const authMethods = [];
+    // Cookie auth: call internal API /api/me
+    if (hasCookie(config)) {
+        authMethods.push('cookie');
+        try {
+            const res = await axios.get('https://www.figma.com/api/user/state', {
+                headers: {
+                    'Cookie': `__Host-figma.authn=${config.cookie}`,
+                    'X-CSRF-Bypass': 'yes',
+                    'X-Figma-User-Id': config.userId || '',
+                },
+                timeout: 15000,
+            });
+            const meta = res.data?.meta || res.data || {};
+            const user = meta.user || meta;
+            console.log(`User:  ${user.handle || user.email || config.userId}`);
+            if (user.email)
+                console.log(`Email: ${user.email}`);
+        }
+        catch (e) {
+            const status = e.response?.status;
+            if (status === 401 || status === 403) {
+                console.log('Cookie: expired or invalid');
+            }
+            else {
+                console.log(`Cookie: request failed (${e.message})`);
+            }
+        }
+    }
+    // PAT auth: call public API /v1/me
+    if (hasPat(config)) {
+        authMethods.push('PAT');
+        try {
+            const res = await axios.get('https://api.figma.com/v1/me', {
+                headers: { 'X-Figma-Token': config.pat },
+                timeout: 15000,
+            });
+            const user = res.data;
+            // Only print user info if we didn't already from cookie
+            if (!hasCookie(config)) {
+                console.log(`User:  ${user.handle || user.email}`);
+                if (user.email)
+                    console.log(`Email: ${user.email}`);
+            }
+        }
+        catch (e) {
+            const status = e.response?.status;
+            if (status === 401 || status === 403) {
+                console.log('PAT:   expired or invalid');
+            }
+            else {
+                console.log(`PAT:   request failed (${e.message})`);
+            }
+        }
+    }
+    if (config.orgId)
+        console.log(`Org:   ${config.orgId}`);
+    console.log(`Auth:  ${authMethods.join(' + ')}`);
+}
+//# sourceMappingURL=whoami.js.map

package/dist/config.d.ts

@@ -0,0 +1,35 @@
+export interface WorkspaceConfig {
+    cookie?: string;
+    user_id?: string;
+    org_id?: string;
+    pat?: string;
+    cookie_extracted_at?: string;
+}
+export interface FigmanageConfig {
+    workspaces: Record<string, WorkspaceConfig>;
+    active_workspace: string;
+}
+export declare function getConfigDir(): string;
+export declare function getConfigPath(): string;
+/**
+ * Read and parse the config file. Returns null if not found or malformed.
+ */
+export declare function readConfig(): FigmanageConfig | null;
+/**
+ * Write config to disk with restricted permissions (0o600).
+ * Creates the config directory if it doesn't exist.
+ */
+export declare function writeConfig(config: FigmanageConfig): void;
+/**
+ * Return the active workspace entry, or null if no config or workspace found.
+ */
+export declare function getActiveWorkspace(): WorkspaceConfig | null;
+/**
+ * Set or update a workspace entry and make it active. Merges with existing config.
+ */
+export declare function setActiveWorkspace(name: string, workspace: WorkspaceConfig): void;
+/**
+ * Delete the config file. No-op if it doesn't exist.
+ */
+export declare function deleteConfig(): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -0,0 +1,83 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, chmodSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export function getConfigDir() {
+    if (process.platform === 'win32' && process.env.APPDATA) {
+        return join(process.env.APPDATA, 'figmanage');
+    }
+    return join(homedir(), '.config', 'figmanage');
+}
+export function getConfigPath() {
+    return join(getConfigDir(), 'config.json');
+}
+/**
+ * Read and parse the config file. Returns null if not found or malformed.
+ */
+export function readConfig() {
+    const configPath = getConfigPath();
+    if (!existsSync(configPath))
+        return null;
+    try {
+        const raw = readFileSync(configPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        // Basic shape validation
+        if (typeof parsed !== 'object' ||
+            parsed === null ||
+            typeof parsed.workspaces !== 'object' ||
+            parsed.workspaces === null ||
+            typeof parsed.active_workspace !== 'string') {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write config to disk with restricted permissions (0o600).
+ * Creates the config directory if it doesn't exist.
+ */
+export function writeConfig(config) {
+    const configDir = getConfigDir();
+    mkdirSync(configDir, { recursive: true, mode: 0o700 });
+    const configPath = getConfigPath();
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+    // Ensure permissions even if file pre-existed with broader mode
+    if (process.platform !== 'win32') {
+        chmodSync(configPath, 0o600);
+    }
+}
+/**
+ * Return the active workspace entry, or null if no config or workspace found.
+ */
+export function getActiveWorkspace() {
+    const config = readConfig();
+    if (!config)
+        return null;
+    const workspace = config.workspaces[config.active_workspace];
+    return workspace ?? null;
+}
+/**
+ * Set or update a workspace entry and make it active. Merges with existing config.
+ */
+export function setActiveWorkspace(name, workspace) {
+    const existing = readConfig() ?? { workspaces: {}, active_workspace: name };
+    existing.workspaces[name] = workspace;
+    existing.active_workspace = name;
+    writeConfig(existing);
+}
+/**
+ * Delete the config file. No-op if it doesn't exist.
+ */
+export function deleteConfig() {
+    const configPath = getConfigPath();
+    try {
+        unlinkSync(configPath);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/index.d.ts

@@ -1,20 +1,3 @@
 #!/usr/bin/env node
-import './tools/navigate.js';
-import './tools/files.js';
-import './tools/projects.js';
-import './tools/permissions.js';
-import './tools/comments.js';
-import './tools/export.js';
-import './tools/versions.js';
-import './tools/branching.js';
-import './tools/components.js';
-import './tools/webhooks.js';
-import './tools/reading.js';
-import './tools/analytics.js';
-import './tools/variables.js';
-import './tools/org.js';
-import './tools/libraries.js';
-import './tools/teams.js';
-import './tools/compound.js';
-import './tools/compound-manager.js';
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,106 +1,34 @@
 #!/usr/bin/env node
-// Run setup if --setup flag is present
+// --setup flag: run the interactive setup wizard and exit.
+// Checked before commander parses to preserve existing behavior
+// (setup uses its own interactive prompts).
 if (process.argv.includes('--setup')) {
     await import('./setup.js');
     process.exit(0);
 }
-import { createServer } from 'node:http';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { loadAuthConfig, hasPat, hasCookie } from './auth/client.js';
-import { registerTools } from './tools/register.js';
-// Import tool modules (side-effect: registers via defineTool)
-import './tools/navigate.js';
-import './tools/files.js';
-import './tools/projects.js';
-import './tools/permissions.js';
-import './tools/comments.js';
-import './tools/export.js';
-import './tools/versions.js';
-import './tools/branching.js';
-import './tools/components.js';
-import './tools/webhooks.js';
-import './tools/reading.js';
-import './tools/analytics.js';
-import './tools/variables.js';
-import './tools/org.js';
-import './tools/libraries.js';
-import './tools/teams.js';
-import './tools/compound.js';
-import './tools/compound-manager.js';
-const ALL_TOOLSETS = [
-    'navigate', 'files', 'projects', 'permissions', 'org',
-    'versions', 'branching', 'comments', 'export',
-    'analytics', 'reading', 'components', 'webhooks', 'variables',
-    'compound', 'teams', 'libraries',
-];
-const TOOLSET_PRESETS = {
-    starter: ['navigate', 'reading', 'comments', 'export'],
-    admin: ['navigate', 'org', 'permissions', 'analytics', 'teams', 'libraries'],
-    readonly: ['navigate', 'reading', 'comments', 'export', 'components', 'versions'],
-    full: ALL_TOOLSETS,
-};
-function parseToolsets(env) {
-    if (!env)
-        return new Set(ALL_TOOLSETS);
-    if (env in TOOLSET_PRESETS)
-        return new Set(TOOLSET_PRESETS[env]);
-    const requested = env.split(',').map(s => s.trim());
-    const valid = requested.filter(t => ALL_TOOLSETS.includes(t));
-    return new Set(valid.length > 0 ? valid : ALL_TOOLSETS);
+// --mcp flag: start the MCP server (stdio or HTTP).
+// This is the hot path for MCP clients -- tool modules are only
+// loaded inside startMcpServer(), keeping CLI startup fast.
+if (process.argv.includes('--mcp')) {
+    const { startMcpServer } = await import('./mcp.js');
+    await startMcpServer();
 }
-function parseHttpPort(argv) {
-    const idx = argv.indexOf('--http');
-    if (idx === -1)
-        return undefined;
-    const port = Number(argv[idx + 1]);
-    if (!port || port < 1 || port > 65535) {
-        console.error('--http requires a valid port number (1-65535)');
-        process.exit(1);
+else {
+    // CLI mode: parse commands with commander
+    const { Command } = await import('commander');
+    const { registerCliCommands } = await import('./cli/index.js');
+    const program = new Command();
+    program
+        .name('figmanage')
+        .description('Figma workspace management CLI')
+        .version(JSON.parse((await import('node:fs')).readFileSync(new URL('../package.json', import.meta.url), 'utf-8')).version);
+    registerCliCommands(program);
+    // No subcommand given -- show help
+    if (process.argv.length <= 2) {
+        program.outputHelp();
+        process.exit(0);
     }
-    return port;
+    await program.parseAsync(process.argv);
 }
-async function main() {
-    const config = loadAuthConfig();
-    const readOnly = process.env.FIGMA_READ_ONLY === '1' || process.env.FIGMA_READ_ONLY === 'true';
-    const enabledToolsets = parseToolsets(process.env.FIGMA_TOOLSETS);
-    if (!hasPat(config) && !hasCookie(config)) {
-        console.error('No auth configured. Set FIGMA_PAT for public API access, or ' +
-            'FIGMA_AUTH_COOKIE + FIGMA_USER_ID for internal API access.');
-        process.exit(1);
-    }
-    const server = new McpServer({
-        name: 'figmanage',
-        version: '0.1.0',
-    });
-    registerTools(server, config, enabledToolsets, readOnly);
-    const httpPort = parseHttpPort(process.argv);
-    if (httpPort) {
-        const transport = new StreamableHTTPServerTransport({
-            sessionIdGenerator: undefined,
-        });
-        const httpServer = createServer(async (req, res) => {
-            const url = new URL(req.url ?? '/', `http://localhost:${httpPort}`);
-            if (url.pathname === '/mcp') {
-                await transport.handleRequest(req, res);
-            }
-            else {
-                res.writeHead(404).end('Not found');
-            }
-        });
-        await server.connect(transport);
-        httpServer.listen(httpPort, () => {
-            console.error(`figmanage HTTP server listening on http://localhost:${httpPort}/mcp`);
-        });
-    }
-    else {
-        const transport = new StdioServerTransport();
-        await server.connect(transport);
-    }
-}
-main().catch((err) => {
-    console.error('Fatal:', err);
-    process.exit(1);
-});
+export {};
 //# sourceMappingURL=index.js.map