devendra-skill-package 1.0.2

package/.github/skills/feature-generator/references/state-library-patterns.md

@@ -0,0 +1,464 @@
+# State Library Patterns Reference
+
+Used by Phase 5 of feature-generator to generate the state layer.
+Select the section matching `fingerprint.stateLib`.
+
+Phase 5.1 (Redux Toolkit) is fully detailed in SKILL.MD. This file covers:
+- Redux Toolkit direct-import pattern (alternative to thunk-extra)
+- Zustand
+- MobX
+- Context API
+
+---
+
+## Redux Toolkit — thunk-extra pattern
+
+**When**: `fingerprint.stateLib = "redux-toolkit"` AND `fingerprint.thunkPattern = "thunk-extra"`
+
+See SKILL.MD Phase 5.1. This is the primary RTK pattern. Use cases are injected
+via `{ extra }` in the thunk. The store config file wires them as `extraArgument`.
+
+### Reducer key constraint
+
+The new slice name MUST NOT collide with existing keys in `fingerprint.reducerMapKeys`.
+If `reducerKey` is already taken, append a suffix: `<reducerKey>Feature`.
+
+### DI instruction comment (always add to diBootstrap.ts)
+
+```typescript
+// To activate this feature:
+// In <fingerprint.storeConfigFile>, add to middleware extraArgument:
+//
+//   fetch<ScreenName>UseCase: fetch<ScreenName>UseCase
+//
+// Then add the reducer to the configureStore reducer map:
+//
+//   <reducerKey>: <sliceName>Reducer
+```
+
+---
+
+## Redux Toolkit — direct-import pattern
+
+**When**: `fingerprint.stateLib = "redux-toolkit"` AND `fingerprint.thunkPattern = "direct-import"`
+
+The use case instance is imported directly into the slice file. No `extra` argument is used.
+
+### Slice template
+
+```typescript
+import { createSlice, createAsyncThunk } from '@reduxjs/toolkit';
+import type { PayloadAction } from '@reduxjs/toolkit'; // only when slice uses PayloadAction in reducers
+import type { <ScreenName>Item } from '<relative-path-to-domainModel>';
+// Direct import — no thunk-extra injection
+import { fetch<ScreenName>UseCase } from '<relative-path-to-diBootstrap>';
+
+export interface <ScreenName>State {
+  items: <ScreenName>Item[];
+  isLoading: boolean;
+  isRefreshing: boolean;
+  error: string | null;
+  isAuthError: boolean;
+}
+
+const initialState: <ScreenName>State = {
+  items: [],
+  isLoading: false,
+  isRefreshing: false,
+  error: null,
+  isAuthError: false,
+};
+
+export const fetch<ScreenName>Thunk = createAsyncThunk(
+  '<sliceName>/fetch',
+  async (params: { clientCode: number; sessionId: string }, { rejectWithValue }) => {
+    try {
+      // No 'extra' — use case imported directly above
+      const result = await fetch<ScreenName>UseCase.execute(params);
+      if (!result.ok) {
+        return rejectWithValue({ message: result.error ?? 'Unknown error', isAuthError: false });
+      }
+      return result.data;
+    } catch (err: unknown) {
+      const apiErr = err as { statusCode?: number; message?: string };
+      return rejectWithValue({
+        message: apiErr.message ?? 'Unexpected error',
+        isAuthError: apiErr.statusCode === 401,
+      });
+    }
+  },
+);
+
+const <sliceName>Slice = createSlice({
+  name: '<sliceName>',
+  initialState,
+  reducers: {
+    reset<ScreenName>: () => initialState,
+  },
+  extraReducers: (builder) => {
+    builder
+      .addCase(fetch<ScreenName>Thunk.pending, (state) => {
+        state.isLoading = true;
+        state.error = null;
+        state.isAuthError = false;
+      })
+      .addCase(fetch<ScreenName>Thunk.fulfilled, (state, action) => {
+        state.isLoading = false;
+        state.items = action.payload ?? [];
+      })
+      .addCase(fetch<ScreenName>Thunk.rejected, (state, action) => {
+        state.isLoading = false;
+        const payload = action.payload as { message: string; isAuthError: boolean };
+        state.error = payload?.message ?? 'Failed to load';
+        state.isAuthError = payload?.isAuthError ?? false;
+      });
+  },
+});
+
+export const { reset<ScreenName> } = <sliceName>Slice.actions;
+export default <sliceName>Slice.reducer;
+```
+
+### Notes
+
+- The diBootstrap.ts exports the use case instance that is imported here.
+- This pattern creates a circular-dependency risk if the diBootstrap also imports from the slice.
+  If detected, switch to thunk-extra and log a WARN.
+
+---
+
+## Zustand
+
+**When**: `fingerprint.stateLib = "zustand"`
+
+Detect the Zustand version from package.json (`"zustand": "^4.x"` vs `"^5.x"`).
+Read 1-2 existing store files to determine whether the project uses:
+  - Slice pattern (multiple `create()` calls combined)
+  - Single store (one `create()` with nested state)
+  - Immer middleware
+
+### Single store template (v4, no immer)
+
+```typescript
+import { create } from 'zustand';
+import type { <ScreenName>Item } from '<relative-path-to-domainModel>';
+import { fetch<ScreenName>UseCase } from '<relative-path-to-diBootstrap>';
+
+export interface <ScreenName>Store {
+  items: <ScreenName>Item[];
+  isLoading: boolean;
+  error: string | null;
+  fetch<ScreenName>: (params: { clientCode: number; sessionId: string }) => Promise<void>;
+  reset: () => void;
+}
+
+const initialState = {
+  items: [] as <ScreenName>Item[],
+  isLoading: false,
+  error: null as string | null,
+};
+
+export const use<ScreenName>Store = create<<ScreenName>Store>()((set) => ({
+  ...initialState,
+
+  fetch<ScreenName>: async (params) => {
+    set({ isLoading: true, error: null });
+    try {
+      // ----- result-wrapper (fingerprint.returnTypeStyle = "result-wrapper") -----
+      const result = await fetch<ScreenName>UseCase.execute(params);
+      if (!result.ok) {
+        set({ isLoading: false, error: result.error ?? 'Failed to load' });
+        return;
+      }
+      set({ isLoading: false, items: result.data ?? [] });
+
+      // ----- custom-type (fingerprint.returnTypeStyle = "custom-type") -----
+      // const result = await fetch<ScreenName>UseCase.execute(params);
+      // set({ isLoading: false, items: result.<primaryField> ?? [] });
+
+      // ----- direct-promise (fingerprint.returnTypeStyle = "direct-promise") -----
+      // const items = await fetch<ScreenName>UseCase.execute(params);
+      // set({ isLoading: false, items });
+    } catch (err: unknown) {
+      const apiErr = err as { message?: string };
+      set({ isLoading: false, error: apiErr.message ?? 'Unexpected error' });
+    }
+  },
+
+  reset: () => set(initialState),
+}));
+```
+
+### Single store template (v4, with immer middleware)
+
+If existing stores use `immer`, wrap `create` with the immer middleware:
+
+```typescript
+import { create } from 'zustand';
+import { immer } from 'zustand/middleware/immer';
+// ... rest same as above but use draft mutations inside set callbacks
+```
+
+### Slice pattern (v4)
+
+> `<screenNameCamelCase>` = camelCase of the screen name (e.g. `TransactionHistory` → `transactionHistory`).
+> Use this as a property prefix to avoid collisions when multiple slices share a single Zustand store.
+
+If the project combines multiple slices, generate a slice function and merge:
+
+```typescript
+import type { StateCreator } from 'zustand';
+import type { <ScreenName>Item } from '<relative-path-to-domainModel>';
+
+export interface <ScreenName>Slice {
+  <screenNameCamelCase>Items: <ScreenName>Item[];
+  <screenNameCamelCase>Loading: boolean;
+  <screenNameCamelCase>Error: string | null;
+  fetch<ScreenName>: (params: { clientCode: number; sessionId: string }) => Promise<void>;
+}
+
+export const create<ScreenName>Slice: StateCreator<<ScreenName>Slice> = (set) => ({
+  <screenNameCamelCase>Items: [],
+  <screenNameCamelCase>Loading: false,
+  <screenNameCamelCase>Error: null,
+
+  fetch<ScreenName>: async (params) => {
+    set({ <screenNameCamelCase>Loading: true, <screenNameCamelCase>Error: null });
+    // ... same async logic
+  },
+});
+```
+
+### Selector pattern for Zustand
+
+Do NOT generate a separate selectors file for Zustand.
+Selectors are inline in the component using `use<ScreenName>Store`:
+
+```typescript
+// In the screen component:
+const items = use<ScreenName>Store((state) => state.items);
+const isLoading = use<ScreenName>Store((state) => state.isLoading);
+```
+
+---
+
+## MobX
+
+**When**: `fingerprint.stateLib = "mobx"`
+
+Detect whether the project uses `makeAutoObservable` (MobX 6+) or `@observable`
+decorators (MobX 4/5 with legacy decorator support).
+
+### Store class template (MobX 6 — makeAutoObservable)
+
+```typescript
+import { makeAutoObservable, runInAction } from 'mobx';
+import type { <ScreenName>Item } from '<relative-path-to-domainModel>';
+import { fetch<ScreenName>UseCase } from '<relative-path-to-diBootstrap>';
+
+export class <ScreenName>Store {
+  items: <ScreenName>Item[] = [];
+  isLoading = false;
+  error: string | null = null;
+
+  constructor() {
+    makeAutoObservable(this);
+  }
+
+  async fetch<ScreenName>(params: { clientCode: number; sessionId: string }): Promise<void> {
+    this.isLoading = true;
+    this.error = null;
+    try {
+      // ----- result-wrapper (fingerprint.returnTypeStyle = "result-wrapper") -----
+      const result = await fetch<ScreenName>UseCase.execute(params);
+      runInAction(() => {
+        if (!result.ok) {
+          this.error = result.error ?? 'Failed to load';
+        } else {
+          this.items = result.data ?? [];
+        }
+        this.isLoading = false;
+      });
+
+      // ----- custom-type (fingerprint.returnTypeStyle = "custom-type") -----
+      // const result = await fetch<ScreenName>UseCase.execute(params);
+      // runInAction(() => { this.items = result.<primaryField> ?? []; this.isLoading = false; });
+
+      // ----- direct-promise (fingerprint.returnTypeStyle = "direct-promise") -----
+      // const items = await fetch<ScreenName>UseCase.execute(params);
+      // runInAction(() => { this.items = items; this.isLoading = false; });
+    } catch (err: unknown) {
+      runInAction(() => {
+        const apiErr = err as { message?: string };
+        this.error = apiErr.message ?? 'Unexpected error';
+        this.isLoading = false;
+      });
+    }
+  }
+
+  reset(): void {
+    this.items = [];
+    this.isLoading = false;
+    this.error = null;
+  }
+}
+
+export const <screenNameCamelCase>Store = new <ScreenName>Store();
+```
+
+### Notes for MobX
+
+- Do NOT generate a Redux slice, selectors file, or thunk.
+- The screen component accesses store via the singleton exported above, wrapped in `observer()`.
+- Do NOT generate a separate selectors file — computed values are class getters:
+
+```typescript
+get hasItems(): boolean {
+  return this.items.length > 0;
+}
+```
+
+---
+
+## Context API
+
+**When**: `fingerprint.stateLib = "context-api"`
+
+Detect whether the project uses `useReducer + createContext` or `useState + createContext`.
+Read existing context files before generating.
+
+### useReducer + createContext template
+
+```typescript
+import React, { createContext, useContext, useReducer, type ReactNode } from 'react';
+import type { <ScreenName>Item } from '<relative-path-to-domainModel>';
+import { fetch<ScreenName>UseCase } from '<relative-path-to-diBootstrap>';
+
+// ---- State shape ----
+
+interface <ScreenName>State {
+  items: <ScreenName>Item[];
+  isLoading: boolean;
+  error: string | null;
+}
+
+const initialState: <ScreenName>State = {
+  items: [],
+  isLoading: false,
+  error: null,
+};
+
+// ---- Actions ----
+
+type <ScreenName>Action =
+  | { type: 'FETCH_START' }
+  | { type: 'FETCH_SUCCESS'; payload: <ScreenName>Item[] }
+  | { type: 'FETCH_ERROR'; payload: string }
+  | { type: 'RESET' };
+
+// ---- Reducer ----
+
+function <screenNameCamelCase>Reducer(
+  state: <ScreenName>State,
+  action: <ScreenName>Action,
+): <ScreenName>State {
+  switch (action.type) {
+    case 'FETCH_START':
+      return { ...state, isLoading: true, error: null };
+    case 'FETCH_SUCCESS':
+      return { ...state, isLoading: false, items: action.payload };
+    case 'FETCH_ERROR':
+      return { ...state, isLoading: false, error: action.payload };
+    case 'RESET':
+      return initialState;
+    default:
+      return state;
+  }
+}
+
+// ---- Context ----
+
+interface <ScreenName>ContextValue {
+  state: <ScreenName>State;
+  fetch<ScreenName>: (params: { clientCode: number; sessionId: string }) => Promise<void>;
+  reset: () => void;
+}
+
+const <ScreenName>Context = createContext<<ScreenName>ContextValue | null>(null);
+
+// ---- Provider ----
+
+export function <ScreenName>Provider({ children }: { children: ReactNode }): React.JSX.Element {
+  const [state, dispatch] = useReducer(<screenNameCamelCase>Reducer, initialState);
+
+  async function fetch<ScreenName>(params: { clientCode: number; sessionId: string }): Promise<void> {
+    dispatch({ type: 'FETCH_START' });
+    try {
+      // ----- result-wrapper (fingerprint.returnTypeStyle = "result-wrapper") -----
+      const result = await fetch<ScreenName>UseCase.execute(params);
+      if (!result.ok) {
+        dispatch({ type: 'FETCH_ERROR', payload: result.error ?? 'Failed to load' });
+        return;
+      }
+      dispatch({ type: 'FETCH_SUCCESS', payload: result.data ?? [] });
+
+      // ----- custom-type (fingerprint.returnTypeStyle = "custom-type") -----
+      // const result = await fetch<ScreenName>UseCase.execute(params);
+      // dispatch({ type: 'FETCH_SUCCESS', payload: result.<primaryField> ?? [] });
+
+      // ----- direct-promise (fingerprint.returnTypeStyle = "direct-promise") -----
+      // const items = await fetch<ScreenName>UseCase.execute(params);
+      // dispatch({ type: 'FETCH_SUCCESS', payload: items });
+    } catch (err: unknown) {
+      const apiErr = err as { message?: string };
+      dispatch({ type: 'FETCH_ERROR', payload: apiErr.message ?? 'Unexpected error' });
+    }
+  }
+
+  function reset(): void {
+    dispatch({ type: 'RESET' });
+  }
+
+  return (
+    <{ScreenName}Context.Provider value={{ state, fetch<ScreenName>, reset }}>
+      {children}
+    </{ScreenName}Context.Provider>
+  );
+}
+
+// ---- Hook ----
+
+export function use<ScreenName>Context(): <ScreenName>ContextValue {
+  const ctx = useContext(<ScreenName>Context);
+  if (ctx === null) {
+    throw new Error('use<ScreenName>Context must be used within <ScreenName>Provider');
+  }
+  return ctx;
+}
+```
+
+### Notes for Context API
+
+- Do NOT generate a Redux slice or thunk.
+- Do NOT generate a selectors file.
+- The screen component wraps in `<ScreenName>Provider>` and accesses state via
+  `use<ScreenName>Context()`.
+- Add a note in the output summary that the user must wrap the screen (or its parent navigator)
+  with the Provider.
+
+---
+
+## State fields from screenLogic — all patterns
+
+The following screenLogic phrases map to additional state fields regardless of state lib:
+
+| screenLogic phrase | Additional state field | Reducer/setter |
+|---|---|---|
+| "filter by category" | `filter: string` | `setFilter` action / setter |
+| "sortable by field" | `sortOrder: 'asc' \| 'desc'`, `sortField: string` | `setSortOrder`, `setSortField` |
+| "selected item detail" | `selectedItemId: string \| null` | `setSelectedItemId` |
+| "tab switcher" | `activeTab: string` | `setActiveTab` |
+| "pagination" | `page: number`, `hasMore: boolean` | `setPage`, `appendItems` |
+| "search query" | `searchQuery: string` | `setSearchQuery` |
+| "date range filter" | `fromDate: string`, `toDate: string` | `setDateRange` |
+| "family flag toggle" | `familyFlag: 0 \| 1` | `setFamilyFlag` |

package/.github/skills/figma-ui-mapper/README.md

@@ -0,0 +1,34 @@
+# figma-ui-mapper
+
+Framework-agnostic Figma-to-code generation skill.
+
+## Supported Frameworks
+- react
+- react-native
+- flutter
+- angular
+- vue
+- next
+- nuxt
+- svelte
+- expo
+- native-android
+- native-ios
+- kotlin-multiplatform
+- ionic
+- capacitor
+
+## Entrypoints
+- node ./scripts/generate-page-through-figma.js
+- node ./scripts/generate-react-page-through-figma.js
+
+## Core Workflow
+See references/workflow.md.
+
+## Script Help
+Run with --help for CLI options.
+
+## Outputs
+Script scaffolding writes to target project:
+- .figma-ui-mapper/reports/
+- .figma-ui-mapper/artifacts/

package/.github/skills/figma-ui-mapper/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: figma-ui-mapper
+description: Framework-agnostic Figma-to-code generation skill that detects target project and framework, loads matching adapter rules, scaffolds generation files, and executes component-first workflow with validation and reporting gates.
+---
+
+## Purpose
+Generate production-ready UI code from Figma for supported frameworks using one consistent workflow with strict validation, reporting, and backward-compatible React invocation.
+
+## Trigger Conditions
+Use this skill when:
+- User asks to generate pages or screens from one or more Figma URLs.
+- User asks to scaffold page, component, asset, report, and artifact structures before implementation.
+- User asks for framework auto-detection in single-app or monorepo repositories.
+
+Do not use when:
+- No Figma URL is provided.
+- The request is design analysis only with no code generation.
+
+## Inputs
+Required:
+- figma_urls: one or more node-specific Figma URLs.
+- page_path: root path for generated pages.
+- component_path: root path for generated components.
+- reusable_components_path: path to shared reusable components.
+
+Optional:
+- asset_path: root path for static assets (default: src/assets).
+- links_file: text or JSON file containing multiple Figma URLs.
+- pages_json: JSON array of pageName + figmaUrl pairs.
+- project_path: target app path in monorepos.
+- non_interactive: disable prompts and require all required flags.
+- dry_run: compute outputs without writing files.
+
+## References
+### Common References
+- ./references/workflow.md
+- ./references/script-usage.md
+- ./references/common.md
+
+### Platform References
+Load only one platform reference based on detected framework:
+- ./references/react.md
+- ./references/react-native.md
+- ./references/flutter.md
+- ./references/angular.md
+- ./references/vue.md
+- ./references/next.md
+- ./references/nuxt.md
+- ./references/svelte.md
+- ./references/expo.md
+- ./references/native-android.md
+- ./references/native-ios.md
+- ./references/kotlin-multiplatform.md
+- ./references/ionic.md
+- ./references/capacitor.md
+
+Framework adapter rule files:
+- ./references/frameworks/<detected-framework>/rules.md
+
+## Assets
+- ./assets/templates/generation-report-template.md
+- ./assets/templates/component-map-template.md
+
+## Scripts
+- ./scripts/generate-page-through-figma.js
+- ./scripts/generate-react-page-through-figma.js
+
+## Execution Steps
+1. Validate inputs and resolve target project context.
+2. Detect framework and architecture from repository signals.
+3. Validate active adapter and load only matching reference/rule files.
+4. Run script-first scaffolding and create adapter-specific page/style/token files.
+5. Execute component-first MCP workflow in references/workflow.md.
+6. Enforce blocking validation gates: coverage, accessibility, screenshot loop, and final QA.
+7. Render report/template outputs and persist artifact summary.
+
+## Rules
+- Keep workflow phases and quality gates intact.
+- Do not skip token extraction, coverage checks, accessibility checks, screenshot validation, or final QA.
+- Load only one framework adapter per run.
+- Keep platform-specific logic in references, not inline in this file.
+- Keep templates in assets and render them during output generation.
+- Do not include secrets in scripts or references.
+
+## Output Format
+Return a structured result with:
+- detected_framework
+- detection_reason
+- framework_adapter_used
+- framework_version
+- architecture_detected
+- pages_requested
+- pages_generated
+- pages_skipped
+- components_reused
+- components_generated
+- validation_summary
+- warnings
+- errors
+- report_path
+- artifact_path

package/.github/skills/figma-ui-mapper/assets/templates/component-map-template.md

@@ -0,0 +1,30 @@
+# Component Map - {{page_name}}
+
+## Inputs
+- figma_url: {{figma_url}}
+- file_key: {{file_key}}
+- node_id: {{node_id}}
+
+## Page Container
+- frame_name: {{frame_name}}
+- node_id: {{node_id}}
+- size: {{size}}
+
+## Sections
+{{sections_table}}
+
+## Reusable Components
+{{reusable_components_table}}
+
+## Assets
+{{assets_table}}
+
+## Coverage Links
+- inventory_reference: {{inventory_reference}}
+- coverage_map_reference: {{coverage_map_reference}}
+
+## Generation Order
+{{generation_order}}
+
+## Status
+{{status_table}}

package/.github/skills/figma-ui-mapper/assets/templates/generation-report-template.md

@@ -0,0 +1,49 @@
+# Figma UI Mapper Generation Report
+
+## Inputs
+- generated_at: {{generated_at}}
+- project_root: {{project_root}}
+- figma_urls: {{figma_urls}}
+- page_path: {{page_path}}
+- component_path: {{component_path}}
+- asset_path: {{asset_path}}
+- reusable_components_path: {{reusable_components_path}}
+
+## Framework
+- detected_framework: {{detected_framework}}
+- framework_version: {{framework_version}}
+- architecture_detected: {{architecture_detected}}
+- detection_reason: {{detection_reason}}
+- adapter_used: {{adapter_used}}
+- platform_reference: {{platform_reference}}
+- framework_rules: {{framework_rules}}
+
+## Coverage
+- pages_requested: {{pages_requested}}
+- pages_generated: {{pages_generated}}
+- pages_skipped: {{pages_skipped}}
+- coverage_map_match: {{coverage_map_match}}
+
+## Components
+- components_reused: {{components_reused}}
+- components_generated: {{components_generated}}
+
+## Tokens and Assets
+- token_extraction: {{token_extraction}}
+- assets_resolved_local: {{assets_resolved_local}}
+- assets_downloaded_figma: {{assets_downloaded_figma}}
+- asset_failures: {{asset_failures}}
+
+## Validation
+- component_first_generation: {{component_first_generation}}
+- accessibility_check: {{accessibility_check}}
+- screenshot_comparison: {{screenshot_comparison}}
+- iteration_count: {{iteration_count}}
+- qa_status: {{qa_status}}
+
+## Errors and Warnings
+- errors: {{errors}}
+- warnings: {{warnings}}
+
+## Summary
+{{summary}}

package/.github/skills/figma-ui-mapper/metadata.yaml

@@ -0,0 +1,22 @@
+name: figma-ui-mapper
+version: 1.1.0
+status: active
+description: Framework-agnostic Figma-to-code generation skill with adapter-based scaffolding and workflow-driven MCP implementation.
+entrypoints:
+  - scripts/generate-page-through-figma.js
+  - scripts/generate-react-page-through-figma.js
+supported_frameworks:
+  - react
+  - react-native
+  - flutter
+  - angular
+  - vue
+  - next
+  - nuxt
+  - svelte
+  - expo
+  - native-android
+  - native-ios
+  - kotlin-multiplatform
+  - ionic
+  - capacitor