ntc-dev-kit 1.0.0__py3-none-any.whl

ntc/templates/react_structure/knowledge/knowledge_design_pattern.md

@@ -0,0 +1,411 @@
+# Design Patterns and Coding Conventions - {project_name}
+
+This document describes the design patterns and coding conventions used in this NTC-generated React + TypeScript + Vite project.
+
+## 🎨 Component Design Patterns
+
+### Functional Component Pattern
+```typescript
+interface ComponentProps {
+  title: string
+  onAction: () => void
+}
+
+const Component: React.FC<ComponentProps> = ({ title, onAction }) => {
+  // Component logic
+  return <div>{title}</div>
+}
+
+export default Component
+```
+
+### Custom Hook Pattern
+```typescript
+const useCustomHook = (param: string) => {
+  const [state, setState] = useState<string>('')
+
+  useEffect(() => {
+    // Effect logic
+  }, [param])
+
+  return state
+}
+```
+
+### Container/Presenter Pattern
+```typescript
+// Container component (handles logic)
+const DataContainer: React.FC = () => {
+  const { data, loading, error } = useData()
+  
+  if (loading) return <LoadingSpinner />
+  if (error) return <ErrorMessage />
+  
+  return <DataPresenter data={data} />
+}
+
+// Presenter component (handles UI)
+const DataPresenter: React.FC<{ data: DataType }> = ({ data }) => {
+  return <div>{data.name}</div>
+}
+```
+
+## 🔧 Service Layer Pattern
+
+### API Service Pattern
+```typescript
+// Centralized API service
+export const apiService = {
+  get: (url: string, config = {}) => apiClient.get(url, config),
+  post: (url: string, data = {}, config = {}) => apiClient.post(url, data, config),
+  // ... other methods
+}
+```
+
+### Auth Service Pattern
+```typescript
+export const authService = {
+  login: async (credentials: LoginCredentials) => {
+    const response = await apiService.post('/auth/login/', credentials)
+    if (response.data.token) {
+      localStorage.setItem('authToken', response.data.token)
+    }
+    return response
+  },
+  logout: () => {
+    localStorage.removeItem('authToken')
+  },
+  // ... other methods
+}
+```
+
+## 📝 TypeScript Patterns
+
+### Interface for Props
+```typescript
+interface ButtonProps {
+  label: string
+  onClick: () => void
+  disabled?: boolean
+  variant?: 'primary' | 'secondary'
+}
+
+const Button: React.FC<ButtonProps> = ({ label, onClick, disabled = false, variant = 'primary' }) => {
+  return <button onClick={onClick} disabled={disabled}>{label}</button>
+}
+```
+
+### Type Guards
+```typescript
+const isString = (value: unknown): value is string => {
+  return typeof value === 'string'
+}
+
+const processValue = (value: unknown) => {
+  if (isString(value)) {
+    return value.toUpperCase()
+  }
+  return 'DEFAULT'
+}
+```
+
+### Generic Types
+```typescript
+interface ApiResponse<T> {
+  data: T
+  status: number
+  message: string
+}
+
+const fetchData = async <T>(url: string): Promise<ApiResponse<T>> => {
+  const response = await apiService.get<ApiResponse<T>>(url)
+  return response.data
+}
+```
+
+## 🎯 State Management Patterns
+
+### Local State Pattern
+```typescript
+const Component: React.FC = () => {
+  const [count, setCount] = useState(0)
+  const [loading, setLoading] = useState(false)
+  
+  const increment = () => setCount(prev => prev + 1)
+  
+  return <div>{count}</div>
+}
+```
+
+### Context Pattern
+```typescript
+interface AppContextType {
+  user: User | null
+  setUser: (user: User | null) => void
+}
+
+const AppContext = createContext<AppContextType | undefined>(undefined)
+
+export const AppProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const [user, setUser] = useState<User | null>(null)
+  
+  return (
+    <AppContext.Provider value={{ user, setUser }}>
+      {children}
+    </AppContext.Provider>
+  )
+}
+
+export const useApp = () => {
+  const context = useContext(AppContext)
+  if (!context) {
+    throw new Error('useApp must be used within AppProvider')
+  }
+  return context
+}
+```
+
+## 🔄 Async Pattern
+
+### Async/Await with Error Handling
+```typescript
+const Component: React.FC = () => {
+  const [data, setData] = useState<Data | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [loading, setLoading] = useState(false)
+
+  const fetchData = async () => {
+    setLoading(true)
+    setError(null)
+    try {
+      const response = await apiService.get('/endpoint')
+      setData(response.data)
+    } catch (err) {
+      setError('Failed to fetch data')
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  useEffect(() => {
+    fetchData()
+  }, [])
+
+  if (loading) return <Loading />
+  if (error) return <Error message={error} />
+  
+  return <div>{data?.name}</div>
+}
+```
+
+## 🎨 Styling Patterns
+
+### CSS-in-JS (if using)
+```typescript
+const styledComponent = styled.div`
+  padding: 1rem;
+  background: ${props => props.theme.background};
+`
+```
+
+### CSS Modules Pattern
+```typescript
+import styles from './Component.module.css'
+
+const Component: React.FC = () => {
+  return <div className={styles.container}>Content</div>
+}
+```
+
+### Tailwind CSS Pattern
+```typescript
+const Component: React.FC = () => {
+  return (
+    <div className="p-4 bg-white rounded-lg shadow">
+      Content
+    </div>
+  )
+}
+```
+
+## 📦 File Organization Patterns
+
+### Feature-Based Structure
+```
+src/
+├── features/
+│   ├── auth/
+│   │   ├── components/
+│   │   ├── services/
+│   │   └── types/
+│   └── dashboard/
+│       ├── components/
+│       ├── services/
+│       └── types/
+├── components/ (shared)
+├── services/ (shared)
+└── utils/ (shared)
+```
+
+### Type-Based Structure
+```
+src/
+├── components/
+├── services/
+├── hooks/
+├── types/
+├── utils/
+└── pages/
+```
+
+## 🔒 Error Handling Patterns
+
+### Error Boundary Pattern
+```typescript
+class ErrorBoundary extends React.Component<{ children: React.ReactNode }, { hasError: boolean }> {
+  constructor(props: { children: React.ReactNode }) {
+    super(props)
+    this.state = { hasError: false }
+  }
+
+  static getDerivedStateFromError() {
+    return { hasError: true }
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return <div>Something went wrong</div>
+    }
+    return this.props.children
+  }
+}
+```
+
+### Try-Catch in Async Operations
+```typescript
+const safeAsyncOperation = async () => {
+  try {
+    const result = await apiService.get('/endpoint')
+    return result
+  } catch (error) {
+    console.error('Operation failed:', error)
+    throw error
+  }
+}
+```
+
+## 🚀 Performance Patterns
+
+### Memo Pattern
+```typescript
+const ExpensiveComponent: React.FC<{ data: DataType }> = React.memo(({ data }) => {
+  return <div>{data.name}</div>
+})
+```
+
+### useCallback Pattern
+```typescript
+const Component: React.FC = () => {
+  const handleClick = useCallback(() => {
+    console.log('Clicked')
+  }, [])
+
+  return <button onClick={handleClick}>Click</button>
+}
+```
+
+### useMemo Pattern
+```typescript
+const Component: React.FC<{ items: Item[] }> = ({ items }) => {
+  const sortedItems = useMemo(() => {
+    return items.sort((a, b) => a.name.localeCompare(b.name))
+  }, [items])
+
+  return <div>{sortedItems.map(item => <div key={item.id}>{item.name}</div>)}</div>
+}
+```
+
+## 🧪 Testing Patterns
+
+### Component Testing Pattern
+```typescript
+describe('Component', () => {
+  it('renders correctly', () => {
+    render(<Component title="Test" />)
+    expect(screen.getByText('Test')).toBeInTheDocument()
+  })
+
+  it('calls callback on click', () => {
+    const handleClick = jest.fn()
+    render(<Button onClick={handleClick} label="Click" />)
+    fireEvent.click(screen.getByText('Click'))
+    expect(handleClick).toHaveBeenCalled()
+  })
+})
+```
+
+### Hook Testing Pattern
+```typescript
+import { renderHook, act } from '@testing-library/react-hooks'
+
+describe('useCustomHook', () => {
+  it('returns initial state', () => {
+    const { result } = renderHook(() => useCustomHook())
+    expect(result.current).toBe('initial')
+  })
+})
+```
+
+## 📐 Naming Conventions
+
+### Components
+- **File**: `PascalCase.tsx` (e.g., `UserProfile.tsx`)
+- **Component**: `PascalCase` (e.g., `UserProfile`)
+- **Props Interface**: `ComponentProps` (e.g., `UserProfileProps`)
+
+### Hooks
+- **File**: `camelCase.ts` (e.g., `useUserProfile.ts`)
+- **Hook**: `camelCase` starting with `use` (e.g., `useUserProfile`)
+
+### Services
+- **File**: `camelCase.ts` (e.g., `apiService.ts`)
+- **Service**: `camelCase` (e.g., `apiService`)
+
+### Types
+- **File**: `PascalCase.types.ts` (e.g., `User.types.ts`)
+- **Interface**: `PascalCase` (e.g., `UserProfile`)
+- **Type**: `PascalCase` (e.g., `ApiResponse`)
+
+### Constants
+- **File**: `camelCase.ts` (e.g., `constants.ts`)
+- **Constant**: `UPPER_SNAKE_CASE` (e.g., `API_BASE_URL`)
+
+## 🎯 Best Practices
+
+### Code Organization
+1. Keep components small and focused
+2. Extract reusable logic into custom hooks
+3. Use TypeScript interfaces for all props
+4. Organize imports (external, internal, types)
+5. Use path aliases (`@/`) for internal imports
+
+### Performance
+1. Use React.memo for expensive components
+2. Implement code splitting with React.lazy
+3. Optimize images and assets
+4. Avoid unnecessary re-renders
+5. Use virtual scrolling for long lists
+
+### Accessibility
+1. Use semantic HTML elements
+2. Provide alt text for images
+3. Ensure keyboard navigation
+4. Use ARIA labels where needed
+5. Test with screen readers
+
+### Security
+1. Sanitize user input
+2. Use HTTPS in production
+3. Validate data on client and server
+4. Never expose sensitive data
+5. Use environment variables for secrets

ntc/templates/react_structure/knowledge/knowledge_structure.md

@@ -0,0 +1,74 @@
+# Project Structure - {project_name}
+
+This document describes the complete project structure and organization for AI assistants to understand how to work with this codebase.
+
+## 📁 Root Directory Structure
+
+```
+{project_name}/
+├── .env.example           # Environment variables example
+├── .gitignore            # Git ignore patterns
+├── .knowledge/           # AI documentation (this directory)
+├── index.html            # HTML entry point
+├── package.json          # Node.js dependencies
+├── tsconfig.json         # TypeScript configuration
+├── tsconfig.app.json     # TypeScript app configuration
+├── tsconfig.node.json    # TypeScript node configuration
+├── vite.config.ts        # Vite build configuration
+├── README.md             # Project documentation
+└── src/                  # Source code
+```
+
+## 🏗️ Source Directory Structure (`src/`)
+
+```
+src/
+├── main.tsx              # Application entry point
+├── App.tsx               # Root component
+├── index.css             # Global styles
+├── components/           # Reusable UI components
+│   └── Header.tsx        # Header component
+├── services/             # API and external services
+│   └── api.ts            # API service with axios
+└── utils/                # Utility functions
+    └── constants.ts      # Constants and configuration
+```
+
+## 🎯 Key Conventions
+
+### File Naming
+- **Components**: `PascalCase` with `.tsx` extension (e.g., `UserProfile.tsx`)
+- **Utilities**: `camelCase` with `.ts` extension (e.g., `formatDate.ts`)
+- **Services**: `camelCase` with `.ts` extension (e.g., `api.ts`)
+- **Types**: `PascalCase` with `.ts` extension (e.g., `UserTypes.ts`)
+
+### Import Patterns
+- **Components**: `import Component from '@/components/Component'`
+- **Services**: `import { apiService } from '@/services/api'`
+- **Utils**: `import { CONSTANT } from '@/utils/constants'`
+- **Types**: `import { UserType } from '@/types'`
+
+### TypeScript Patterns
+- **Props Interface**: Always define interfaces for component props
+- **Generic Types**: Use generics when appropriate for reusable components
+- **Strict Mode**: TypeScript strict mode is enabled
+- **No Any**: Avoid using `any` type, use `unknown` or proper types instead
+
+## 🔄 Development Workflow
+
+1. **Install dependencies**: `npm install`
+2. **Run development server**: `npm run dev`
+3. **Build for production**: `npm run build`
+4. **Preview production build**: `npm run preview`
+5. **Run linter**: `npm run lint`
+
+## 📋 Important Notes for AI
+
+- **Always use TypeScript** with proper type definitions
+- **Follow the component structure** when creating new components
+- **Use the apiService** for all API calls
+- **Handle loading and error states** in async operations
+- **Use environment variables** via `import.meta.env.VITE_*`
+- **Path aliases**: Use `@` for `src/` directory imports
+- **Vite**: This project uses Vite as the build tool (not Create React App)
+- **Port**: Development server runs on http://localhost:5173

ntc/templates/react_structure/main.py

@@ -0,0 +1,217 @@
+import os
+import subprocess
+import sys
+import json
+import shutil
+from ntc.utils.output import print_success, print_error, print_warning, print_info, print_progress, print_package, print_download
+
+def replace_variables(content, variables):
+    """Replace placeholders with actual variables."""
+    for key, value in variables.items():
+        content = content.replace(f"{{{key}}}", value)
+    return content
+
+def get_template_content(template_name, variables):
+    """Load template content and replace variables."""
+    # Remove 'react_structure/' prefix if present since we're already in that directory
+    if template_name.startswith("react_structure/"):
+        template_name = template_name[len("react_structure/"):]
+    
+    template_path = os.path.join(os.path.dirname(__file__), template_name)
+    if not os.path.exists(template_path):
+        return ""
+    with open(template_path, "r", encoding="utf-8") as f:
+        content = f.read()
+    return replace_variables(content, variables)
+
+def create_from_json(base_path, structure, variables):
+    """Recursively create directories and files from JSON."""
+    for name, content in structure.items():
+        name = replace_variables(name, variables)
+        full_path = os.path.join(base_path, name)
+
+        if isinstance(content, dict):
+            if "template" in content:
+                os.makedirs(os.path.dirname(full_path), exist_ok=True)
+                with open(full_path, "w", encoding="utf-8") as f:
+                    f.write(get_template_content(content["template"], variables))
+            else:
+                os.makedirs(full_path, exist_ok=True)
+                create_from_json(full_path, content, variables)
+        else:
+            os.makedirs(os.path.dirname(full_path), exist_ok=True)
+            with open(full_path, "w", encoding="utf-8") as f:
+                f.write(replace_variables(content or "", variables))
+
+def install_npm_dependencies(project_root):
+    """Install npm dependencies for React project."""
+    print_package("Installing npm dependencies...")
+    
+    # Check if npm is available
+    if not shutil.which("npm"):
+        print_error("npm not found. Please install Node.js and npm first.")
+        print_info("Visit https://nodejs.org/ to download Node.js")
+        return False
+    
+    try:
+        # Change to project directory and install dependencies
+        result = subprocess.run(
+            ["npm", "install"],
+            cwd=project_root,
+            check=True,
+            capture_output=True,
+            text=True
+        )
+        print_success("npm dependencies installed successfully!")
+        return True
+    except subprocess.CalledProcessError as e:
+        print_error(f"Failed to install npm dependencies: {e}")
+        print_info("You can manually run 'npm install' in the project directory later.")
+        return False
+
+def init_react_project(base_path, project_name):
+    """Initialize React project structure and setup environment."""
+    structure_file = os.path.join(os.path.dirname(__file__), "structure.json")
+
+    if not os.path.exists(structure_file):
+        print_error(f"Structure file not found: {structure_file}")
+        return
+
+    with open(structure_file, "r", encoding="utf-8") as f:
+        structure = json.load(f)
+
+    project_root = os.path.join(base_path, project_name)
+    os.makedirs(project_root, exist_ok=True)
+
+    variables = {
+        "project_name": project_name,
+    }
+
+    create_from_json(project_root, structure["Project"], variables)
+    print_success(f"React project '{project_name}' initialized at: {project_root}")
+
+    # Ask user for dependency installation
+    print(f"\n{Fore.CYAN}{Style.BRIGHT}📦 NODE.JS DEPENDENCY SETUP{Style.RESET_ALL}")
+    print("─" * 40)
+    print(f"{Fore.YELLOW}{Style.BRIGHT}[1]{Style.RESET_ALL} {Fore.WHITE}Install dependencies now (npm install){Style.RESET_ALL}")
+    print(f"{Fore.YELLOW}{Style.BRIGHT}[2]{Style.RESET_ALL} {Fore.WHITE}Use existing node_modules (if available){Style.RESET_ALL}")
+    print(f"{Fore.YELLOW}{Style.BRIGHT}[3]{Style.RESET_ALL} {Fore.WHITE}Skip dependency installation{Style.RESET_ALL}")
+    
+    while True:
+        deps_choice = input(f"{Fore.WHITE}{Style.BRIGHT}❓ Select dependency option (1-3): {Style.RESET_ALL}").strip()
+        
+        if deps_choice == "1":
+            # Install dependencies now
+            install_npm_dependencies(project_root)
+            break
+            
+        elif deps_choice == "2":
+            # Check for existing node_modules
+            node_modules_path = os.path.join(project_root, "node_modules")
+            if os.path.exists(node_modules_path):
+                print_success("Found existing node_modules directory!")
+                print_info("Using existing dependencies. Run 'npm install' if you need to update them.")
+            else:
+                print_warning("No existing node_modules found in this location.")
+                print_info("You may need to run 'npm install' manually later.")
+            break
+            
+        elif deps_choice == "3":
+            # Skip installation
+            print_info("Skipping dependency installation.")
+            print_info("Remember to run 'npm install' before starting development.")
+            break
+            
+        else:
+            print_error("Invalid choice. Please select 1, 2, or 3.")
+
+    # Show next steps
+    print(f"\n{Fore.GREEN}{Style.BRIGHT}🎉 PROJECT READY!{Style.RESET_ALL}")
+    print("─" * 30)
+    print_info("Next steps:")
+    print(f"  1. cd {project_name}")
+    if deps_choice != "1":
+        print("  2. npm install")
+        print("  3. npm run dev")
+    else:
+        print("  2. npm run dev")
+    print_info("Your React app will be available at http://localhost:5173")
+    print_info("Make sure your backend API is running on http://localhost:8000")
+
+def init_react_project_in_current_dir(project_name):
+    """Initialize React project structure in the current directory."""
+    structure_file = os.path.join(os.path.dirname(__file__), "structure.json")
+
+    if not os.path.exists(structure_file):
+        print_error(f"Structure file not found: {structure_file}")
+        return
+
+    with open(structure_file, "r", encoding="utf-8") as f:
+        structure = json.load(f)
+
+    project_root = os.getcwd()  # Use current directory
+
+    variables = {
+        "project_name": project_name,
+    }
+
+    # Check if current directory is empty or ask for confirmation
+    existing_files = [f for f in os.listdir(project_root) if not f.startswith('.')]
+    if existing_files:
+        print_warning(f"Current directory is not empty. Found {len(existing_files)} files/folders.")
+        print_info("Existing items: " + ", ".join(existing_files[:5]) + ("..." if len(existing_files) > 5 else ""))
+        
+        confirm = input(f"{Fore.WHITE}{Style.BRIGHT}❓ Continue anyway? (y/N): {Style.RESET_ALL}").strip().lower()
+        if confirm != 'y':
+            print_info("Project initialization cancelled.")
+            return
+
+    create_from_json(project_root, structure["Project"], variables)
+    print_success(f"React project '{project_name}' initialized in current directory: {project_root}")
+
+    # Ask user for dependency installation
+    print(f"\n{Fore.CYAN}{Style.BRIGHT}📦 NODE.JS DEPENDENCY SETUP{Style.RESET_ALL}")
+    print("─" * 40)
+    print(f"{Fore.YELLOW}{Style.BRIGHT}[1]{Style.RESET_ALL} {Fore.WHITE}Install dependencies now (npm install){Style.RESET_ALL}")
+    print(f"{Fore.YELLOW}{Style.BRIGHT}[2]{Style.RESET_ALL} {Fore.WHITE}Use existing node_modules (if available){Style.RESET_ALL}")
+    print(f"{Fore.YELLOW}{Style.BRIGHT}[3]{Style.RESET_ALL} {Fore.WHITE}Skip dependency installation{Style.RESET_ALL}")
+    
+    while True:
+        deps_choice = input(f"{Fore.WHITE}{Style.BRIGHT}❓ Select dependency option (1-3): {Style.RESET_ALL}").strip()
+        
+        if deps_choice == "1":
+            # Install dependencies now
+            install_npm_dependencies(project_root)
+            break
+            
+        elif deps_choice == "2":
+            # Check for existing node_modules
+            node_modules_path = os.path.join(project_root, "node_modules")
+            if os.path.exists(node_modules_path):
+                print_success("Found existing node_modules directory!")
+                print_info("Using existing dependencies. Run 'npm install' if you need to update them.")
+            else:
+                print_warning("No existing node_modules found in this location.")
+                print_info("You may need to run 'npm install' manually later.")
+            break
+            
+        elif deps_choice == "3":
+            # Skip installation
+            print_info("Skipping dependency installation.")
+            print_info("Remember to run 'npm install' before starting development.")
+            break
+            
+        else:
+            print_error("Invalid choice. Please select 1, 2, or 3.")
+
+    # Show next steps
+    print(f"\n{Fore.GREEN}{Style.BRIGHT}🎉 PROJECT READY!{Style.RESET_ALL}")
+    print("─" * 30)
+    print_info("Next steps:")
+    if deps_choice != "1":
+        print("  1. npm install")
+        print("  2. npm run dev")
+    else:
+        print("  1. npm run dev")
+    print_info("Your React app will be available at http://localhost:5173")
+    print_info("Make sure your backend API is running on http://localhost:8000")