@sarjallab09/figma-intelligence 1.0.0

package/figma-intelligence-layer/src/tools/phase5-governance/component-spec-sheet/types.ts

@@ -0,0 +1,88 @@
+/**
+ * component-spec-sheet/types.ts — Interfaces for the visual spec sheet tool
+ */
+import type {
+  AnatomyExtraction,
+  NodeSnapshot,
+  SpacingEntry,
+  ClassifiedElement,
+} from "../component-spec/types.js";
+
+// ─── Tool Input ────────────────────────────────────────────────────────────
+
+export type SpecSheetSection = "header" | "anatomy" | "properties" | "spacing";
+
+export interface SpecSheetArgs {
+  nodeId?: string;
+  sections?: SpecSheetSection[];
+  maxVariantsPerAxis?: number;
+  placement?: "right" | "below" | "new-page";
+}
+
+// ─── Planning ──────────────────────────────────────────────────────────────
+
+export interface MarkerPlan {
+  letter: string;
+  markerX: number;
+  markerY: number;
+  targetX: number;
+  targetY: number;
+  name: string;
+  role: string;
+}
+
+export interface VariantSample {
+  variantId: string;
+  label: string;
+  props: Record<string, string>;
+}
+
+export interface PropertyAxisPlan {
+  axisName: string;
+  samples: VariantSample[];
+}
+
+export interface BooleanTogglePlan {
+  name: string;
+  trueVariantId: string | null;
+  falseVariantId: string | null;
+}
+
+export interface SpecSheetPlan {
+  componentName: string;
+  variantLabel: string;
+  sourceNodeId: string;
+  sourceType: string;
+  placement: { x: number; y: number };
+  componentBounds: { w: number; h: number };
+
+  sections: SpecSheetSection[];
+
+  // Anatomy
+  anatomyElements: ClassifiedElement[];
+  markers: MarkerPlan[];
+  anatomyScale: number;
+  anatomyDisplayW: number;
+  anatomyDisplayH: number;
+
+  // Properties
+  propertyAxes: PropertyAxisPlan[];
+  booleanToggles: BooleanTogglePlan[];
+
+  // Spacing
+  spacingEntries: SpacingEntry[];
+}
+
+// ─── Tool Output ───────────────────────────────────────────────────────────
+
+export interface SpecSheetResult {
+  frameId: string;
+  componentName: string;
+  sections: SpecSheetSection[];
+  variantCount: number;
+  anatomyElementCount: number;
+}
+
+// ─── Re-exports for convenience ────────────────────────────────────────────
+
+export type { AnatomyExtraction, NodeSnapshot, SpacingEntry, ClassifiedElement };

package/figma-intelligence-layer/src/tools/phase5-governance/decision-log/index.ts

@@ -0,0 +1,135 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Decision Log Tool
+// Provides log / query / export / clear operations over the shared DecisionLog
+// that records every design action taken across all tools.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { decisionLog } from "../../../shared/decision-log.js";
+import { LogEntry } from "../../../shared/types.js";
+
+// ─── Public types ─────────────────────────────────────────────────────────────
+
+export interface DecisionLogArgs {
+  action: "log" | "query" | "export" | "clear";
+  entry?: {
+    tool: string;
+    nodeIds: string[];
+    rationale: string;
+    tokens?: string[];
+    reversible?: boolean;
+  };
+  query?: string;
+  exportFormat?: "json" | "markdown";
+}
+
+export interface DecisionLogResult {
+  action: "log" | "query" | "export" | "clear";
+  /** Populated for action="log" — the created LogEntry */
+  createdEntry?: LogEntry;
+  /** Populated for action="query" — matching entries */
+  entries?: LogEntry[];
+  /** Populated for action="export" — serialized string */
+  exportedContent?: string;
+  /** Populated for action="clear" — count of removed entries */
+  clearedCount?: number;
+  message: string;
+}
+
+// ─── Action implementations ───────────────────────────────────────────────────
+
+async function actionLog(args: DecisionLogArgs): Promise<DecisionLogResult> {
+  if (!args.entry) {
+    throw new Error(
+      'decisionLogTool: action "log" requires an "entry" object with tool, nodeIds, and rationale.'
+    );
+  }
+
+  const { tool, nodeIds, rationale, tokens, reversible } = args.entry;
+
+  if (!tool) throw new Error('decisionLogTool: entry.tool is required.');
+  if (!rationale) throw new Error('decisionLogTool: entry.rationale is required.');
+
+  const created = await decisionLog.log({
+    tool,
+    nodeIds: nodeIds ?? [],
+    rationale,
+    tokens,
+    reversible: reversible ?? false,
+  });
+
+  return {
+    action: "log",
+    createdEntry: created,
+    message: `Decision logged with id "${created.id}" for tool "${tool}".`,
+  };
+}
+
+async function actionQuery(args: DecisionLogArgs): Promise<DecisionLogResult> {
+  if (!args.query) {
+    throw new Error('decisionLogTool: action "query" requires a "query" string.');
+  }
+
+  const entries = await decisionLog.query(args.query);
+
+  return {
+    action: "query",
+    entries,
+    message: `Found ${entries.length} log entr${entries.length === 1 ? "y" : "ies"} matching query: "${args.query}".`,
+  };
+}
+
+async function actionExport(args: DecisionLogArgs): Promise<DecisionLogResult> {
+  const format = args.exportFormat ?? "json";
+  const exportedContent = await decisionLog.export(format);
+
+  const sizeKb = (Buffer.byteLength(exportedContent, "utf-8") / 1024).toFixed(1);
+
+  return {
+    action: "export",
+    exportedContent,
+    message: `Exported decision log as ${format} (${sizeKb} KB).`,
+  };
+}
+
+async function actionClear(): Promise<DecisionLogResult> {
+  // Read the current count before clearing so we can report it
+  const beforeExport = await decisionLog.export("json");
+  let clearedCount = 0;
+  try {
+    const entries: LogEntry[] = JSON.parse(beforeExport);
+    clearedCount = Array.isArray(entries) ? entries.length : 0;
+  } catch {
+    clearedCount = 0;
+  }
+
+  await decisionLog.clear();
+
+  return {
+    action: "clear",
+    clearedCount,
+    message: `Cleared ${clearedCount} decision log entr${clearedCount === 1 ? "y" : "ies"}.`,
+  };
+}
+
+// ─── Main handler ─────────────────────────────────────────────────────────────
+
+export async function decisionLogToolHandler(
+  args: DecisionLogArgs
+): Promise<DecisionLogResult> {
+  switch (args.action) {
+    case "log":
+      return actionLog(args);
+    case "query":
+      return actionQuery(args);
+    case "export":
+      return actionExport(args);
+    case "clear":
+      return actionClear();
+    default: {
+      const exhaustive: never = args.action;
+      throw new Error(
+        `decisionLogTool: Unknown action "${exhaustive}". Valid actions: log | query | export | clear.`
+      );
+    }
+  }
+}