@pattern-stack/frontend-patterns 0.2.0-alpha.0 → 0.2.0-alpha.1

package/cli/commands/generate-hooks.ts

@@ -8,11 +8,15 @@
 
 import { promises as fs } from 'fs'
 import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
 import { loadOpenAPISpec, parseOpenAPI } from '../../src/codegen/openapi/parser.js'
 import { generateTypes } from '../../src/codegen/openapi/type-generator.js'
 import { generateAPIClient } from '../../src/codegen/openapi/client-generator.js'
 import { generateHooks } from '../../src/codegen/openapi/hook-generator.js'
 
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
 interface GenerateHooksOptions {
   output: string
   prefix?: string
@@ -121,6 +125,11 @@ export async function generateHooksCommand(source: string, options: GenerateHook
     await writeFile(join(options.output, 'hooks', 'keys.ts'), hooks.keys)
     await writeFile(join(options.output, 'hooks', 'types.ts'), hooks.types)
     await writeFile(join(options.output, 'hooks', 'index.ts'), hooks.index)
+
+    // Copy bulk-types.ts to output directory (referenced by hooks/types.ts)
+    const bulkTypesPath = join(__dirname, '../../src/codegen/openapi/bulk-types.ts')
+    const bulkTypesContent = await fs.readFile(bulkTypesPath, 'utf8')
+    await writeFile(join(options.output, 'bulk-types.ts'), bulkTypesContent)
     
     // Write confidence report if available
     if (hooks.report) {
@@ -154,10 +163,10 @@ export { queryKeys } from './hooks'`
     
     await writeFile(join(options.output, 'index.ts'), mainIndex)
     
-    // Generate usage example
+    // Generate usage example (as .tsx since it contains JSX)
     const usageExample = generateUsageExample(spec.info.title, options)
-    await writeFile(join(options.output, 'example.ts'), usageExample)
-    
+    await writeFile(join(options.output, 'example.tsx'), usageExample)
+
     console.log()
     console.log('✅ Generation complete!')
     console.log(`📦 Generated files in: ${options.output}`)
@@ -165,7 +174,7 @@ export { queryKeys } from './hooks'`
     console.log('🚀 Quick start:')
     console.log(`import { createAPIClient, useGetUsers } from './${options.output}'`)
     console.log()
-    console.log('💡 See example.ts for detailed usage instructions')
+    console.log('💡 See example.tsx for detailed usage instructions')
     
   } catch (error) {
     console.error('❌ Generation failed:')

package/cli/src/codegen/openapi/__tests__/naming-utils.test.js

@@ -0,0 +1,367 @@
+import { singularize, pluralize, isPlural } from '../naming-utils.js';
+
+describe('singularize()', () => {
+  describe('regular plurals', () => {
+    it('should convert cats to cat', () => {
+      expect(singularize('cats')).toBe('cat');
+    });
+
+    it('should convert dogs to dog', () => {
+      expect(singularize('dogs')).toBe('dog');
+    });
+
+    it('should convert users to user', () => {
+      expect(singularize('users')).toBe('user');
+    });
+
+    it('should convert accounts to account', () => {
+      expect(singularize('accounts')).toBe('account');
+    });
+  });
+
+  describe('-ies plurals', () => {
+    it('should convert activities to activity', () => {
+      expect(singularize('activities')).toBe('activity');
+    });
+
+    it('should convert categories to category', () => {
+      expect(singularize('categories')).toBe('category');
+    });
+
+    it('should convert companies to company', () => {
+      expect(singularize('companies')).toBe('company');
+    });
+
+    it('should convert opportunities to opportunity', () => {
+      expect(singularize('opportunities')).toBe('opportunity');
+    });
+  });
+
+  describe('-es plurals', () => {
+    it('should convert boxes to box', () => {
+      expect(singularize('boxes')).toBe('box');
+    });
+
+    it('should convert watches to watch', () => {
+      expect(singularize('watches')).toBe('watch');
+    });
+
+    it('should convert dishes to dish', () => {
+      expect(singularize('dishes')).toBe('dish');
+    });
+
+    it('should convert benches to bench', () => {
+      expect(singularize('benches')).toBe('bench');
+    });
+  });
+
+  describe('-ses plurals (tricky cases)', () => {
+    it('should convert addresses to address', () => {
+      expect(singularize('addresses')).toBe('address');
+    });
+
+    it('should convert businesses to business', () => {
+      expect(singularize('businesses')).toBe('business');
+    });
+
+    it('should convert processes to process', () => {
+      expect(singularize('processes')).toBe('process');
+    });
+  });
+
+  describe('irregular plurals', () => {
+    it('should convert people to person', () => {
+      expect(singularize('people')).toBe('person');
+    });
+
+    it('should convert children to child', () => {
+      expect(singularize('children')).toBe('child');
+    });
+
+    it('should convert men to man', () => {
+      expect(singularize('men')).toBe('man');
+    });
+
+    it('should convert women to woman', () => {
+      expect(singularize('women')).toBe('woman');
+    });
+  });
+
+  describe('already singular', () => {
+    it('should keep data as data', () => {
+      expect(singularize('data')).toBe('data');
+    });
+
+    it('should keep metadata as metadata', () => {
+      expect(singularize('metadata')).toBe('metadata');
+    });
+
+    it('should keep user as user', () => {
+      expect(singularize('user')).toBe('user');
+    });
+
+    it('should keep account as account', () => {
+      expect(singularize('account')).toBe('account');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should keep status as status', () => {
+      expect(singularize('status')).toBe('status');
+    });
+
+    it('should keep class as class', () => {
+      expect(singularize('class')).toBe('class');
+    });
+
+    it('should keep bus as bus', () => {
+      expect(singularize('bus')).toBe('bus');
+    });
+
+    it('should convert pass to pass (not pas)', () => {
+      expect(singularize('pass')).toBe('pass');
+    });
+
+    it('should handle empty string', () => {
+      expect(singularize('')).toBe('');
+    });
+
+    it('should handle single character', () => {
+      expect(singularize('a')).toBe('a');
+    });
+  });
+});
+
+describe('pluralize()', () => {
+  describe('regular plurals', () => {
+    it('should convert cat to cats', () => {
+      expect(pluralize('cat')).toBe('cats');
+    });
+
+    it('should convert dog to dogs', () => {
+      expect(pluralize('dog')).toBe('dogs');
+    });
+
+    it('should convert user to users', () => {
+      expect(pluralize('user')).toBe('users');
+    });
+
+    it('should convert account to accounts', () => {
+      expect(pluralize('account')).toBe('accounts');
+    });
+  });
+
+  describe('-y endings (consonant + y)', () => {
+    it('should convert activity to activities', () => {
+      expect(pluralize('activity')).toBe('activities');
+    });
+
+    it('should convert category to categories', () => {
+      expect(pluralize('category')).toBe('categories');
+    });
+
+    it('should convert company to companies', () => {
+      expect(pluralize('company')).toBe('companies');
+    });
+
+    it('should convert opportunity to opportunities', () => {
+      expect(pluralize('opportunity')).toBe('opportunities');
+    });
+  });
+
+  describe('vowel + y endings', () => {
+    it('should convert day to days', () => {
+      expect(pluralize('day')).toBe('days');
+    });
+
+    it('should convert key to keys', () => {
+      expect(pluralize('key')).toBe('keys');
+    });
+
+    it('should convert boy to boys', () => {
+      expect(pluralize('boy')).toBe('boys');
+    });
+
+    it('should convert array to arrays', () => {
+      expect(pluralize('array')).toBe('arrays');
+    });
+  });
+
+  describe('-x, -ch, -sh, -s, -ss endings', () => {
+    it('should convert box to boxes', () => {
+      expect(pluralize('box')).toBe('boxes');
+    });
+
+    it('should convert watch to watches', () => {
+      expect(pluralize('watch')).toBe('watches');
+    });
+
+    it('should convert dish to dishes', () => {
+      expect(pluralize('dish')).toBe('dishes');
+    });
+
+    it('should convert bench to benches', () => {
+      expect(pluralize('bench')).toBe('benches');
+    });
+
+    it('should convert address to addresses', () => {
+      expect(pluralize('address')).toBe('addresses');
+    });
+
+    it('should convert business to businesses', () => {
+      expect(pluralize('business')).toBe('businesses');
+    });
+
+    it('should convert class to classes', () => {
+      expect(pluralize('class')).toBe('classes');
+    });
+  });
+
+  describe('irregular plurals', () => {
+    it('should convert person to people', () => {
+      expect(pluralize('person')).toBe('people');
+    });
+
+    it('should convert child to children', () => {
+      expect(pluralize('child')).toBe('children');
+    });
+
+    it('should convert man to men', () => {
+      expect(pluralize('man')).toBe('men');
+    });
+
+    it('should convert woman to women', () => {
+      expect(pluralize('woman')).toBe('women');
+    });
+  });
+
+  describe('already plural (no double-pluralize)', () => {
+    it('should keep accounts as accounts', () => {
+      expect(pluralize('accounts')).toBe('accounts');
+    });
+
+    it('should keep users as users', () => {
+      expect(pluralize('users')).toBe('users');
+    });
+
+    it('should keep activities as activities', () => {
+      expect(pluralize('activities')).toBe('activities');
+    });
+
+    it('should keep boxes as boxes', () => {
+      expect(pluralize('boxes')).toBe('boxes');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle empty string', () => {
+      expect(pluralize('')).toBe('');
+    });
+
+    it('should handle single character', () => {
+      expect(pluralize('a')).toBe('as');
+    });
+
+    it('should keep status as status (special case)', () => {
+      expect(pluralize('status')).toBe('status');
+    });
+  });
+});
+
+describe('isPlural()', () => {
+  describe('should return true for plural words', () => {
+    it('should identify cats as plural', () => {
+      expect(isPlural('cats')).toBe(true);
+    });
+
+    it('should identify activities as plural', () => {
+      expect(isPlural('activities')).toBe(true);
+    });
+
+    it('should identify boxes as plural', () => {
+      expect(isPlural('boxes')).toBe(true);
+    });
+
+    it('should identify watches as plural', () => {
+      expect(isPlural('watches')).toBe(true);
+    });
+
+    it('should identify addresses as plural', () => {
+      expect(isPlural('addresses')).toBe(true);
+    });
+
+    it('should identify people as plural', () => {
+      expect(isPlural('people')).toBe(true);
+    });
+
+    it('should identify children as plural', () => {
+      expect(isPlural('children')).toBe(true);
+    });
+
+    it('should identify users as plural', () => {
+      expect(isPlural('users')).toBe(true);
+    });
+
+    it('should identify accounts as plural', () => {
+      expect(isPlural('accounts')).toBe(true);
+    });
+  });
+
+  describe('should return false for singular words', () => {
+    it('should identify cat as singular', () => {
+      expect(isPlural('cat')).toBe(false);
+    });
+
+    it('should identify activity as singular', () => {
+      expect(isPlural('activity')).toBe(false);
+    });
+
+    it('should identify box as singular', () => {
+      expect(isPlural('box')).toBe(false);
+    });
+
+    it('should identify user as singular', () => {
+      expect(isPlural('user')).toBe(false);
+    });
+
+    it('should identify account as singular', () => {
+      expect(isPlural('account')).toBe(false);
+    });
+  });
+
+  describe('should return false for edge cases', () => {
+    it('should identify status as singular', () => {
+      expect(isPlural('status')).toBe(false);
+    });
+
+    it('should identify class as singular', () => {
+      expect(isPlural('class')).toBe(false);
+    });
+
+    it('should identify bus as singular', () => {
+      expect(isPlural('bus')).toBe(false);
+    });
+
+    it('should identify process as singular', () => {
+      expect(isPlural('process')).toBe(false);
+    });
+
+    it('should identify data as singular', () => {
+      expect(isPlural('data')).toBe(false);
+    });
+
+    it('should identify metadata as singular', () => {
+      expect(isPlural('metadata')).toBe(false);
+    });
+  });
+
+  describe('should handle empty/minimal input', () => {
+    it('should return false for empty string', () => {
+      expect(isPlural('')).toBe(false);
+    });
+
+    it('should return false for single character', () => {
+      expect(isPlural('a')).toBe(false);
+    });
+  });
+});

package/cli/src/codegen/openapi/client-generator.js

@@ -6,6 +6,9 @@
  *
  * Part of FRO-12: API Client Generator
  */
+import { singularize, pluralize, isPlural } from './naming-utils.js';
+import { AUTH_ACTIONS, HEALTH_ENDPOINTS, USER_PROFILE_ENDPOINTS, SINGLETON_RESOURCES, COLLECTION_ACTIONS } from './naming-constants.js';
+
 export class APIClientGenerator {
     options;
     constructor(options = {}) {
@@ -39,7 +42,7 @@ export class APIClientGenerator {
     generateAxiosClient() {
         return `/**
  * Axios API Client
- * 
+ *
  * Auto-generated API client with interceptors and error handling
  */
 
@@ -146,7 +149,7 @@ export class APIClient {
     generateFetchClient() {
         return `/**
  * Fetch API Client
- * 
+ *
  * Auto-generated API client using native fetch with error handling
  */
 
@@ -166,7 +169,7 @@ export class APIClient {
   ): Promise<T> {
     try {
       const fullUrl = this.buildUrl(url, options.params)
-      
+
       const fetchOptions: RequestInit = {
         method,
         headers: {
@@ -205,7 +208,7 @@ export class APIClient {
 
   private buildUrl(path: string, params?: Record<string, any>): string {
     const url = new URL(path, this.config.baseUrl)
-    
+
     if (params) {
       Object.entries(params).forEach(([key, value]) => {
         if (value !== undefined && value !== null) {
@@ -325,7 +328,7 @@ export class APIClient {
   private shouldRetry(error: AxiosError): boolean {
     const retryCount = (error.config as any)?._retryCount || 0
     const maxRetries = this.config.retries || ${this.options.retries}
-    
+
     return (
       retryCount < maxRetries &&
       (!error.response || error.response.status >= 500) &&
@@ -335,11 +338,11 @@ export class APIClient {
 
   private async retryRequest(config: any): Promise<any> {
     config._retryCount = (config._retryCount || 0) + 1
-    
+
     // Exponential backoff
     const delay = Math.pow(2, config._retryCount) * 1000
     await new Promise(resolve => setTimeout(resolve, delay))
-    
+
     return this.client.request(config)
   }`;
     }
@@ -500,7 +503,7 @@ export class APIClient {
         const authTypes = this.generateAuthTypes();
         return `/**
  * API Client Types
- * 
+ *
  * Configuration and utility types for the generated API client
  */
 
@@ -556,7 +559,7 @@ export interface APIError {
     generateConfiguration() {
         return `/**
  * API Client Configuration
- * 
+ *
  * Default configuration and factory functions
  */
 
@@ -580,7 +583,7 @@ export const defaultConfig: Partial<APIClientConfig> = {
     generateIndexFile() {
         return `/**
  * Generated API Client
- * 
+ *
  * Auto-generated from OpenAPI specification
  */
 
@@ -593,20 +596,85 @@ export { createAPIClient, defaultConfig } from './config'`;
     generateFileHeader(title) {
         return `/**
  * ${title}
- * 
+ *
  * Auto-generated from OpenAPI specification
  * Do not edit manually
  */`;
     }
     getMethodName(endpoint) {
-        if (endpoint.operationId) {
-            return this.camelCase(endpoint.operationId);
-        }
-        const pathParts = endpoint.path
-            .split('/')
-            .filter(part => part && !part.startsWith('{'))
-            .map(part => this.capitalize(part));
-        return this.camelCase(`${endpoint.method}_${pathParts.join('_')}`);
+        // Use semantic naming instead of raw operationId
+        return this.generateSemanticMethodName(endpoint);
+    }
+    generateSemanticMethodName(endpoint) {
+        // Extract resource from path
+        const pathSegments = endpoint.path.split('/').filter(s => s && !s.startsWith('{') && !['api', 'v1', 'v2'].includes(s));
+        const urlSegments = endpoint.path.split('/');
+        const hasPathParam = endpoint.path.includes('{');
+        const lastSegment = pathSegments[pathSegments.length - 1]?.replace(/-/g, '_') || 'resource';
+        const prevSegment = pathSegments[pathSegments.length - 2]?.replace(/-/g, '_');
+
+        // Auth endpoints - use action name directly
+        if (AUTH_ACTIONS.includes(lastSegment.toLowerCase())) {
+            return this.camelCase(lastSegment);
+        }
+
+        // Health/status singletons
+        if (HEALTH_ENDPOINTS.includes(lastSegment.toLowerCase())) {
+            return this.camelCase(lastSegment);
+        }
+
+        // User profile singletons
+        if (USER_PROFILE_ENDPOINTS.includes(lastSegment.toLowerCase())) {
+            return this.camelCase(`get_current_user`);
+        }
+
+        // Metadata endpoints - include parent resource to avoid collision
+        if (lastSegment.toLowerCase() === 'metadata' && prevSegment) {
+            return hasPathParam
+                ? this.camelCase(`get_${singularize(prevSegment)}_metadata`)
+                : this.camelCase(`get_${prevSegment}_metadata`);
+        }
+
+        // Collection actions (e.g., /activities/search)
+        if (COLLECTION_ACTIONS.includes(lastSegment.toLowerCase()) && prevSegment) {
+            return this.camelCase(`${lastSegment}_${prevSegment}`);
+        }
+
+        // Determine resource name - for nested paths, include context
+        let resource = lastSegment;
+        if (pathSegments.length > 2 && hasPathParam) {
+            // e.g., /accounts/{id}/stages/allowed → get_account_allowed_stages
+            const parentResource = pathSegments.find((s, i) => {
+                const nextSeg = urlSegments[urlSegments.findIndex(u => u === s) + 1];
+                return nextSeg?.startsWith('{');
+            });
+            if (parentResource && parentResource !== lastSegment) {
+                resource = `${singularize(parentResource)}_${lastSegment}`;
+            }
+        }
+
+        // Generate name based on HTTP method
+        switch (endpoint.method) {
+            case 'get':
+                return hasPathParam
+                    ? this.camelCase(`get_${singularize(resource)}`)
+                    : this.camelCase(`list_${resource}`);
+            case 'post':
+                // Check for custom actions like /accounts/{id}/stage
+                const lastUrl = urlSegments[urlSegments.length - 1];
+                const prevUrl = urlSegments[urlSegments.length - 2];
+                if (!lastUrl.startsWith('{') && prevUrl?.startsWith('{')) {
+                    return this.camelCase(`${lastUrl}_${singularize(prevSegment || resource)}`);
+                }
+                return this.camelCase(`create_${singularize(resource)}`);
+            case 'put':
+            case 'patch':
+                return this.camelCase(`update_${singularize(resource)}`);
+            case 'delete':
+                return this.camelCase(`delete_${singularize(resource)}`);
+            default:
+                return this.camelCase(`${endpoint.method}_${resource}`);
+        }
     }
     generatePathWithParams(endpoint) {
         return endpoint.path.replace(/{([^}]+)}/g, '${$1}');

package/cli/src/codegen/openapi/confidence-scorer.js

@@ -0,0 +1,93 @@
+/**
+ * Confidence Scorer (Stub)
+ *
+ * Scores generated hook names for quality/confidence.
+ * This is a minimal stub that returns high confidence for all names.
+ */
+
+export class ConfidenceScorer {
+  constructor() {
+    this.scoringRules = [];
+  }
+
+  /**
+   * Score a generated hook name
+   * @returns {{ hookName: string, operationId: string, confidence: string, score: number, suggestions: string[] }}
+   */
+  scoreHookName(hookName, operationId, path, method) {
+    // Simple heuristic: shorter names are better
+    const lengthScore = Math.max(0, 100 - hookName.length);
+
+    // Check for common anti-patterns
+    const hasApiV1 = hookName.toLowerCase().includes('apiv1');
+    const hasUnderscore = hookName.includes('_');
+    const isVeryLong = hookName.length > 40;
+
+    let score = lengthScore;
+    if (hasApiV1) score -= 30;
+    if (hasUnderscore) score -= 10;
+    if (isVeryLong) score -= 20;
+
+    // Normalize to 0-100
+    score = Math.max(0, Math.min(100, score));
+
+    // Determine confidence level
+    let confidence;
+    if (score >= 70) confidence = 'high';
+    else if (score >= 40) confidence = 'medium';
+    else confidence = 'low';
+
+    return {
+      hookName,
+      operationId,
+      path,
+      method,
+      confidence,
+      score,
+      suggestions: confidence === 'low' ? [this.suggestBetterName(path, method)] : []
+    };
+  }
+
+  suggestBetterName(path, method) {
+    // Extract resource from path
+    const segments = path.split('/').filter(s => s && !s.startsWith('{') && !['api', 'v1'].includes(s));
+    const resource = segments[segments.length - 1]?.replace(/-/g, '') || 'resource';
+
+    // Capitalize first letter
+    const capitalizedResource = resource.charAt(0).toUpperCase() + resource.slice(1);
+
+    switch (method) {
+      case 'get':
+        return path.includes('{') ? `useGet${capitalizedResource}` : `use${capitalizedResource}`;
+      case 'post':
+        return `useCreate${capitalizedResource}`;
+      case 'put':
+      case 'patch':
+        return `useUpdate${capitalizedResource}`;
+      case 'delete':
+        return `useDelete${capitalizedResource}`;
+      default:
+        return `use${capitalizedResource}`;
+    }
+  }
+
+  generateReport(scoredNames) {
+    const high = scoredNames.filter(s => s.confidence === 'high').length;
+    const medium = scoredNames.filter(s => s.confidence === 'medium').length;
+    const low = scoredNames.filter(s => s.confidence === 'low').length;
+
+    return `
+Hook Name Quality Report
+========================
+Total hooks: ${scoredNames.length}
+High confidence: ${high} (${Math.round(high/scoredNames.length*100)}%)
+Medium confidence: ${medium} (${Math.round(medium/scoredNames.length*100)}%)
+Low confidence: ${low} (${Math.round(low/scoredNames.length*100)}%)
+
+${low > 0 ? 'Low confidence hooks that may need review:\n' +
+  scoredNames.filter(s => s.confidence === 'low')
+    .map(s => `  - ${s.hookName} → suggested: ${s.suggestions[0]}`)
+    .join('\n') : 'All hooks have acceptable names!'}
+`;
+  }
+}

package/cli/src/codegen/openapi/hook-config.js

@@ -0,0 +1,48 @@
+/**
+ * Hook Configuration Manager (Stub)
+ *
+ * Provides name overrides and pattern configuration for hook generation.
+ * This is a minimal stub to unblock the hook generator.
+ */
+
+export class HookConfigManager {
+  constructor(configPath) {
+    this.configPath = configPath;
+    this.overrides = {};
+    this.patterns = {
+      deduplicateSegments: true
+    };
+    this.reviewedNames = [];
+    this.statistics = {};
+  }
+
+  async load() {
+    // No-op for stub - would load from config file
+    return;
+  }
+
+  async save() {
+    // No-op for stub - would save to config file
+    return;
+  }
+
+  getOverride(operationId) {
+    return this.overrides[operationId] || null;
+  }
+
+  getPatterns() {
+    return this.patterns;
+  }
+
+  getReviewedNames() {
+    return this.reviewedNames;
+  }
+
+  updateStatistics(stats) {
+    this.statistics = { ...this.statistics, ...stats };
+  }
+
+  setOverride(operationId, hookName) {
+    this.overrides[operationId] = hookName;
+  }
+}

package/cli/src/codegen/openapi/hook-generator.js

@@ -6,8 +6,10 @@
  *
  * Part of FRO-3: React Hook Generator
  */
-import { HookConfigManager } from './hook-config';
-import { ConfidenceScorer } from './confidence-scorer';
+import { HookConfigManager } from './hook-config.js';
+import { ConfidenceScorer } from './confidence-scorer.js';
+import { singularize, pluralize, isPlural } from './naming-utils.js';
+import { AUTH_ACTIONS, HEALTH_ENDPOINTS, USER_PROFILE_ENDPOINTS, SINGLETON_RESOURCES, COLLECTION_ACTIONS, SPECIAL_ACTIONS } from './naming-constants.js';
 export class ReactHookGenerator {
     options;
     configManager;
@@ -203,13 +205,13 @@ export class ReactHookGenerator {
                 return `    onMutate: async (newData) => {
       // Cancel outgoing refetches
       await queryClient.cancelQueries({ queryKey: queryKeys.all })
-      
+
       // Snapshot previous value
       const previousData = queryClient.getQueryData(queryKeys.all)
-      
+
       // Optimistically update cache
       queryClient.setQueryData(queryKeys.all, (old: any) => [...(old || []), newData])
-      
+
       return { previousData }
     },
     onError: (err, newData, context) => {
@@ -220,14 +222,14 @@ export class ReactHookGenerator {
             case 'patch':
                 return `    onMutate: async (updatedData) => {
       await queryClient.cancelQueries({ queryKey: queryKeys.all })
-      
+
       const previousData = queryClient.getQueryData(queryKeys.all)
-      
+
       // Update specific item in cache
-      queryClient.setQueryData(queryKeys.all, (old: any) => 
+      queryClient.setQueryData(queryKeys.all, (old: any) =>
         old?.map((item: any) => item.id === updatedData.id ? { ...item, ...updatedData } : item)
       )
-      
+
       return { previousData }
     },
     onError: (err, updatedData, context) => {
@@ -236,14 +238,14 @@ export class ReactHookGenerator {
             case 'delete':
                 return `    onMutate: async (id) => {
       await queryClient.cancelQueries({ queryKey: queryKeys.all })
-      
+
       const previousData = queryClient.getQueryData(queryKeys.all)
-      
+
       // Remove item from cache
-      queryClient.setQueryData(queryKeys.all, (old: any) => 
+      queryClient.setQueryData(queryKeys.all, (old: any) =>
         old?.filter((item: any) => item.id !== id)
       )
-      
+
       return { previousData }
     },
     onError: (err, id, context) => {
@@ -275,18 +277,36 @@ export class ReactHookGenerator {
         // Group endpoints by resource/tag
         const groupedEndpoints = this.groupEndpointsByResource(endpoints);
         for (const [resource, resourceEndpoints] of Object.entries(groupedEndpoints)) {
+            // Sanitize resource name to be a valid JS identifier
+            const sanitizedResource = this.sanitizeIdentifier(resource);
+            console.log(`DEBUG: resource="${resource}" -> sanitizedResource="${sanitizedResource}"`);
             keys.push(`  // ${resource} keys`);
-            keys.push(`  ${resource}: () => [...queryKeys.all, '${resource}'] as const,`);
+            keys.push(`  ${sanitizedResource}: () => [...queryKeys.all, '${sanitizedResource}'] as const,`);
+            const usedKeys = new Set([sanitizedResource]); // Track used keys to avoid duplicates
             for (const endpoint of resourceEndpoints) {
                 if (endpoint.method !== 'get')
                     continue;
                 const operationName = this.getOperationName(endpoint);
-                const keyName = this.camelCase(operationName.replace(/^get/, ''));
+                let keyName = this.camelCase(operationName.replace(/^get/, ''));
+                // Skip if keyName matches sanitizedResource (base key already handles this)
+                if (keyName === sanitizedResource) {
+                    continue;
+                }
+                // If keyName already used, add suffix to disambiguate
+                if (usedKeys.has(keyName)) {
+                    const isList = !endpoint.path.includes('{');
+                    keyName = isList ? `${keyName}List` : `${keyName}Detail`;
+                }
+                // Still duplicate after suffix? Skip to avoid compilation error
+                if (usedKeys.has(keyName)) {
+                    continue;
+                }
+                usedKeys.add(keyName);
                 if (this.hasRequiredParams(endpoint)) {
-                    keys.push(`  ${keyName}: (params: any) => [...queryKeys.${resource}(), '${keyName}', params] as const,`);
+                    keys.push(`  ${keyName}: (params: Record<string, unknown>) => [...queryKeys.${sanitizedResource}(), '${keyName}', params] as const,`);
                 }
                 else {
-                    keys.push(`  ${keyName}: () => [...queryKeys.${resource}(), '${keyName}'] as const,`);
+                    keys.push(`  ${keyName}: () => [...queryKeys.${sanitizedResource}(), '${keyName}'] as const,`);
                 }
             }
             keys.push('');
@@ -336,7 +356,7 @@ export class ReactHookGenerator {
     generateFileHeader(title) {
         return `/**
  * ${title}
- * 
+ *
  * Auto-generated React hooks from OpenAPI specification
  * Do not edit manually - regenerate using the hook generator
  */`;
@@ -422,6 +442,8 @@ export class ReactHookGenerator {
             /^(?<action>\w+?)_api_v\d+_(?<path>.+?)_(?<method>get|post|put|patch|delete)$/i,
             // Pattern: action_resource_path_method
             /^(?<action>\w+?)_(?<resource>\w+?)_(?<path>.+?)_(?<method>get|post|put|patch|delete)$/i,
+            // Pattern: simple action_action_method (e.g., ready_ready_get, health_health_get)
+            /^(?<action>\w+?)_\1_(?<method>get|post|put|patch|delete)$/i,
             // Pattern: simple action_resource
             /^(?<action>\w+?)_(?<resource>\w+?)$/i,
         ];
@@ -439,7 +461,12 @@ export class ReactHookGenerator {
         // Check if it's a custom action
         const urlSegments = endpoint.path.split('/');
         const lastSegment = urlSegments[urlSegments.length - 1];
-        const isCustomAction = !lastSegment.startsWith('{') && urlSegments[urlSegments.length - 2]?.startsWith('{');
+        const prevSegment = urlSegments[urlSegments.length - 2];
+        // Custom action: either after a path param (e.g., /accounts/{id}/archive)
+        // or a known action verb on a collection (e.g., /activities/search)
+        const isResourceAction = !lastSegment.startsWith('{') && prevSegment?.startsWith('{');
+        const isCollectionAction = !lastSegment.startsWith('{') && !prevSegment?.startsWith('{') && COLLECTION_ACTIONS.includes(lastSegment);
+        const isCustomAction = isResourceAction || isCollectionAction;
         // Extract or infer the action verb
         const actionVerb = this.extractActionVerb(components.action || operationId, endpoint.method);
         // Extract or infer the resource
@@ -449,7 +476,7 @@ export class ReactHookGenerator {
             'resource';
         return {
             action: actionVerb,
-            resource: resource,
+            resource: isCollectionAction ? prevSegment : resource,
             path: components.path || '',
             method: endpoint.method,
             isCustomAction,
@@ -463,10 +490,10 @@ export class ReactHookGenerator {
     extractActionVerb(actionPart, method) {
         // Common action verbs to recognize
         const actionVerbs = [
-            'login', 'logout', 'register', 'signup', 'signin',
-            'health', 'status', 'check',
+            ...AUTH_ACTIONS,
+            ...HEALTH_ENDPOINTS,
             'list', 'get', 'create', 'update', 'delete',
-            'reassign', 'assign', 'settle', 'reconcile',
+            ...COLLECTION_ACTIONS,
             'approve', 'reject', 'archive', 'restore',
             'sync', 'refresh', 'reset', 'verify', 'validate'
         ];
@@ -501,11 +528,7 @@ export class ReactHookGenerator {
      * Check if this is a special endpoint that should keep its action verb
      */
     isSpecialEndpoint(parsed) {
-        const specialActions = [
-            'login', 'logout', 'register', 'signup', 'signin',
-            'health', 'status', 'check', 'verify', 'validate'
-        ];
-        return specialActions.includes(parsed.action);
+        return SPECIAL_ACTIONS.includes(parsed.action);
     }
     /**
      * Format name for custom action endpoints
@@ -519,17 +542,18 @@ export class ReactHookGenerator {
                 return customActionName;
             }
             // Otherwise combine resource and action
-            return `${this.singularize(resource)}_${customActionName}`;
+            return `${singularize(resource)}_${customActionName}`;
         }
-        return `${action}_${this.singularize(resource)}`;
+        return `${action}_${singularize(resource)}`;
     }
     /**
      * Format name for special endpoints (login, health, etc.)
      */
     formatSpecialEndpointName(parsed) {
         const { action, resource } = parsed;
-        // For endpoints like "login", "health", just return the action
-        if (['login', 'logout', 'health', 'status'].includes(action)) {
+        // For simple singleton endpoints, just return the action
+        const simpleActions = [...AUTH_ACTIONS.filter(a => ['login', 'logout'].includes(a)), ...HEALTH_ENDPOINTS.filter(h => ['health', 'ready', 'status'].includes(h)), ...USER_PROFILE_ENDPOINTS];
+        if (simpleActions.includes(action)) {
             return action;
         }
         // For other special endpoints, combine with resource if meaningful
@@ -544,19 +568,19 @@ export class ReactHookGenerator {
     formatStandardOperationName(parsed, endpoint) {
         const { resource } = parsed;
         // Determine if it's a list or single resource operation
-        const isList = endpoint.method === 'get' && !endpoint.path.includes('{');
+        const isList = endpoint.method === 'get' && !endpoint.path.includes('{') && !this.isSingletonEndpoint(resource, endpoint.path);
         switch (endpoint.method) {
             case 'get':
-                return isList ? this.pluralize(resource) : this.singularize(resource);
+                return isList ? pluralize(resource) : singularize(resource);
             case 'post':
-                return `create_${this.singularize(resource)}`;
+                return `create_${singularize(resource)}`;
             case 'put':
             case 'patch':
-                return `update_${this.singularize(resource)}`;
+                return `update_${singularize(resource)}`;
             case 'delete':
-                return `delete_${this.singularize(resource)}`;
+                return `delete_${singularize(resource)}`;
             default:
-                return this.singularize(resource);
+                return singularize(resource);
         }
     }
     generateCleanName(endpoint) {
@@ -578,7 +602,7 @@ export class ReactHookGenerator {
             const action = lastSegment.replace(/-/g, '_');
             return `${mainResource}_${action}`;
         }
-        // For nested resources (e.g., /categories/{id}/subcategories), 
+        // For nested resources (e.g., /categories/{id}/subcategories),
         // just use the last resource name
         if (pathParts.length > 2 && segments.some(s => s.startsWith('{'))) {
             // This is a nested resource, just use the last part
@@ -591,7 +615,7 @@ export class ReactHookGenerator {
                 const isList = !endpoint.path.includes('{');
                 // Only pluralize if it's a list and not already plural
                 if (isList && !cleanResource.endsWith('s') && !cleanResource.endsWith('ies')) {
-                    return this.pluralize(cleanResource);
+                    return pluralize(cleanResource);
                 }
                 return cleanResource;
             case 'post':
@@ -605,28 +629,22 @@ export class ReactHookGenerator {
                 return `${endpoint.method}_${cleanResource}`;
         }
     }
-    pluralize(word) {
-        // Simple pluralization rules
-        if (word.endsWith('y') && !['ay', 'ey', 'iy', 'oy', 'uy'].includes(word.slice(-2))) {
-            return word.slice(0, -1) + 'ies';
+    isSingletonEndpoint(resource, path) {
+        // Check if resource matches singleton pattern
+        const lowerResource = resource.toLowerCase().replace(/_/g, '');
+        if (SINGLETON_RESOURCES.some(s => lowerResource === s || lowerResource.endsWith(s))) {
+            return true;
         }
-        if (word.endsWith('s') || word.endsWith('x') || word.endsWith('ch') || word.endsWith('sh')) {
-            return word + 'es';
+
+        // Check path patterns for common singletons
+        const pathSegments = path.split('/').filter(s => s && !s.startsWith('{'));
+        const lastSegment = pathSegments[pathSegments.length - 1]?.toLowerCase();
+
+        if (SINGLETON_RESOURCES.includes(lastSegment)) {
+            return true;
         }
-        return word + 's';
-    }
-    singularize(word) {
-        // Simple singularization rules
-        if (word.endsWith('ies')) {
-            return word.slice(0, -3) + 'y';
-        }
-        if (word.endsWith('ses') || word.endsWith('xes') || word.endsWith('ches') || word.endsWith('shes')) {
-            return word.slice(0, -2);
-        }
-        if (word.endsWith('s') && !word.endsWith('ss')) {
-            return word.slice(0, -1);
-        }
-        return word;
+
+        return false;
     }
     hasRequiredParams(endpoint) {
         return endpoint.parameters.some(p => p.required) ||
@@ -663,6 +681,15 @@ export class ReactHookGenerator {
         }
     }
     isListEndpoint(endpoint) {
+        // Extract resource for singleton check
+        const pathSegments = endpoint.path.split('/').filter(s => s && !s.startsWith('{'));
+        const resource = pathSegments[pathSegments.length - 1]?.replace(/-/g, '_') || '';
+
+        // Singleton endpoints are never list endpoints
+        if (this.isSingletonEndpoint(resource, endpoint.path)) {
+            return false;
+        }
+
         return endpoint.path.includes('list') ||
             !endpoint.path.includes('{') ||
             (endpoint.summary?.toLowerCase().includes('list') ?? false) ||
@@ -671,7 +698,9 @@ export class ReactHookGenerator {
     groupEndpointsByResource(endpoints) {
         const groups = {};
         for (const endpoint of endpoints) {
-            const resource = endpoint.tags?.[0] || 'default';
+            const tag = endpoint.tags?.[0] || 'default';
+            // Sanitize tag to be a valid JS identifier (camelCase, no spaces)
+            const resource = this.sanitizeIdentifier(tag);
             if (!groups[resource]) {
                 groups[resource] = [];
             }
@@ -679,8 +708,17 @@ export class ReactHookGenerator {
         }
         return groups;
     }
+    sanitizeIdentifier(str) {
+        // Convert to camelCase and remove invalid characters
+        return str
+            .replace(/[^a-zA-Z0-9\s]/g, '') // Remove special chars except spaces
+            .split(/\s+/) // Split on whitespace
+            .map((word, i) => i === 0 ? word.toLowerCase() : word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+            .join('');
+    }
     getRelatedQueryTags(endpoint) {
-        const resource = endpoint.tags?.[0] || 'default';
+        const tag = endpoint.tags?.[0] || 'default';
+        const resource = this.sanitizeIdentifier(tag);
         return [resource, 'all'];
     }
     camelCase(str) {

package/cli/src/codegen/openapi/naming-constants.js

@@ -0,0 +1,98 @@
+/**
+ * Naming Constants
+ *
+ * Shared constants for magic strings used across hook and client generators.
+ * These constants help identify special endpoints that get unique naming treatment.
+ */
+
+/**
+ * Authentication action endpoints
+ * These endpoints are named directly without CRUD prefixes (e.g., 'login' not 'createLogin')
+ */
+export const AUTH_ACTIONS = [
+  'login',
+  'logout',
+  'register',
+  'signup',
+  'signin',
+  'refresh'
+];
+
+/**
+ * Health/status check endpoints
+ * These are singleton endpoints that return system status
+ */
+export const HEALTH_ENDPOINTS = [
+  'health',
+  'ready',
+  'status',
+  'info',
+  'version'
+];
+
+/**
+ * User profile endpoints
+ * These endpoints reference the current/authenticated user
+ */
+export const USER_PROFILE_ENDPOINTS = [
+  'me',
+  'self',
+  'profile',
+  'current'
+];
+
+/**
+ * Singleton resources
+ * Resources that return a single item, not a collection
+ * Includes all auth, health, and user profile endpoints plus common singleton patterns
+ */
+export const SINGLETON_RESOURCES = [
+  'me',
+  'self',
+  'current',
+  'profile',
+  'health',
+  'ready',
+  'status',
+  'info',
+  'version',
+  'metadata',
+  'config',
+  'settings',
+  'preferences',
+  'summary',
+  'stats',
+  'statistics',
+  'dashboard',
+  'schema',
+  'spec',
+  'openapi'
+];
+
+/**
+ * Collection action verbs
+ * Actions that operate on collections (e.g., /activities/search)
+ */
+export const COLLECTION_ACTIONS = [
+  'search',
+  'export',
+  'import',
+  'bulk',
+  'batch',
+  'count',
+  'stats',
+  'validate'
+];
+
+/**
+ * Special actions - combination of auth, health, and user profile endpoints
+ * These endpoints get special naming treatment and keep their action verb
+ */
+export const SPECIAL_ACTIONS = [
+  ...AUTH_ACTIONS,
+  ...HEALTH_ENDPOINTS,
+  ...USER_PROFILE_ENDPOINTS,
+  'check',
+  'verify',
+  'validate'
+];

package/cli/src/codegen/openapi/naming-utils.js

@@ -0,0 +1,149 @@
+/**
+ * Shared naming utilities for OpenAPI code generation
+ * Handles singular/plural conversions with proper edge case handling
+ */
+
+/**
+ * Map of irregular plural forms
+ */
+export const IRREGULAR_PLURALS = {
+    person: 'people',
+    child: 'children',
+    data: 'data',         // already plural
+    media: 'media',       // already plural
+    metadata: 'metadata', // already plural
+    people: 'people',     // already plural
+    children: 'children', // already plural
+};
+
+/**
+ * Map of irregular singular forms (reverse lookup)
+ */
+const IRREGULAR_SINGULARS = {
+    people: 'person',
+    children: 'child',
+    data: 'data',         // already singular
+    media: 'media',       // already singular
+    metadata: 'metadata', // already singular
+    person: 'person',     // already singular
+    child: 'child',       // already singular
+};
+
+/**
+ * Words that naturally end in 's' but are singular
+ */
+const SINGULAR_EXCEPTIONS = [
+    'status',
+    'class',
+    'address',
+    'access',
+    'success',
+    'process',
+    'bus',
+    'focus',
+    'virus',
+];
+
+/**
+ * Check if a word is already plural
+ * @param {string} word - The word to check
+ * @returns {boolean} - True if the word is plural
+ */
+export function isPlural(word) {
+    // Check irregular plurals first
+    if (IRREGULAR_PLURALS[word.toLowerCase()]) {
+        return IRREGULAR_PLURALS[word.toLowerCase()] === word.toLowerCase();
+    }
+
+    // Check singular exceptions - these end in 's' but are not plural
+    if (SINGULAR_EXCEPTIONS.includes(word.toLowerCase())) {
+        return false;
+    }
+
+    // Check common plural endings
+    if (word.endsWith('ies') || word.endsWith('es') || word.endsWith('s')) {
+        return true;
+    }
+
+    return false;
+}
+
+/**
+ * Convert plural word to singular
+ * @param {string} word - The word to singularize
+ * @returns {string} - The singular form of the word
+ */
+export function singularize(word) {
+    // Handle empty or short words
+    if (!word || word.length <= 1) {
+        return word;
+    }
+
+    // Check irregular singulars first
+    const lowerWord = word.toLowerCase();
+    if (IRREGULAR_SINGULARS[lowerWord]) {
+        return IRREGULAR_SINGULARS[lowerWord];
+    }
+
+    // Already singular (check exceptions)
+    if (SINGULAR_EXCEPTIONS.includes(lowerWord)) {
+        return word;
+    }
+
+    // -ies → -y (activities → activity)
+    if (word.endsWith('ies')) {
+        return word.slice(0, -3) + 'y';
+    }
+
+    // -ses → -s (processes → process, but 'process' is already singular)
+    // -xes → -x (boxes → box)
+    // -ches → -ch (watches → watch)
+    // -shes → -sh (dishes → dish)
+    if (word.endsWith('ses') || word.endsWith('xes') || word.endsWith('ches') || word.endsWith('shes')) {
+        return word.slice(0, -2);
+    }
+
+    // Regular -s ending (cats → cat)
+    // But avoid words ending in -ss (class, success, etc.)
+    if (word.endsWith('s') && !word.endsWith('ss') && word.length > 1) {
+        return word.slice(0, -1);
+    }
+
+    return word;
+}
+
+/**
+ * Convert singular word to plural
+ * @param {string} word - The word to pluralize
+ * @returns {string} - The plural form of the word
+ */
+export function pluralize(word) {
+    // Handle empty or short words
+    if (!word || word.length <= 1) {
+        return word;
+    }
+
+    // Check if already plural
+    if (isPlural(word)) {
+        return word;
+    }
+
+    // Check irregular plurals first
+    const lowerWord = word.toLowerCase();
+    if (IRREGULAR_PLURALS[lowerWord]) {
+        return IRREGULAR_PLURALS[lowerWord];
+    }
+
+    // -y ending (not vowel+y) → -ies (activity → activities)
+    if (word.endsWith('y') && !['ay', 'ey', 'iy', 'oy', 'uy'].includes(word.slice(-2))) {
+        return word.slice(0, -1) + 'ies';
+    }
+
+    // -x, -ch, -sh endings → add 'es' (box → boxes, watch → watches, dish → dishes)
+    if (word.endsWith('x') || word.endsWith('ch') || word.endsWith('sh')) {
+        return word + 'es';
+    }
+
+    // Regular: add 's' (cat → cats, dog → dogs)
+    return word + 's';
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@pattern-stack/frontend-patterns",
   "description": "Production-ready React frontend template with atomic architecture patterns. Build ultra-lean applications by importing shared UI foundation patterns.",
   "private": false,
-  "version": "0.2.0-alpha.0",
+  "version": "0.2.0-alpha.1",
   "keywords": [
     "react",
     "typescript",