agent-orchestrator-kit 0.1.11 → 0.1.12

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.1.12] - 2026-07-21
+
+### Added
+- **`figma-fetch --depth <n>`** — limit Figma node tree depth for large frames (omit = full tree)
+
+### Fixed
+- **`figma-fetch` large payloads** — write API response text as-is instead of pretty-printing via `JSON.stringify` (avoids `Invalid string length` on huge trees)
+- Clearer error when Figma API returns a non-JSON body
+
 ## [0.1.11] - 2026-07-21
 
 ### Added

package/README.md

@@ -624,6 +624,8 @@ npx agent-orchestrator-kit figma-setup
 npx agent-orchestrator-kit figma-status
 npx agent-orchestrator-kit figma-fetch --url "https://www.figma.com/design/FILE_KEY/Name?node-id=1-2" \
   --out openspec/changes/<name>/assets/figma-nodes.json
+# large frames: limit tree depth
+npx agent-orchestrator-kit figma-fetch --file FILE_KEY --nodes 1:2 --depth 2 --out figma-nodes.json
 ```
 
 `figma-fetch` uses the Figma REST API (`X-Figma-Token`) and writes JSON for design-brief capture. Live Figma is for design-intake only — apply uses `design-brief.md`.
@@ -753,6 +755,10 @@ openspec/                # Committed — spec-driven workflow
 
 ## Changelog
 
+### 0.1.12
+- `figma-fetch --depth <n>` for large frames
+- Write large Figma JSON as raw API text (avoids `Invalid string length` on huge trees)
+
 ### 0.1.11
 - Optional **Figma personal token** setup: `.agents/figma.local.env` (gitignored) + `figma-mcp-launcher.cjs` (no secret in `.mcp.json`)
 - CLI: `figma-setup`, `figma-status`, `figma-fetch` (REST nodes/file JSON)

package/bin/agent-orchestrator.js

@@ -260,13 +260,17 @@ async function figmaApiGet(token, path) {
   try {
     data = JSON.parse(text);
   } catch {
-    data = { err: text };
+    data = null;
   }
   if (!response.ok) {
-    const message = data?.err || data?.message || response.statusText || `HTTP ${response.status}`;
+    const message =
+      (data && (data.err || data.message)) || response.statusText || `HTTP ${response.status}`;
     throw new Error(String(message));
   }
-  return data;
+  if (!data) {
+    throw new Error('Figma API returned non-JSON response');
+  }
+  return { data, text };
 }
 
 function resolveTemplate(templateName, profile) {
@@ -1063,6 +1067,7 @@ program
   .option('--url <url>', 'Figma design URL (file key + optional node-id)')
   .option('--file <key>', 'Figma file key')
   .option('--nodes <ids>', 'Comma-separated node ids (1:2 or 1-2)')
+  .option('--depth <n>', 'Limit node tree depth (use for large frames; omit = full tree)')
   .option('--out <path>', 'Output JSON path', 'figma-nodes.json')
   .action(async (opts) => {
     const projectDir = process.cwd();
@@ -1096,16 +1101,36 @@ program
       .filter(Boolean)
       .map((id) => id.replace(/-/g, ':'));
 
+    const query = [];
+    if (nodeIds.length) {
+      query.push(`ids=${encodeURIComponent(nodeIds.join(','))}`);
+    }
+    if (opts.depth != null && String(opts.depth).trim() !== '') {
+      const depth = Number(opts.depth);
+      if (!Number.isInteger(depth) || depth < 1) {
+        log.err('--depth must be a positive integer');
+        process.exitCode = 1;
+        return;
+      }
+      query.push(`depth=${depth}`);
+    }
+
     try {
-      const path = nodeIds.length
-        ? `/files/${encodeURIComponent(fileKey)}/nodes?ids=${encodeURIComponent(nodeIds.join(','))}`
-        : `/files/${encodeURIComponent(fileKey)}`;
-      log.info(nodeIds.length ? `Fetching ${nodeIds.length} node(s)…` : 'Fetching full file…');
-      const data = await figmaApiGet(token, path);
+      const apiPath = nodeIds.length
+        ? `/files/${encodeURIComponent(fileKey)}/nodes${query.length ? `?${query.join('&')}` : ''}`
+        : `/files/${encodeURIComponent(fileKey)}${query.length ? `?${query.join('&')}` : ''}`;
+      log.info(
+        nodeIds.length
+          ? `Fetching ${nodeIds.length} node(s)${opts.depth ? ` (depth ${opts.depth})` : ''}…`
+          : `Fetching full file${opts.depth ? ` (depth ${opts.depth})` : ''}…`
+      );
+      const { data, text } = await figmaApiGet(token, apiPath);
       const outPath = join(projectDir, opts.out);
       mkdirSync(dirname(outPath), { recursive: true });
-      writeFileSync(outPath, `${JSON.stringify(data, null, 2)}\n`);
-      log.ok(`Wrote ${opts.out}`);
+      // Write API payload as-is — pretty-print of huge trees can throw "Invalid string length"
+      writeFileSync(outPath, text.endsWith('\n') ? text : `${text}\n`);
+      const nodeCount = data.nodes ? Object.keys(data.nodes).length : 0;
+      log.ok(`Wrote ${opts.out}${nodeCount ? ` (${nodeCount} node key(s))` : ''}`);
     } catch (error) {
       log.err(`Figma API error: ${error.message}`);
       process.exitCode = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-kit",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Universal AI agent orchestration kit for Cursor, Claude Code, and Amp Code — spec-driven OpenSpec pipeline, cross-IDE subagents, and optional local Figma PAT setup (figma-setup / figma-status / figma-fetch)",
   "keywords": [
     "ai-agent",