pi-mono-all 1.0.0

package/node_modules/pi-mono-figma/__tests__/fixtures/hidden-and-vectors.json

@@ -0,0 +1,28 @@
+{
+  "id": "4:1",
+  "name": "Visibility Fixture",
+  "type": "FRAME",
+  "absoluteBoundingBox": { "width": 200, "height": 120 },
+  "children": [
+    {
+      "id": "4:2",
+      "name": "Visible text",
+      "type": "TEXT",
+      "characters": "Visible copy"
+    },
+    {
+      "id": "4:3",
+      "name": "Hidden text",
+      "type": "TEXT",
+      "visible": false,
+      "characters": "Hidden copy"
+    },
+    {
+      "id": "4:4",
+      "name": "Search icon",
+      "type": "VECTOR",
+      "absoluteBoundingBox": { "width": 16, "height": 16 },
+      "children": [{ "id": "4:5", "name": "Vector point", "type": "VECTOR" }]
+    }
+  ]
+}

package/node_modules/pi-mono-figma/__tests__/fixtures/variables-and-styles.json

@@ -0,0 +1,40 @@
+{
+  "id": "3:1",
+  "name": "Tokenized Button",
+  "type": "FRAME",
+  "absoluteBoundingBox": { "width": 160, "height": 48 },
+  "layoutMode": "HORIZONTAL",
+  "primaryAxisAlignItems": "CENTER",
+  "counterAxisAlignItems": "CENTER",
+  "styles": { "fill": "S:primary-fill", "stroke": "S:border-default" },
+  "boundVariables": {
+    "fills": [{ "type": "VARIABLE_ALIAS", "id": "VariableID:color-primary" }],
+    "cornerRadius": { "type": "VARIABLE_ALIAS", "id": "VariableID:radius-md" }
+  },
+  "fills": [
+    {
+      "type": "SOLID",
+      "color": { "r": 0.02, "g": 0.35, "b": 0.9 },
+      "opacity": 1
+    }
+  ],
+  "cornerRadius": 8,
+  "children": [
+    {
+      "id": "3:2",
+      "name": "Label",
+      "type": "TEXT",
+      "characters": "Submit",
+      "style": { "fontFamily": "Inter", "fontSize": 14, "fontWeight": 600 },
+      "styles": { "text": "S:text-button" },
+      "boundVariables": {
+        "fills": [
+          { "type": "VARIABLE_ALIAS", "id": "VariableID:text-on-primary" }
+        ]
+      },
+      "fills": [
+        { "type": "SOLID", "color": { "r": 1, "g": 1, "b": 1 }, "opacity": 1 }
+      ]
+    }
+  ]
+}

package/node_modules/pi-mono-figma/docs/live-selection-bridge.md

@@ -0,0 +1,16 @@
+# Future live-selection bridge
+
+The current Figma extension is REST/API-based and read-only. It operates on explicit `fileKey` and `nodeId` values and does not receive live selection events from the Figma app.
+
+A future live-selection workflow should be implemented as a separate bridge/plugin layer:
+
+1. A Figma plugin reads the current page and selected node IDs.
+2. A local bridge exposes that selection through localhost or Pi extension IPC.
+3. A Pi tool such as `figma_get_current_selection` returns file key, page, selected node IDs, and optional render metadata.
+4. Existing processed tools (`figma_get_node_summary`, `figma_get_implementation_context`, search, and asset extraction) run against those selected node IDs.
+
+Non-goals for the REST baseline:
+
+- no Figma file edits,
+- no private APIs,
+- no claim of live selection support until a plugin/bridge exists.

package/node_modules/pi-mono-figma/index.ts

@@ -0,0 +1,6 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { registerFigmaTools } from "./src/figma-tools.js";
+
+export default function figmaExtension(pi: ExtensionAPI): void {
+	registerFigmaTools(pi);
+}

package/node_modules/pi-mono-figma/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "pi-mono-figma",
+  "version": "0.2.1",
+  "description": "Pi extension and skill for Figma design context tools",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-skill",
+    "figma"
+  ],
+  "scripts": {
+    "test": "npx tsx --test '__tests__/**/*.test.ts'"
+  },
+  "dependencies": {
+    "pi-common": "workspace:*"
+  },
+  "bundledDependencies": [
+    "pi-common"
+  ],
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  }
+}

package/node_modules/pi-mono-figma/skills/figma/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: figma
+description: Access Figma design files using native pi tools — read LLM-ready summaries, explanations, implementation context, screenshots, components, styles, variables, and design tokens. Requires a Figma personal access token.
+---
+
+# Figma Design Integration
+
+Use the native `figma_*` tools to read Figma files and translate designs into code. Prefer processed, LLM-ready tools over raw Figma JSON.
+
+## When to Use
+
+- User provides a Figma file URL and asks you to explain or implement a design.
+- User asks about Figma colors, typography, spacing, components, variables, or layout.
+- You need screenshots/assets for visual validation.
+
+## Authentication
+
+The tools read the token from an in-memory override, `FIGMA_TOKEN`, or `~/.pi/agent/auth.json` at `.figma.token`.
+
+If auth is missing, invalid, or expired, do **not** ask the user to paste the token in chat. Use the native `figma_configure_auth` tool or ask the user to run `/figma-auth --force`. The prompt is masked and the token is stored by the extension without returning it to the model.
+
+## URL Parsing
+
+Given:
+
+```text
+https://www.figma.com/design/ABC123def456/Project-Name?node-id=123-456
+```
+
+- File key: `ABC123def456`
+- Node ID: `123-456` from the URL (`figma_*` tools also accept API format `123:456`)
+
+Use `figma_parse_url` when you need to extract these values from a full URL.
+
+## Default Tool Workflow
+
+1. Use `figma_configure_auth` only when auth is missing, invalid, expired, or the user asks to update the token.
+2. Use `figma_parse_url` for full Figma URLs.
+3. If the exact target node is unclear, use `figma_get_design_context` plus `figma_find_nodes_by_name` or `figma_find_nodes_by_text` before raw exploration.
+4. Use `figma_render_nodes` for screenshots and `figma_extract_assets` when icons, node renders, or image fills are needed for implementation.
+   - Do **not** pass `outputDir` unless the user explicitly requests persistent files in a specific location. Let the extension use its OS temp directory default for generated images/assets.
+5. Use `figma_explain_node` or `figma_get_node_summary` for the target frame/component.
+6. Use enriched `figma_get_implementation_context` when coding from a design. Pass `framework`, `styling`, `resolveTokens`, and `includeCodeSnippets` when useful.
+7. Use `figma_find_code_connect_mapping` only when the local repo may contain Code Connect mappings or Figma URL/node references.
+8. Use `figma_get_component_implementation_hints` for component-level implementation planning.
+9. Use `figma_get_nodes` only for raw debugging.
+
+**Do not call `figma_get_nodes` by default. Prefer processed tools.**
+
+Prefer batch calls where supported: pass multiple node IDs to `figma_render_nodes`, `figma_get_node_metadata`, or raw `figma_get_nodes` instead of looping.
+
+## Recommended Workflows
+
+### Explaining a component
+
+```text
+figma_parse_url
+figma_render_nodes
+figma_explain_node
+```
+
+### Implementing a design
+
+```text
+figma_parse_url
+figma_find_nodes_by_name/text if the URL lacks an exact target node
+figma_render_nodes
+figma_get_implementation_context with framework/styling/token options when useful
+figma_get_node_summary for specific subnodes if needed
+```
+
+### Extracting assets
+
+```text
+figma_extract_assets
+```
+
+Use this when visual assets are needed. Prefer the manifest's `nodePath`, `suggestedName`, hashes, and local paths over guessing layer-to-file mappings.
+
+### Finding local implementation mappings
+
+```text
+figma_find_code_connect_mapping
+figma_get_component_implementation_hints
+```
+
+Only use these when you are working in a local code repository where Code Connect or Figma URL/node references may exist.
+
+### Debugging the extension or raw Figma data
+
+```text
+figma_get_nodes
+```
+
+## Processed Tools
+
+- `figma_get_node_summary` returns compact structured summaries: name, type, size, layout, spacing/padding, fills/strokes/effects, visible text, component properties, and immediate child hierarchy.
+- `figma_extract_text` returns visible text nodes only.
+- `figma_explain_node` returns human-readable Markdown for questions like “Explain this component.”
+- `figma_find_nodes_by_name` and `figma_find_nodes_by_text` search names/text with compact path-aware matches. Use them before raw file exploration.
+- `figma_get_implementation_context` returns coding-ready context: purpose, sections, fields/buttons, measurements, typography, colors, spacing, CSS layout/responsive hints, accessibility hints, design tokens, assets, framework hints, and hierarchy.
+- `figma_extract_assets` returns an asset manifest for SVG icons, node renders, and image fills.
+- `figma_find_code_connect_mapping` scans the local repo for Code Connect/Figma references.
+- `figma_get_component_implementation_hints` combines Figma context, variants, tokens, assets, accessibility, Code Connect matches, and optional starter snippets.
+
+Processed tools default to shallow, safe fetches:
+
+```ts
+{
+  depth: 2,
+  includeHidden: false,
+  includeVectors: false,
+  includeComponentInternals: false,
+  framework?: "react" | "html" | "vue" | "angular" | "react-native",
+  styling?: "css" | "css-modules" | "styled-components" | "tailwind" | "inline",
+  resolveTokens?: true,
+  includeCodeSnippets?: false
+}
+```
+
+Only increase `depth` (max 4) or enable internals/vectors for a specific child node when needed.
+
+## Raw Escape Hatches
+
+- `figma_get_file`
+- `figma_get_nodes`
+
+Use these only when raw Figma JSON is explicitly needed or when debugging the extension. They may return very large responses and reduce answer quality.
+
+## Output Limits
+
+Processed tools enforce compact defaults and may include `metadata.truncated: true` plus `nextSteps`, for example:
+
+- Call `figma_get_node_summary` with a deeper `depth`.
+- Inspect a specific child node by ID.
+- Enable `includeComponentInternals=true` for a focused component instance.
+
+## Notes
+
+- Figma API is rate-limited; batch node IDs where supported.
+- Large responses may be truncated; narrow to a specific child node when needed.
+- This integration is read-only and cannot modify Figma files.
+- Live Figma selection is not implemented. True Dev Mode-style live selection requires a future local Figma plugin/bridge.

package/node_modules/pi-mono-figma/src/code-connect.ts

@@ -0,0 +1,110 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve } from "node:path";
+
+export interface CodeConnectScanOptions {
+	fileKey: string;
+	nodeId?: string;
+	componentKey?: string;
+	rootDir?: string;
+	cwd: string;
+	maxMatches?: number;
+	maxFiles?: number;
+	maxFileBytes?: number;
+}
+
+export interface CodeConnectMatch {
+	path: string;
+	line: number;
+	kind: "figma-connect" | "figma-config" | "figma-file-reference" | "figma-node-reference" | "component-key-reference";
+	preview: string;
+}
+
+export interface CodeConnectScanResult {
+	rootDir: string;
+	matches: CodeConnectMatch[];
+	metadata: { truncated: boolean; truncatedReasons: string[]; nextSteps: string[] };
+}
+
+const IGNORE_DIRS = new Set(["node_modules", "dist", "build", ".git", "coverage", ".next", ".turbo", ".cache"]);
+const DEFAULT_MAX_MATCHES = 40;
+const DEFAULT_MAX_FILES = 1500;
+const DEFAULT_MAX_FILE_BYTES = 300_000;
+
+export async function findCodeConnectMapping(options: CodeConnectScanOptions): Promise<CodeConnectScanResult> {
+	const rootDir = resolveRoot(options.cwd, options.rootDir);
+	const maxMatches = clampInteger(options.maxMatches ?? DEFAULT_MAX_MATCHES, 1, 200);
+	const maxFiles = clampInteger(options.maxFiles ?? DEFAULT_MAX_FILES, 1, 10_000);
+	const maxFileBytes = clampInteger(options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES, 1_000, 2_000_000);
+	const normalizedNodeId = options.nodeId?.replace(/-/g, ":");
+	const urlNodeId = normalizedNodeId?.replace(/:/g, "-");
+	const matches: CodeConnectMatch[] = [];
+	const truncatedReasons: string[] = [];
+	let filesSeen = 0;
+
+	async function scanDir(dir: string): Promise<void> {
+		if (filesSeen >= maxFiles || matches.length >= maxMatches) return;
+		for (const entry of await readdir(dir, { withFileTypes: true })) {
+			if (entry.isDirectory()) {
+				if (IGNORE_DIRS.has(entry.name) || (entry.name.startsWith(".") && !entry.name.startsWith(".figma"))) continue;
+				await scanDir(join(dir, entry.name));
+				continue;
+			}
+			if (!entry.isFile() || !isLikelySource(entry.name)) continue;
+			filesSeen += 1;
+			if (filesSeen > maxFiles) {
+				truncatedReasons.push(`Scanned file cap ${maxFiles} reached.`);
+				return;
+			}
+			const filePath = join(dir, entry.name);
+			const info = await stat(filePath);
+			if (info.size > maxFileBytes) continue;
+			await scanFile(filePath);
+			if (matches.length >= maxMatches) {
+				truncatedReasons.push(`Reached maxMatches ${maxMatches}; additional matches were omitted.`);
+				return;
+			}
+		}
+	}
+
+	async function scanFile(filePath: string): Promise<void> {
+		const text = await readFile(filePath, "utf8");
+		const lines = text.split(/\r?\n/);
+		lines.forEach((line, index) => {
+			for (const kind of classify(line, filePath, options.fileKey, normalizedNodeId, urlNodeId, options.componentKey)) {
+				if (matches.length < maxMatches) matches.push({ path: relative(rootDir, filePath), line: index + 1, kind, preview: line.trim().slice(0, 240) });
+			}
+		});
+	}
+
+	await scanDir(rootDir);
+	const nextSteps = matches.length ? ["Open matched files to inspect local component props and implementation conventions."] : ["No local Code Connect mapping was found; use Figma implementation context and existing component search next."];
+	if (truncatedReasons.length) nextSteps.push("Narrow rootDir or raise maxMatches/maxFiles if you expect more mappings.");
+	return { rootDir, matches, metadata: { truncated: truncatedReasons.length > 0, truncatedReasons: [...new Set(truncatedReasons)], nextSteps } };
+}
+
+function classify(line: string, filePath: string, fileKey: string, nodeId?: string, urlNodeId?: string, componentKey?: string): Array<CodeConnectMatch["kind"]> {
+	const lowerPath = filePath.toLowerCase();
+	const kinds: Array<CodeConnectMatch["kind"]> = [];
+	if (/figma\.connect\s*\(/.test(line)) kinds.push("figma-connect");
+	if ((/figma\.config\.|figma\.config\.(js|ts|mjs|cjs)$/.test(line) || /figma\.config\./.test(lowerPath) || /\.figma\./.test(lowerPath)) && line.trim()) kinds.push("figma-config");
+	if (line.includes(fileKey)) kinds.push("figma-file-reference");
+	if (nodeId && (line.includes(nodeId) || (urlNodeId && line.includes(urlNodeId)))) kinds.push("figma-node-reference");
+	if (componentKey && line.includes(componentKey)) kinds.push("component-key-reference");
+	return kinds;
+}
+
+function resolveRoot(cwd: string, rootDir?: string): string {
+	if (!rootDir) return cwd;
+	const resolved = isAbsolute(rootDir) ? resolve(rootDir) : resolve(cwd, rootDir);
+	const cwdResolved = resolve(cwd);
+	if (resolved !== cwdResolved && !resolved.startsWith(`${cwdResolved}/`)) throw new Error("rootDir must be inside the current working directory.");
+	return resolved;
+}
+
+function isLikelySource(name: string): boolean {
+	return /(?:figma\.config\..*|\.figma\..*|\.(tsx?|jsx?|vue|svelte|mdx?|json|ya?ml))$/i.test(name);
+}
+
+function clampInteger(value: number, min: number, max: number): number {
+	return Math.max(min, Math.min(max, Math.trunc(value)));
+}

package/node_modules/pi-mono-figma/src/figma-assets.ts

@@ -0,0 +1,146 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { basename, extname } from "node:path";
+
+export type FigmaAssetType = "svgIcons" | "nodeRenders" | "imageFills";
+export type FigmaAssetKind = "svgIcon" | "nodeRender" | "imageFill";
+
+export interface FigmaAssetCandidate {
+	kind: FigmaAssetKind;
+	nodeId?: string;
+	nodeName?: string;
+	nodeType?: string;
+	nodePath: string;
+	imageRef?: string;
+	fillIndex?: number;
+	suggestedName: string;
+}
+
+export interface FigmaAssetManifestEntry extends FigmaAssetCandidate {
+	format: "png" | "jpg" | "svg" | "webp" | "unknown";
+	path?: string;
+	url?: string | null;
+	sha256?: string;
+	bytes?: number;
+}
+
+export interface FigmaAssetCollectionResult {
+	assets: FigmaAssetCandidate[];
+	metadata: { truncated: boolean; truncatedReasons: string[]; nextSteps: string[] };
+}
+
+export interface FigmaExtractAssetsResult {
+	nodeId: string;
+	assetTypes: FigmaAssetType[];
+	assets: FigmaAssetManifestEntry[];
+	metadata: { truncated: boolean; truncatedReasons: string[]; nextSteps: string[] };
+}
+
+const VECTOR_TYPES = new Set(["VECTOR", "BOOLEAN_OPERATION", "STAR", "LINE", "ELLIPSE", "POLYGON", "REGULAR_POLYGON"]);
+const DEFAULT_MAX_ASSETS = 80;
+
+export function collectAssetCandidates(node: unknown, options: { assetTypes?: FigmaAssetType[]; includeHidden?: boolean; maxAssets?: number } = {}): FigmaAssetCollectionResult {
+	const assetTypes = new Set(options.assetTypes?.length ? options.assetTypes : (["svgIcons", "nodeRenders", "imageFills"] as FigmaAssetType[]));
+	const maxAssets = clampInteger(options.maxAssets ?? DEFAULT_MAX_ASSETS, 1, 500);
+	const assets: FigmaAssetCandidate[] = [];
+	const truncatedReasons: string[] = [];
+
+	function push(candidate: FigmaAssetCandidate): void {
+		if (assets.length >= maxAssets) {
+			if (!truncatedReasons.some((reason) => reason.includes("maxAssets"))) truncatedReasons.push(`Reached maxAssets ${maxAssets}; additional assets were omitted.`);
+			return;
+		}
+		assets.push(candidate);
+	}
+
+	walk(node, options.includeHidden ?? false, (record, path, level) => {
+		const name = String(record.name ?? "Asset");
+		const type = String(record.type ?? "UNKNOWN");
+		const id = stringValue(record.id);
+		if (assetTypes.has("svgIcons") && id && isIconCandidate(record)) {
+			push({ kind: "svgIcon", nodeId: id, nodeName: name, nodeType: type, nodePath: path, suggestedName: `${safeFilename(name || id)}.svg` });
+		}
+		if (assetTypes.has("nodeRenders") && id && (level === 0 || /asset|illustration|image|card|avatar|logo/i.test(name))) {
+			push({ kind: "nodeRender", nodeId: id, nodeName: name, nodeType: type, nodePath: path, suggestedName: `${safeFilename(name || id)}.png` });
+		}
+		if (assetTypes.has("imageFills")) {
+			const fills = Array.isArray(record.fills) ? record.fills : [];
+			fills.forEach((fill, index) => {
+				const fillRecord = asRecord(fill);
+				const imageRef = stringValue(fillRecord.imageRef);
+				if (imageRef) push({ kind: "imageFill", nodeId: id, nodeName: name, nodeType: type, nodePath: path, imageRef, fillIndex: index, suggestedName: `${safeFilename(name || imageRef)}.${formatFromScaleMode(fillRecord.scaleMode)}` });
+			});
+		}
+	});
+
+	return {
+		assets,
+		metadata: {
+			truncated: truncatedReasons.length > 0,
+			truncatedReasons,
+			nextSteps: truncatedReasons.length ? ["Raise maxAssets or extract assets from a narrower child node."] : [],
+		},
+	};
+}
+
+export async function manifestEntryFromFile(candidate: FigmaAssetCandidate, filePath: string, url?: string | null, format?: FigmaAssetManifestEntry["format"]): Promise<FigmaAssetManifestEntry> {
+	const bytes = await readFile(filePath);
+	return { ...candidate, path: filePath, url, format: format ?? formatFromPath(filePath), sha256: sha256(bytes), bytes: bytes.byteLength };
+}
+
+export function manifestEntryFromUrl(candidate: FigmaAssetCandidate, url: string | null | undefined, format: FigmaAssetManifestEntry["format"]): FigmaAssetManifestEntry {
+	return { ...candidate, url: url ?? null, format };
+}
+
+export function sha256(value: Buffer | Uint8Array | string): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+export function safeFilename(value: string): string {
+	return value.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "").toLowerCase() || "figma-asset";
+}
+
+export function formatFromPath(path: string): FigmaAssetManifestEntry["format"] {
+	const extension = extname(path || basename(path)).toLowerCase().replace(/^\./, "");
+	if (extension === "png" || extension === "jpg" || extension === "svg" || extension === "webp") return extension;
+	if (extension === "jpeg") return "jpg";
+	return "unknown";
+}
+
+function formatFromScaleMode(_value: unknown): "png" {
+	return "png";
+}
+
+function isIconCandidate(record: Record<string, unknown>): boolean {
+	const type = String(record.type ?? "UNKNOWN");
+	const name = String(record.name ?? "");
+	const box = asRecord(record.absoluteBoundingBox);
+	const width = numberValue(box.width) ?? 0;
+	const height = numberValue(box.height) ?? 0;
+	return VECTOR_TYPES.has(type) || /\b(icon|logo|glyph)\b/i.test(name) || (width > 0 && height > 0 && width <= 64 && height <= 64 && !Array.isArray(record.children));
+}
+
+function walk(node: unknown, includeHidden: boolean, visit: (record: Record<string, unknown>, path: string, level: number) => void, path = "", level = 0): void {
+	const record = asRecord(node);
+	if (!includeHidden && record.visible === false) return;
+	const name = String(record.name ?? "Unnamed node");
+	const nextPath = path ? `${path} > ${name}` : name;
+	visit(record, nextPath, level);
+	for (const child of Array.isArray(record.children) ? record.children : []) walk(child, includeHidden, visit, nextPath, level + 1);
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+	return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+}
+
+function stringValue(value: unknown): string | undefined {
+	return typeof value === "string" ? value : undefined;
+}
+
+function numberValue(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function clampInteger(value: number, min: number, max: number): number {
+	return Math.max(min, Math.min(max, Math.trunc(value)));
+}

package/node_modules/pi-mono-figma/src/figma-cache.ts

@@ -0,0 +1,6 @@
+import { createTtlCache } from "pi-common/cache";
+
+export const figmaCache = createTtlCache<unknown>({
+	defaultTtlMs: 5 * 60 * 1000,
+	maxEntries: 100,
+});