@spectratools/figma-cli 0.2.0 → 0.3.0

package/dist/index.js

@@ -2,32 +2,13 @@
 
 // src/cli.ts
 import { readFileSync, realpathSync } from "fs";
-import { dirname, resolve } from "path";
+import { dirname, resolve as resolve2 } from "path";
 import { fileURLToPath } from "url";
 import { initTelemetry, shutdownTelemetry } from "@spectratools/cli-shared/telemetry";
-import { Cli } from "incur";
-var __dirname = dirname(fileURLToPath(import.meta.url));
-var pkg = JSON.parse(readFileSync(resolve(__dirname, "../package.json"), "utf8"));
-var cli = Cli.create("figma", {
-  version: pkg.version,
-  description: "Query Figma REST API data from the command line."
-});
-var isMain = (() => {
-  const entrypoint = process.argv[1];
-  if (!entrypoint) {
-    return false;
-  }
-  try {
-    return realpathSync(entrypoint) === realpathSync(fileURLToPath(import.meta.url));
-  } catch {
-    return false;
-  }
-})();
-if (isMain) {
-  initTelemetry("figma");
-  process.on("beforeExit", () => shutdownTelemetry());
-  cli.serve();
-}
+import { Cli as Cli7 } from "incur";
+
+// src/commands/comments.ts
+import { Cli, z as z4 } from "incur";
 
 // src/api.ts
 import {
@@ -61,12 +42,18 @@ var styleSchema = z.object({
   style_type: z.string(),
   description: z.string().optional()
 });
+var clientMetaSchema = z.object({
+  node_id: z.string().optional(),
+  node_offset: z.object({ x: z.number(), y: z.number() }).optional()
+}).optional();
 var commentSchema = z.object({
   id: z.string(),
   message: z.string(),
   created_at: z.string(),
+  resolved_at: z.string().nullable().optional(),
   user: userSchema,
-  order_id: z.union([z.string(), z.number()]).optional()
+  order_id: z.union([z.string(), z.number()]).optional(),
+  client_meta: clientMetaSchema
 });
 var fileMetaSchema = z.object({
   name: z.string(),
@@ -189,13 +176,1010 @@ function createFigmaClient(apiKey) {
   };
 }
 
+// src/commands/_common.ts
+import { z as z3 } from "incur";
+
 // src/auth.ts
 import { z as z2 } from "incur";
 var figmaEnv = z2.object({
   FIGMA_API_KEY: z2.string().describe("Figma personal access token")
 });
+
+// src/commands/_common.ts
+var fileKeyArg = z3.string().describe("Figma file key (from the file URL)");
+var formatOption = z3.enum(["json", "table"]).default("json").describe("Output format: json or table");
+function outputFormatter(data, format) {
+  if (format === "json") {
+    return JSON.stringify(data, null, 2);
+  }
+  const rows = Array.isArray(data) ? data : [data];
+  if (rows.length === 0) return "(no data)";
+  const keys = Object.keys(rows[0]);
+  const widths = keys.map((k) => Math.max(k.length, ...rows.map((r) => String(r[k] ?? "").length)));
+  const header = keys.map((k, i) => k.padEnd(widths[i])).join("  ");
+  const separator = widths.map((w) => "-".repeat(w)).join("  ");
+  const body = rows.map((r) => keys.map((k, i) => String(r[k] ?? "").padEnd(widths[i])).join("  ")).join("\n");
+  return `${header}
+${separator}
+${body}`;
+}
+
+// src/commands/comments.ts
+var commentsCli = Cli.create("comments", {
+  description: "List and post comments on Figma files."
+});
+commentsCli.command("list", {
+  description: "List all comments on a Figma file.",
+  args: z4.object({ fileKey: fileKeyArg }),
+  options: z4.object({ format: formatOption }),
+  env: figmaEnv,
+  output: z4.unknown(),
+  examples: [
+    {
+      args: { fileKey: "abc123" },
+      options: { format: "json" },
+      description: "List comments as JSON"
+    },
+    {
+      args: { fileKey: "abc123" },
+      options: { format: "table" },
+      description: "List comments as table"
+    }
+  ],
+  async run(c) {
+    const fileKey = c.args.fileKey;
+    const client = createFigmaClient(c.env.FIGMA_API_KEY);
+    const response = await client.getComments(fileKey);
+    const comments = response.comments.map((comment) => ({
+      id: comment.id,
+      author: comment.user.handle,
+      message: comment.message,
+      createdAt: comment.created_at,
+      resolved: comment.resolved_at != null,
+      nodeId: comment.client_meta?.node_id ?? null
+    }));
+    if (comments.length === 0) {
+      return c.ok(
+        c.options.format === "json" ? { comments: [], message: "No comments found." } : "No comments found."
+      );
+    }
+    if (c.options.format === "json") {
+      return c.ok({ comments, total: comments.length });
+    }
+    return c.ok(
+      outputFormatter(
+        comments.map((co) => ({
+          id: co.id,
+          author: co.author,
+          message: co.message.length > 50 ? `${co.message.slice(0, 47)}...` : co.message,
+          createdAt: co.createdAt,
+          resolved: co.resolved ? "yes" : "no",
+          nodeId: co.nodeId ?? "-"
+        })),
+        "table"
+      )
+    );
+  }
+});
+commentsCli.command("post", {
+  description: "Post a comment on a Figma file.",
+  args: z4.object({ fileKey: fileKeyArg }),
+  options: z4.object({
+    message: z4.string().describe("Comment text (required)"),
+    "node-id": z4.string().optional().describe("Pin comment to a specific node ID")
+  }),
+  env: figmaEnv,
+  output: z4.unknown(),
+  examples: [
+    {
+      args: { fileKey: "abc123" },
+      options: { message: "Looks good!" },
+      description: "Post a general comment"
+    },
+    {
+      args: { fileKey: "abc123" },
+      options: { message: "Check this spacing", "node-id": "1:42" },
+      description: "Post a comment pinned to a node"
+    }
+  ],
+  async run(c) {
+    const fileKey = c.args.fileKey;
+    const { message, "node-id": nodeId } = c.options;
+    if (!message || message.trim().length === 0) {
+      return c.error({
+        code: "VALIDATION_ERROR",
+        message: "--message is required and cannot be empty"
+      });
+    }
+    const client = createFigmaClient(c.env.FIGMA_API_KEY);
+    const comment = await client.postComment(fileKey, message, nodeId);
+    return c.ok({
+      id: comment.id,
+      message: comment.message,
+      author: comment.user.handle,
+      createdAt: comment.created_at,
+      permalink: `https://www.figma.com/file/${fileKey}?comment=${comment.id}`
+    });
+  }
+});
+
+// src/commands/components.ts
+import { Cli as Cli2, z as z5 } from "incur";
+var componentsCli = Cli2.create("components", {
+  description: "List and inspect published Figma components."
+});
+var componentOutputSchema = z5.object({
+  key: z5.string(),
+  name: z5.string(),
+  description: z5.string()
+});
+componentsCli.command("list", {
+  description: "List published components in a Figma file.",
+  args: z5.object({
+    fileKey: z5.string().describe("Figma file key")
+  }),
+  options: z5.object({}),
+  env: figmaEnv,
+  output: z5.object({
+    components: z5.array(componentOutputSchema),
+    total: z5.number()
+  }),
+  examples: [
+    {
+      args: { fileKey: "abc123FileKey" },
+      options: {},
+      description: "List all published components"
+    }
+  ],
+  async run(c) {
+    const { fileKey } = c.args;
+    const client = createFigmaClient(c.env.FIGMA_API_KEY);
+    const response = await client.getFileComponents(fileKey);
+    const components = response.meta.components;
+    return c.ok(
+      {
+        components: components.map((comp) => ({
+          key: comp.key,
+          name: comp.name,
+          description: comp.description
+        })),
+        total: components.length
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          commands: components.length > 0 ? [
+            {
+              command: `components get ${fileKey} ${components[0]?.key}`,
+              description: `Get details for "${components[0]?.name}"`
+            }
+          ] : [
+            {
+              command: `tokens export ${fileKey}`,
+              description: "Export design tokens from this file"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+componentsCli.command("get", {
+  description: "Get details for a specific published component.",
+  args: z5.object({
+    fileKey: z5.string().describe("Figma file key"),
+    componentKey: z5.string().describe("Component key")
+  }),
+  options: z5.object({}),
+  env: figmaEnv,
+  output: z5.object({
+    key: z5.string(),
+    name: z5.string(),
+    description: z5.string(),
+    found: z5.boolean()
+  }),
+  examples: [
+    {
+      args: { fileKey: "abc123FileKey", componentKey: "comp:456" },
+      options: {},
+      description: "Get details for a specific component"
+    }
+  ],
+  async run(c) {
+    const { fileKey, componentKey } = c.args;
+    const client = createFigmaClient(c.env.FIGMA_API_KEY);
+    const response = await client.getFileComponents(fileKey);
+    const match = response.meta.components.find((comp) => comp.key === componentKey);
+    if (!match) {
+      return c.ok(
+        {
+          key: componentKey,
+          name: "",
+          description: "",
+          found: false
+        },
+        c.format === "json" || c.format === "jsonl" ? void 0 : {
+          cta: {
+            commands: [
+              {
+                command: `components list ${fileKey}`,
+                description: "List all available components"
+              }
+            ]
+          }
+        }
+      );
+    }
+    return c.ok(
+      {
+        key: match.key,
+        name: match.name,
+        description: match.description,
+        found: true
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          commands: [
+            {
+              command: `components list ${fileKey}`,
+              description: "List all components"
+            },
+            {
+              command: `tokens export ${fileKey}`,
+              description: "Export design tokens"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+
+// src/commands/files.ts
+import { Cli as Cli3, z as z6 } from "incur";
+var pageSchema = z6.object({
+  id: z6.string(),
+  name: z6.string()
+});
+var fileGetOutputSchema = z6.object({
+  name: z6.string(),
+  lastModified: z6.string(),
+  version: z6.string(),
+  thumbnailUrl: z6.string().optional(),
+  pages: z6.array(pageSchema)
+});
+var projectFileOutputSchema = z6.object({
+  key: z6.string(),
+  name: z6.string(),
+  lastModified: z6.string(),
+  thumbnailUrl: z6.string().optional()
+});
+var filesListOutputSchema = z6.object({
+  projectName: z6.string(),
+  files: z6.array(projectFileOutputSchema),
+  count: z6.number()
+});
+var filesCli = Cli3.create("files", {
+  description: "Query Figma file metadata."
+});
+filesCli.command("get", {
+  description: "Get metadata for a Figma file.",
+  args: z6.object({
+    fileKey: fileKeyArg
+  }),
+  options: z6.object({
+    format: formatOption
+  }),
+  env: figmaEnv,
+  output: fileGetOutputSchema,
+  examples: [
+    {
+      args: { fileKey: "abc123XYZ" },
+      description: "Get file metadata for a Figma file"
+    }
+  ],
+  async run(c) {
+    const client = createFigmaClient(c.env.FIGMA_API_KEY);
+    const file = await client.getFile(c.args.fileKey, { depth: 1 });
+    const doc = file.document;
+    const pages = doc?.children?.map((child) => ({ id: child.id, name: child.name })) ?? [];
+    const result = {
+      name: file.name,
+      lastModified: file.lastModified,
+      version: file.version,
+      thumbnailUrl: void 0,
+      pages
+    };
+    if (c.options.format === "table") {
+      process.stdout.write(
+        `${outputFormatter(result, "table")}
+`
+      );
+    }
+    return c.ok(
+      result,
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          commands: [
+            {
+              command: "nodes get",
+              args: { fileKey: c.args.fileKey, nodeId: pages[0]?.id ?? "<node-id>" },
+              description: "Inspect a node in this file"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+filesCli.command("list", {
+  description: "List files in a Figma project.",
+  options: z6.object({
+    "project-id": z6.string().describe("Figma project ID"),
+    format: formatOption
+  }),
+  env: figmaEnv,
+  output: filesListOutputSchema,
+  examples: [
+    {
+      options: { "project-id": "12345" },
+      description: "List files in a Figma project"
+    }
+  ],
+  async run(c) {
+    const projectId = c.options["project-id"];
+    const client = createFigmaClient(c.env.FIGMA_API_KEY);
+    const project = await client.getProjectFiles(projectId);
+    const files = project.files.map((f) => ({
+      key: f.key,
+      name: f.name,
+      lastModified: f.last_modified,
+      thumbnailUrl: f.thumbnail_url
+    }));
+    const result = {
+      projectName: project.name,
+      files,
+      count: files.length
+    };
+    if (c.options.format === "table") {
+      process.stdout.write(`${outputFormatter(files, "table")}
+`);
+    }
+    return c.ok(
+      result,
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          commands: files[0] ? [
+            {
+              command: "files get",
+              args: { fileKey: files[0].key },
+              description: `Get metadata for "${files[0].name}"`
+            }
+          ] : []
+        }
+      }
+    );
+  }
+});
+
+// src/commands/frames.ts
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { resolve } from "path";
+import { Cli as Cli4, z as z7 } from "incur";
+var framesCli = Cli4.create("frames", {
+  description: "Export frame metadata and render frame images from Figma files."
+});
+function extractFrames(document, pageFilter) {
+  const doc = document;
+  const frames = [];
+  for (const page of doc.children ?? []) {
+    if (page.type !== "CANVAS") continue;
+    if (pageFilter && page.name !== pageFilter) continue;
+    for (const child of page.children ?? []) {
+      if (child.type !== "FRAME") continue;
+      frames.push({
+        name: child.name,
+        nodeId: child.id,
+        page: page.name,
+        width: child.absoluteBoundingBox?.width ?? 0,
+        height: child.absoluteBoundingBox?.height ?? 0
+      });
+    }
+  }
+  return frames;
+}
+async function downloadFile(url) {
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`Download failed (${res.status}): ${url}`);
+  }
+  return Buffer.from(await res.arrayBuffer());
+}
+framesCli.command("export", {
+  description: "List all top-level frames in a Figma file.",
+  args: z7.object({ fileKey: fileKeyArg }),
+  options: z7.object({
+    page: z7.string().optional().describe("Filter to frames on a specific page"),
+    format: formatOption
+  }),
+  env: figmaEnv,
+  output: z7.unknown(),
+  examples: [
+    {
+      args: { fileKey: "abc123" },
+      options: { format: "json" },
+      description: "List frames in a file"
+    },
+    {
+      args: { fileKey: "abc123" },
+      options: { page: "Home", format: "table" },
+      description: "List frames on the Home page"
+    }
+  ],
+  async run(c) {
+    const fileKey = c.args.fileKey;
+    const client = createFigmaClient(c.env.FIGMA_API_KEY);
+    const file = await client.getFile(fileKey);
+    const frames = extractFrames(file.document, c.options.page);
+    if (frames.length === 0) {
+      const msg = c.options.page ? `No frames found on page "${c.options.page}".` : "No top-level frames found in this file.";
+      return c.ok(c.options.format === "json" ? { frames: [], message: msg } : msg);
+    }
+    if (c.options.format === "json") {
+      return c.ok({ frames, total: frames.length });
+    }
+    return c.ok(outputFormatter(frames, "table"));
+  }
+});
+framesCli.command("render", {
+  description: "Download rendered images of specific frames from a Figma file.",
+  args: z7.object({ fileKey: fileKeyArg }),
+  options: z7.object({
+    ids: z7.string().describe("Comma-separated node IDs to render"),
+    "image-format": z7.enum(["png", "svg"]).default("png").describe("Image format: png or svg (default: png)"),
+    scale: z7.coerce.number().min(1).max(4).default(2).describe("Image scale 1-4 (default: 2)"),
+    output: z7.string().default(".").describe("Output directory (default: current directory)")
+  }),
+  env: figmaEnv,
+  output: z7.unknown(),
+  examples: [
+    {
+      args: { fileKey: "abc123" },
+      options: {
+        ids: "1:2,3:4",
+        "image-format": "png",
+        scale: 2,
+        output: "."
+      },
+      description: "Render frames as 2x PNG"
+    }
+  ],
+  async run(c) {
+    const fileKey = c.args.fileKey;
+    const { ids, "image-format": imageFormat, scale, output: outputDir } = c.options;
+    const client = createFigmaClient(c.env.FIGMA_API_KEY);
+    const nodeIds = ids.split(",").map((id) => id.trim());
+    if (nodeIds.length === 0 || nodeIds.length === 1 && nodeIds[0] === "") {
+      return c.error({
+        code: "VALIDATION_ERROR",
+        message: "--ids is required and cannot be empty"
+      });
+    }
+    const imagesResponse = await client.getImages(fileKey, nodeIds, {
+      format: imageFormat,
+      scale
+    });
+    if (imagesResponse.err) {
+      return c.error({
+        code: "FIGMA_API_ERROR",
+        message: imagesResponse.err
+      });
+    }
+    const resolvedDir = resolve(outputDir);
+    if (!existsSync(resolvedDir)) {
+      mkdirSync(resolvedDir, { recursive: true });
+    }
+    const results = [];
+    for (const nodeId of nodeIds) {
+      const imageUrl = imagesResponse.images[nodeId];
+      if (!imageUrl) {
+        results.push({ nodeId, file: "(no image)", size: 0 });
+        continue;
+      }
+      const safeNodeId = nodeId.replace(/:/g, "-");
+      const filename = `${safeNodeId}.${imageFormat}`;
+      const filepath = resolve(resolvedDir, filename);
+      const buffer = await downloadFile(imageUrl);
+      writeFileSync(filepath, buffer);
+      results.push({ nodeId, file: filepath, size: buffer.length });
+    }
+    return c.ok({ rendered: results, total: results.length });
+  }
+});
+
+// src/commands/nodes.ts
+import { Cli as Cli5, z as z8 } from "incur";
+var boundingBoxSchema = z8.object({
+  x: z8.number(),
+  y: z8.number(),
+  width: z8.number(),
+  height: z8.number()
+}).optional();
+var childSummarySchema = z8.object({
+  id: z8.string(),
+  name: z8.string(),
+  type: z8.string()
+});
+var nodeGetOutputSchema = z8.object({
+  id: z8.string(),
+  name: z8.string(),
+  type: z8.string(),
+  boundingBox: boundingBoxSchema,
+  children: z8.array(childSummarySchema),
+  childCount: z8.number()
+});
+function summarizeChildren(children, depth) {
+  if (!children || depth <= 0) return [];
+  const result = [];
+  for (const child of children) {
+    result.push({
+      id: child.id ?? "",
+      name: child.name ?? "",
+      type: child.type ?? "UNKNOWN"
+    });
+    if (depth > 1 && child.children) {
+      result.push(...summarizeChildren(child.children, depth - 1));
+    }
+  }
+  return result;
+}
+var nodesCli = Cli5.create("nodes", {
+  description: "Inspect Figma file nodes."
+});
+nodesCli.command("get", {
+  description: "Get details for a specific node in a Figma file.",
+  args: z8.object({
+    fileKey: fileKeyArg,
+    nodeId: z8.string().describe('Node ID (e.g. "1:2")')
+  }),
+  options: z8.object({
+    depth: z8.coerce.number().default(1).describe("How deep into the node tree to display children (default: 1)"),
+    format: formatOption
+  }),
+  env: figmaEnv,
+  output: nodeGetOutputSchema,
+  examples: [
+    {
+      args: { fileKey: "abc123XYZ", nodeId: "1:2" },
+      options: { depth: 2 },
+      description: "Inspect a node with 2 levels of children"
+    }
+  ],
+  async run(c) {
+    const client = createFigmaClient(c.env.FIGMA_API_KEY);
+    const response = await client.getFileNodes(c.args.fileKey, [c.args.nodeId]);
+    const nodeData = response.nodes[c.args.nodeId];
+    if (!nodeData?.document) {
+      return c.error({
+        code: "NODE_NOT_FOUND",
+        message: `Node "${c.args.nodeId}" not found in file "${c.args.fileKey}".`
+      });
+    }
+    const doc = nodeData.document;
+    const bbox = doc.absoluteBoundingBox ?? doc.absoluteRenderBounds;
+    const children = summarizeChildren(doc.children, c.options.depth);
+    const result = {
+      id: doc.id ?? c.args.nodeId,
+      name: doc.name ?? "",
+      type: doc.type ?? "UNKNOWN",
+      boundingBox: bbox ? { x: bbox.x, y: bbox.y, width: bbox.width, height: bbox.height } : void 0,
+      children,
+      childCount: doc.children?.length ?? 0
+    };
+    if (c.options.format === "table") {
+      process.stdout.write(
+        `${outputFormatter(result, "table")}
+`
+      );
+    }
+    return c.ok(
+      result,
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          commands: children[0] ? [
+            {
+              command: "nodes get",
+              args: { fileKey: c.args.fileKey, nodeId: children[0].id },
+              description: `Inspect child node "${children[0].name}"`
+            }
+          ] : []
+        }
+      }
+    );
+  }
+});
+
+// src/commands/tokens.ts
+import { writeFileSync as writeFileSync2 } from "fs";
+import { Cli as Cli6, z as z9 } from "incur";
+
+// src/tokens/dtcg.ts
+function slugify(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+function colorToDtcgHex(rgba) {
+  const r = rgba.r.toString(16).padStart(2, "0");
+  const g = rgba.g.toString(16).padStart(2, "0");
+  const b = rgba.b.toString(16).padStart(2, "0");
+  if (rgba.a < 1) {
+    const a = Math.round(rgba.a * 255).toString(16).padStart(2, "0");
+    return `#${r}${g}${b}${a}`;
+  }
+  return `#${r}${g}${b}`;
+}
+function colorToDtcg(token) {
+  return {
+    $type: "color",
+    $value: colorToDtcgHex(token.rgba)
+  };
+}
+function typographyToDtcg(token) {
+  const group = {
+    fontFamily: {
+      $type: "fontFamily",
+      $value: token.fontFamily
+    },
+    fontSize: {
+      $type: "dimension",
+      $value: `${token.fontSize}px`
+    },
+    fontWeight: {
+      $type: "fontWeight",
+      $value: token.fontWeight
+    },
+    letterSpacing: {
+      $type: "dimension",
+      $value: `${token.letterSpacing}px`
+    }
+  };
+  if (token.lineHeight !== null) {
+    group.lineHeight = {
+      $type: "dimension",
+      $value: `${token.lineHeight}px`
+    };
+  }
+  return group;
+}
+function shadowToDtcg(token) {
+  return {
+    $type: "shadow",
+    $value: {
+      color: colorToDtcgHex(token.color),
+      offsetX: `${token.offsetX}px`,
+      offsetY: `${token.offsetY}px`,
+      blur: `${token.radius}px`,
+      spread: `${token.spread}px`
+    }
+  };
+}
+function blurToDtcg(token) {
+  return {
+    $type: "dimension",
+    $value: `${token.radius}px`
+  };
+}
+function effectToDtcg(token) {
+  if ("color" in token) {
+    return shadowToDtcg(token);
+  }
+  return blurToDtcg(token);
+}
+function toDtcg(tokens) {
+  const output = {};
+  if (tokens.colors.length > 0) {
+    const group = {};
+    for (const c of tokens.colors) {
+      group[slugify(c.name)] = colorToDtcg(c);
+    }
+    output.color = group;
+  }
+  if (tokens.typography.length > 0) {
+    const group = {};
+    for (const t of tokens.typography) {
+      group[slugify(t.name)] = typographyToDtcg(t);
+    }
+    output.typography = group;
+  }
+  if (tokens.effects.length > 0) {
+    const group = {};
+    for (const e of tokens.effects) {
+      group[slugify(e.name)] = effectToDtcg(e);
+    }
+    output.effect = group;
+  }
+  return output;
+}
+
+// src/tokens/extractor.ts
+function clamp(v, min, max) {
+  return Math.max(min, Math.min(max, v));
+}
+function toHex(r, g, b, a) {
+  const r8 = Math.round(clamp(r, 0, 1) * 255);
+  const g8 = Math.round(clamp(g, 0, 1) * 255);
+  const b8 = Math.round(clamp(b, 0, 1) * 255);
+  const hex = `#${r8.toString(16).padStart(2, "0")}${g8.toString(16).padStart(2, "0")}${b8.toString(16).padStart(2, "0")}`;
+  if (a < 1) {
+    const a8 = Math.round(clamp(a, 0, 1) * 255);
+    return `${hex}${a8.toString(16).padStart(2, "0")}`;
+  }
+  return hex;
+}
+function sanitizeName(name) {
+  return name.trim() || "unnamed";
+}
+function extractColorFromPaints(name, fills) {
+  const solid = fills.find((f) => f.type === "SOLID" && f.visible !== false && f.color);
+  if (!solid?.color) return null;
+  const { r, g, b, a: colorA } = solid.color;
+  const a = solid.opacity !== void 0 ? solid.opacity * colorA : colorA;
+  return {
+    name: sanitizeName(name),
+    hex: toHex(r, g, b, a),
+    rgba: {
+      r: Math.round(clamp(r, 0, 1) * 255),
+      g: Math.round(clamp(g, 0, 1) * 255),
+      b: Math.round(clamp(b, 0, 1) * 255),
+      a: Number.parseFloat(clamp(a, 0, 1).toFixed(2))
+    }
+  };
+}
+function extractTypography(name, style) {
+  return {
+    name: sanitizeName(name),
+    fontFamily: style.fontFamily,
+    fontSize: style.fontSize,
+    fontWeight: style.fontWeight,
+    lineHeight: style.lineHeightPx ?? null,
+    letterSpacing: style.letterSpacing ?? 0
+  };
+}
+function extractEffects(name, effects) {
+  const tokens = [];
+  for (const effect of effects) {
+    if (effect.visible === false) continue;
+    if (effect.type === "DROP_SHADOW" || effect.type === "INNER_SHADOW") {
+      tokens.push({
+        name: sanitizeName(name),
+        type: effect.type === "DROP_SHADOW" ? "drop-shadow" : "inner-shadow",
+        color: effect.color ? {
+          r: Math.round(clamp(effect.color.r, 0, 1) * 255),
+          g: Math.round(clamp(effect.color.g, 0, 1) * 255),
+          b: Math.round(clamp(effect.color.b, 0, 1) * 255),
+          a: Number.parseFloat(clamp(effect.color.a, 0, 1).toFixed(2))
+        } : { r: 0, g: 0, b: 0, a: 1 },
+        offsetX: effect.offset?.x ?? 0,
+        offsetY: effect.offset?.y ?? 0,
+        radius: effect.radius ?? 0,
+        spread: effect.spread ?? 0
+      });
+    } else if (effect.type === "LAYER_BLUR" || effect.type === "BACKGROUND_BLUR") {
+      tokens.push({
+        name: sanitizeName(name),
+        type: effect.type === "LAYER_BLUR" ? "layer-blur" : "background-blur",
+        radius: effect.radius ?? 0
+      });
+    }
+  }
+  return tokens;
+}
+function extractTokens(document, styles, filter) {
+  const colors = [];
+  const typography = [];
+  const effects = [];
+  if (!styles || Object.keys(styles).length === 0) {
+    return { colors, typography, effects };
+  }
+  const styleByNodeId = /* @__PURE__ */ new Map();
+  for (const [nodeId, meta] of Object.entries(styles)) {
+    styleByNodeId.set(nodeId, meta);
+  }
+  const nodeMap = /* @__PURE__ */ new Map();
+  function walk(node) {
+    if (!node || typeof node !== "object") return;
+    const n = node;
+    if (n.id) {
+      nodeMap.set(n.id, n);
+    }
+    const nodeStyles = n.styles;
+    if (nodeStyles) {
+      for (const [_styleType, styleId] of Object.entries(nodeStyles)) {
+        if (styleByNodeId.has(styleId)) {
+          nodeMap.set(styleId, n);
+        }
+      }
+    }
+    if (Array.isArray(n.children)) {
+      for (const child of n.children) walk(child);
+    }
+  }
+  walk(document);
+  for (const [nodeId, meta] of styleByNodeId) {
+    const node = nodeMap.get(nodeId);
+    const styleName = meta.name;
+    if (meta.style_type === "FILL" && (!filter || filter === "colors")) {
+      if (node?.fills && Array.isArray(node.fills)) {
+        const color = extractColorFromPaints(styleName, node.fills);
+        if (color) colors.push(color);
+      }
+    } else if (meta.style_type === "TEXT" && (!filter || filter === "typography")) {
+      if (node?.style) {
+        typography.push(extractTypography(styleName, node.style));
+      }
+    } else if (meta.style_type === "EFFECT" && (!filter || filter === "effects")) {
+      if (node?.effects && Array.isArray(node.effects)) {
+        const extracted = extractEffects(styleName, node.effects);
+        effects.push(...extracted);
+      }
+    }
+  }
+  return { colors, typography, effects };
+}
+function toFlatTokens(tokens) {
+  const flat = {};
+  for (const c of tokens.colors) {
+    const key = `color.${slugify2(c.name)}`;
+    flat[key] = c.hex;
+  }
+  for (const t of tokens.typography) {
+    const base = `typography.${slugify2(t.name)}`;
+    flat[`${base}.fontFamily`] = t.fontFamily;
+    flat[`${base}.fontSize`] = t.fontSize;
+    flat[`${base}.fontWeight`] = t.fontWeight;
+    if (t.lineHeight !== null) flat[`${base}.lineHeight`] = t.lineHeight;
+    flat[`${base}.letterSpacing`] = t.letterSpacing;
+  }
+  for (const e of tokens.effects) {
+    const base = `effect.${slugify2(e.name)}`;
+    flat[`${base}.type`] = e.type;
+    if ("color" in e) {
+      const s = e;
+      flat[`${base}.offsetX`] = s.offsetX;
+      flat[`${base}.offsetY`] = s.offsetY;
+      flat[`${base}.radius`] = s.radius;
+      flat[`${base}.spread`] = s.spread;
+      flat[`${base}.color`] = `rgba(${s.color.r}, ${s.color.g}, ${s.color.b}, ${s.color.a})`;
+    } else {
+      flat[`${base}.radius`] = e.radius;
+    }
+  }
+  return flat;
+}
+function slugify2(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+
+// src/commands/tokens.ts
+var tokensCli = Cli6.create("tokens", {
+  description: "Extract design tokens from Figma files."
+});
+var formatOption2 = z9.enum(["dtcg", "flat", "json"]).default("dtcg").describe("Output format: dtcg (W3C DTCG), flat (key-value), json (raw intermediate)");
+var filterOption = z9.enum(["colors", "typography", "effects"]).optional().describe("Extract only specific token types");
+var outputOption = z9.string().optional().describe("Write output to file instead of stdout");
+tokensCli.command("export", {
+  description: "Extract design tokens from a Figma file.",
+  args: z9.object({
+    fileKey: z9.string().describe("Figma file key")
+  }),
+  options: z9.object({
+    format: formatOption2,
+    filter: filterOption,
+    output: outputOption
+  }),
+  env: figmaEnv,
+  output: z9.unknown(),
+  examples: [
+    {
+      args: { fileKey: "abc123FileKey" },
+      options: { format: "dtcg" },
+      description: "Export tokens in DTCG format"
+    },
+    {
+      args: { fileKey: "abc123FileKey" },
+      options: { format: "flat", filter: "colors" },
+      description: "Export only color tokens in flat format"
+    }
+  ],
+  async run(c) {
+    const { fileKey } = c.args;
+    const client = createFigmaClient(c.env.FIGMA_API_KEY);
+    const file = await client.getFile(fileKey);
+    const tokens = extractTokens(
+      file.document,
+      file.styles,
+      c.options.filter
+    );
+    let result;
+    if (c.options.format === "dtcg") {
+      result = toDtcg(tokens);
+    } else if (c.options.format === "flat") {
+      result = toFlatTokens(tokens);
+    } else {
+      result = tokens;
+    }
+    if (c.options.output) {
+      writeFileSync2(c.options.output, JSON.stringify(result, null, 2), "utf8");
+      return c.ok(
+        { written: c.options.output, format: c.options.format },
+        c.format === "json" || c.format === "jsonl" ? void 0 : {
+          cta: {
+            commands: [
+              {
+                command: `tokens export ${fileKey} --format flat`,
+                description: "Export tokens in flat format"
+              }
+            ]
+          }
+        }
+      );
+    }
+    return c.ok(
+      result,
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          commands: [
+            {
+              command: `tokens export ${fileKey} --format flat`,
+              description: "Export in flat key-value format"
+            },
+            {
+              command: `tokens export ${fileKey} --filter colors`,
+              description: "Export only color tokens"
+            },
+            {
+              command: `components list ${fileKey}`,
+              description: "List published components"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+
+// src/cli.ts
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var pkg = JSON.parse(readFileSync(resolve2(__dirname, "../package.json"), "utf8"));
+var cli = Cli7.create("figma", {
+  version: pkg.version,
+  description: "Query Figma REST API data from the command line."
+});
+cli.command(tokensCli);
+cli.command(componentsCli);
+cli.command(filesCli);
+cli.command(nodesCli);
+cli.command(framesCli);
+cli.command(commentsCli);
+var isMain = (() => {
+  const entrypoint = process.argv[1];
+  if (!entrypoint) {
+    return false;
+  }
+  try {
+    return realpathSync(entrypoint) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+if (isMain) {
+  initTelemetry("figma");
+  process.on("beforeExit", () => shutdownTelemetry());
+  cli.serve();
+}
 export {
   cli,
   createFigmaClient,
-  figmaEnv
+  extractTokens,
+  figmaEnv,
+  toDtcg,
+  toFlatTokens
 };