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

ntc/templates/flutter/CLAUDE.md

@@ -0,0 +1,190 @@
+# AI Agent Instructions for NTC-Generated Flutter Projects
+
+This document provides specific instructions for AI agents (Claude, GPT, etc.) working with NTC-generated Flutter projects.
+
+## 📖 Knowledge Base Reading Order
+
+When first approaching this codebase, AI agents should read the knowledge files in this order:
+
+1. **CLAUDE.md** (this file) - AI agent specific instructions
+2. **.knowledge/knowledge_structure.md** - Project structure and organization
+3. **.knowledge/knowledge_description.md** - Architecture overview and technical stack
+4. **.knowledge/knowledge_design_pattern.md** - Design patterns and coding conventions
+
+## 🤖 AI Agent Guidelines
+
+### Before Making Changes
+
+1. **Read the Knowledge Base**: Always read the knowledge files before making any changes to understand the project structure and conventions.
+
+2. **Understand the NTC Structure**: This project follows the NTC (Nexent Toolkit Console) structure with Flutter, Riverpod, and modern Flutter patterns.
+
+3. **Check Existing Implementations**: Before adding new features, check if similar implementations already exist in `lib/core/`, `lib/features/`, or `lib/services/`.
+
+### Code Modification Rules
+
+1. **Use Dart Type Safety**: All code must use Dart with strong type safety. Avoid `dynamic` types whenever possible.
+
+2. **Follow Widget Patterns**:
+   - Use functional widgets with Riverpod
+   - Keep widgets small and focused
+   - Use const constructors where possible
+   - Separate UI from business logic
+
+3. **State Management**:
+   - Use Riverpod for state management
+   - Use StateNotifier for stateful logic
+   - Keep state as close to where it's used as possible
+   - Use ProviderScope at the root
+
+4. **API Integration**:
+   - Use the `ApiService` from `lib/services/api_service.dart` for all API calls
+   - Use the `DioClient` from `lib/core/network/dio_client.dart` for HTTP operations
+   - Handle loading and error states properly
+   - Use async/await for asynchronous operations
+
+5. **Environment Variables**:
+   - Use `String.fromEnvironment()` for environment variables
+   - All configuration should use environment variables, never hardcode values
+   - Define environment variables in `--dart-define` during build
+
+6. **Follow Naming Conventions**:
+   - Widgets: `PascalCase` (e.g., `UserProfile`)
+   - Files: `snake_case.dart` (e.g., `user_profile.dart`)
+   - Variables: `camelCase` (e.g., `userName`)
+   - Constants: `UPPER_SNAKE_CASE`
+   - Private members: `_camelCase`
+
+### Flutter Best Practices
+
+1. **Widget Structure**:
+   - Prefer const constructors
+   - Use ConsumerWidget for widgets that need providers
+   - Use ConsumerStatefulWidget for complex state
+   - Extract widgets into separate files
+
+2. **Performance**:
+   - Use const widgets where possible
+   - Avoid rebuilding unnecessarily
+   - Use `const` for static values
+   - Use `ListView.builder` for long lists
+
+3. **Accessibility**:
+   - Use semantic labels
+   - Ensure proper contrast
+   - Support screen readers
+   - Use proper touch targets
+
+### External Service Integration
+
+1. **API Communication**:
+   - Use the configured Dio instance in `DioClient`
+   - Handle authentication with JWT tokens via interceptors
+   - Implement proper error handling and user feedback
+   - Use loading states for async operations
+
+2. **State Management**:
+   - Use Riverpod providers for state
+   - Use StateNotifier for complex state logic
+   - Keep state local when possible
+   - Use family modifiers for parameterized providers
+
+### Development Workflow
+
+1. **Running the Project**:
+   - Install dependencies: `flutter pub get`
+   - Run development server: `flutter run`
+   - Build for production: `flutter build apk` or `flutter build ios`
+   - Run tests: `flutter test`
+
+2. **Adding New Features**:
+   - Place in `lib/features/` for feature-based organization
+   - Follow the feature pattern: data, domain, presentation layers
+   - Include proper Riverpod providers
+   - Add necessary API services
+
+3. **Adding API Services**:
+   - Add endpoint methods to `lib/services/api_service.dart`
+   - Use the existing `DioClient` with interceptors
+   - Follow the existing service patterns
+   - Include proper Dart types
+
+### Testing
+
+1. **Test Structure**: Each widget and service should have corresponding test files in the `test/` directory.
+
+2. **Run Tests**: Use `flutter test` to run the test suite.
+
+### Security Considerations
+
+1. **Never Commit Secrets**: Environment variables should never be committed to the repository.
+
+2. **Use HTTPS in Production**: All API calls should use HTTPS in production.
+
+3. **Validate Inputs**: Always validate user inputs both on client and server side.
+
+4. **Secure Storage**: Use `flutter_secure_storage` for sensitive data.
+
+### When to Ask for Clarification
+
+1. If you're unsure about the NTC structure or conventions
+2. If you need to add a new external service integration
+3. If you're modifying the build configuration
+4. If you're changing the Riverpod state management
+5. If you're modifying the authentication flow
+
+## 🎯 Quick Reference
+
+### Import Patterns
+```dart
+// API service
+import '../services/api_service.dart';
+
+// Core config
+import '../core/config/app_config.dart';
+import '../core/config/environment.dart';
+
+// Riverpod
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+// Flutter
+import 'package:flutter/material.dart';
+```
+
+### Common Patterns
+```dart
+// API call with loading and error states
+final isLoading = ref.watch(isLoadingProvider);
+final error = ref.watch(errorProvider);
+
+final fetchData = ref.read(fetchDataProvider.notifier).fetchData();
+
+// Environment variable
+final apiUrl = String.fromEnvironment('API_BASE_URL', defaultValue: 'http://localhost:8000');
+
+// Riverpod provider
+final myProvider = Provider<int>((ref) {
+  return 42;
+});
+
+// ConsumerWidget
+class MyWidget extends ConsumerWidget {
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final value = ref.watch(myProvider);
+    return Text('$value');
+  }
+}
+```
+
+## 📝 Additional Resources
+
+- Flutter Documentation: https://flutter.dev/docs
+- Riverpod Documentation: https://riverpod.dev/
+- Dart Documentation: https://dart.dev/guides
+- Dio Documentation: https://pub.dev/packages/dio
+
+---
+
+**Last Updated**: 2026-05-09
+**Template Version**: Flutter 3.19+ + Riverpod 2.4+

ntc/templates/flutter/analysis_options.yaml

@@ -0,0 +1,9 @@
+include: package:flutter_lints/flutter.yaml
+
+linter:
+  rules:
+    prefer_const_constructors: true
+    prefer_const_literals_to_create_immutables: true
+    prefer_const_declarations: true
+    avoid_print: false
+    prefer_single_quotes: true

ntc/templates/flutter/main.py

@@ -0,0 +1,187 @@
+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
+
+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 'flutter/' prefix if present since we're already in that directory
+    if template_name.startswith("flutter/"):
+        template_name = template_name[len("flutter/"):]
+    
+    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_flutter_dependencies(project_root):
+    """Install Flutter dependencies for the project."""
+    print_info("Installing Flutter dependencies...")
+    
+    # Check if flutter is available
+    if not shutil.which("flutter"):
+        print_error("Flutter not found. Please install Flutter SDK first.")
+        print_info("Visit https://flutter.dev/docs/get-started/install to download Flutter")
+        return False
+    
+    try:
+        # Change to project directory and install dependencies
+        result = subprocess.run(
+            ["flutter", "pub", "get"],
+            cwd=project_root,
+            check=True,
+            capture_output=True,
+            text=True
+        )
+        print_success("Flutter dependencies installed successfully!")
+        return True
+    except subprocess.CalledProcessError as e:
+        print_error(f"Failed to install Flutter dependencies: {e}")
+        print_info("You can manually run 'flutter pub get' in the project directory later.")
+        return False
+
+def convert_to_camel_case(name):
+    """Convert snake_case to CamelCase."""
+    return ''.join(word.capitalize() for word in name.split('_'))
+
+def init_flutter_project(base_path, project_name):
+    """Initialize Flutter 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,
+        "project_camel": convert_to_camel_case(project_name),
+    }
+
+    create_from_json(project_root, structure["{project_name}"], variables)
+    print_success(f"Flutter project '{project_name}' initialized at: {project_root}")
+
+    # Ask user for dependency installation
+    print(f"\n📦 FLUTTER DEPENDENCY SETUP")
+    print("─" * 40)
+    print("[1] Install dependencies now (flutter pub get)")
+    print("[2] Skip dependency installation")
+    
+    deps_choice = input("❓ Select dependency option (1-2): ").strip()
+    
+    # Clear screen after selection
+    os.system('cls' if os.name == 'nt' else 'clear')
+    
+    if deps_choice == "1":
+        install_flutter_dependencies(project_root)
+    else:
+        print_info("Skipping dependency installation.")
+        print_info("Remember to run 'flutter pub get' before starting development.")
+
+    # Show next steps
+    print(f"\n🎉 PROJECT READY!")
+    print("─" * 30)
+    print_info("Next steps:")
+    print("  1. cd " + project_name)
+    if deps_choice != "1":
+        print("  2. flutter pub get")
+        print("  3. flutter run")
+    else:
+        print("  2. flutter run")
+    print_info("Your Flutter app will be available on your connected device/emulator")
+    print_info("Make sure your backend API is running on http://localhost:8000")
+
+def init_flutter_project_in_current_dir(project_name):
+    """Initialize Flutter 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,
+        "project_camel": convert_to_camel_case(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("❓ Continue anyway? (y/N): ").strip().lower()
+        if confirm != 'y':
+            print_info("Project initialization cancelled.")
+            return
+
+    create_from_json(project_root, structure["{project_name}"], variables)
+    print_success(f"Flutter project '{project_name}' initialized in current directory: {project_root}")
+
+    # Ask user for dependency installation
+    print(f"\n📦 FLUTTER DEPENDENCY SETUP")
+    print("─" * 40)
+    print("[1] Install dependencies now (flutter pub get)")
+    print("[2] Skip dependency installation")
+    
+    deps_choice = input("❓ Select dependency option (1-2): ").strip()
+    
+    # Clear screen after selection
+    os.system('cls' if os.name == 'nt' else 'clear')
+    
+    if deps_choice == "1":
+        install_flutter_dependencies(project_root)
+    else:
+        print_info("Skipping dependency installation.")
+        print_info("Remember to run 'flutter pub get' before starting development.")
+
+    # Show next steps
+    print(f"\n🎉 PROJECT READY!")
+    print("─" * 30)
+    print_info("Next steps:")
+    if deps_choice != "1":
+        print("  1. flutter pub get")
+        print("  2. flutter run")
+    else:
+        print("  1. flutter run")
+    print_info("Your Flutter app will be available on your connected device/emulator")
+    print_info("Make sure your backend API is running on http://localhost:8000")

ntc/templates/flutter/pubspec.yaml

@@ -0,0 +1,65 @@
+name: {project_name}
+description: A modern Flutter application with state management and API integration
+publish_to: 'none'
+
+version: 1.0.0+1
+
+environment:
+  sdk: ^3.9.0
+
+dependencies:
+  flutter:
+    sdk: flutter
+  flutter_localizations:
+    sdk: flutter
+
+  # State Management
+  flutter_riverpod: ^2.4.9
+
+  # HTTP Client & Networking
+  dio: ^5.4.0
+  connectivity_plus: ^5.0.2
+
+  # Secure Storage
+  flutter_secure_storage: ^9.0.0
+
+  # Local Storage & Caching
+  hive: ^2.2.3
+  hive_flutter: ^1.1.0
+  shared_preferences: ^2.5.4
+
+  # JSON & Models
+  freezed_annotation: ^2.4.1
+  json_annotation: ^4.8.1
+
+  # Utils
+  cached_network_image: ^3.3.0
+  intl: ^0.20.2
+
+  # Fonts
+  google_fonts: ^6.1.0
+
+  # Device Info
+  device_info_plus: ^10.1.0
+
+  # Path Provider
+  path_provider: ^2.1.2
+
+  # URL Launcher
+  url_launcher: ^6.3.0
+
+  # Cupertino Icons
+  cupertino_icons: ^1.0.8
+
+dev_dependencies:
+  flutter_test:
+    sdk: flutter
+
+  flutter_lints: ^5.0.0
+
+flutter:
+  uses-material-design: true
+  generate: true
+
+  assets:
+    - assets/

ntc/templates/flutter/structure.json

@@ -0,0 +1,51 @@
+{
+  "{project_name}": {
+    "pubspec.yaml": { "template": "flutter/pubspec.yaml" },
+    ".gitignore": { "template": "flutter/.gitignore" },
+    "analysis_options.yaml": { "template": "flutter/analysis_options.yaml" },
+    "README.md": "# {project_name}\n\nA modern Flutter application with state management and API integration, initialized by `ntc init`.\n\n## Tech Stack\n\n- Flutter 3.19+\n- Dart 3.9+\n- Riverpod 2.4+ (State Management)\n- Dio 5.4+ (HTTP Client)\n- Flutter Secure Storage\n- Hive (Local Storage)\n\n## Getting Started\n\n```bash\nflutter pub get\nflutter run\n```\n\n## Available Commands\n\n- `flutter pub get` - Install dependencies\n- `flutter run` - Run the app in development mode\n- `flutter build apk` - Build Android APK\n- `flutter build ios` - Build iOS app\n- `flutter test` - Run tests\n- `flutter analyze` - Analyze code\n",
+    "CLAUDE.md": { "template": "flutter/CLAUDE.md" },
+    ".knowledge": {
+      "knowledge_structure.md": { "template": "flutter/.knowledge/knowledge_structure.md" },
+      "knowledge_description.md": { "template": "flutter/.knowledge/knowledge_description.md" },
+      "knowledge_design_pattern.md": { "template": "flutter/.knowledge/knowledge_design_pattern.md" }
+    },
+    "lib": {
+      "main.dart": { "template": "flutter/lib/main.dart" },
+      "core": {
+        "config": {
+          "app_config.dart": { "template": "flutter/lib/core/config/app_config.dart" },
+          "environment.dart": { "template": "flutter/lib/core/config/environment.dart" }
+        },
+        "constants": {
+          "app_constants.dart": { "template": "flutter/lib/core/constants/app_constants.dart" }
+        },
+        "network": {
+          "dio_client.dart": { "template": "flutter/lib/core/network/dio_client.dart" }
+        }
+      },
+      "services": {
+        "api_service.dart": { "template": "flutter/lib/services/api_service.dart" }
+      },
+      "shared": {
+        "theme": {
+          "app_theme.dart": { "template": "flutter/lib/shared/theme/app_theme.dart" },
+          "theme_provider.dart": { "template": "flutter/lib/shared/theme/theme_provider.dart" }
+        },
+        "localization": {
+          "locale_provider.dart": { "template": "flutter/lib/shared/localization/locale_provider.dart" }
+        }
+      },
+      "features": {
+        "home": {
+          "presentation": {
+            "home_screen.dart": { "template": "flutter/lib/features/home/presentation/home_screen.dart" }
+          }
+        }
+      },
+      "l10n": {
+        "app_localizations.dart": { "template": "flutter/lib/l10n/app_localizations.dart" }
+      }
+    }
+  }
+}

ntc/templates/nextjs/.env.example

@@ -0,0 +1,10 @@
+# API Configuration
+NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
+
+# Site Configuration
+NEXT_PUBLIC_SITE_NAME={project_name}
+NEXT_PUBLIC_SITE_URL=http://localhost:3000
+
+# SEO Configuration
+NEXT_PUBLIC_SITE_DESCRIPTION=A modern website built with Next.js
+NEXT_PUBLIC_SITE_KEYWORDS=nextjs,react,typescript

ntc/templates/nextjs/.gitignore

@@ -0,0 +1,36 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+.env
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts