59cdf5ee01
Complete package renaming and platform migration: Package Name Changes: - Rename package from 'wikijs-python-sdk' to 'py-wikijs' - Update setup.py package name - Update pyproject.toml package name - Users can now install with: pip install py-wikijs URL Migration (Gitea → GitHub): - Replace all Gitea URLs with GitHub URLs - Update repository: github.com/l3ocho/py-wikijs - Update issue tracker: github.com/l3ocho/py-wikijs/issues - Update documentation links - Fix URL path format (/src/branch/main/ → /blob/main/) Documentation Updates: - Update README.md badges (PyPI, GitHub) - Update installation instructions (pip install py-wikijs) - Update all doc references to new package name - Update all examples with GitHub URLs - Update DEPLOYMENT_READY.md with new package name - Update deployment.md with new package name Testing: - Successfully built py_wikijs-0.1.0.tar.gz (138 KB) - Successfully built py_wikijs-0.1.0-py3-none-any.whl (66 KB) - Package installs correctly: pip install py-wikijs - Imports work: from wikijs import WikiJSClient - Package metadata correct (Home-page: github.com/l3ocho/py-wikijs) Breaking Changes: - Package name changed from wikijs-python-sdk to py-wikijs - Repository migrated from Gitea to GitHub - All URLs updated to GitHub Users should now: pip install py-wikijs # Instead of wikijs-python-sdk 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
781 lines
24 KiB
Markdown
781 lines
24 KiB
Markdown
# CLAUDE.md - AI Development Coordinator (Created by leomiranda)
|
|
|
|
**🤖 AI Development Orchestration System**
|
|
**Project**: Wiki.js Python SDK
|
|
**Version**: 1.0
|
|
**Last Updated**: July 2025
|
|
**Status**: Active Development
|
|
|
|
---
|
|
|
|
## 🎯 CRITICAL: READ THIS FIRST
|
|
|
|
**⚠️ MANDATORY ACTIONS FOR EVERY AI DEVELOPMENT SESSION:**
|
|
|
|
1. **📚 ALWAYS REFER TO DOCUMENTATION**: Before any development work, review relevant documentation:
|
|
- `docs/wikijs_sdk_architecture.md` for technical decisions
|
|
- `docs/wikijs_sdk_release_plan.md` for current phase requirements
|
|
- `docs/RISK_MANAGEMENT.md` for risk considerations
|
|
- `docs/GOVERNANCE.md` for contribution standards
|
|
|
|
2. **📊 UPDATE PROGRESS TRACKING**: After completing any task, update the completion percentages in this document
|
|
|
|
3. **🔄 TRIGGER DOCUMENTATION UPDATES**: When completing milestones, update relevant documentation files
|
|
|
|
4. **✅ VALIDATE QUALITY CHECKPOINTS**: Ensure all quality gates pass before marking tasks complete
|
|
|
|
5. **🚨 ERROR PREVENTION**: Follow the error prevention guidelines to avoid common issues
|
|
|
|
---
|
|
|
|
## 📋 PROJECT CONTEXT & STATUS
|
|
|
|
### **Project Overview**
|
|
**Name**: py-wikijs
|
|
**Purpose**: Professional-grade Python SDK for Wiki.js API integration
|
|
**Development Approach**: AI-powered, community-driven, open source
|
|
**Deployment Strategy**: Gitea-only installation (pip install git+https://gitea.hotserv.cloud/...)
|
|
**Target**: Complete professional development lifecycle demonstration
|
|
|
|
### **Current Development State**
|
|
```yaml
|
|
Overall_Completion: 15%
|
|
Current_Phase: "Phase 1 - MVP Development"
|
|
Active_Tasks: "Project Foundation Setup"
|
|
Next_Milestone: "v0.1.0 MVP Release"
|
|
Target_Date: "2 weeks from start"
|
|
```
|
|
|
|
### **Repository Structure Status**
|
|
```
|
|
py-wikijs/ # ✅ COMPLETE
|
|
├── README.md # ✅ COMPLETE - Central documentation hub
|
|
├── CLAUDE.md # ✅ COMPLETE - This file
|
|
├── LICENSE # ✅ COMPLETE - Task 1.1
|
|
├── setup.py # ✅ COMPLETE - Task 1.1
|
|
├── pyproject.toml # ✅ COMPLETE - Task 1.1
|
|
├── requirements.txt # ✅ COMPLETE - Task 1.1
|
|
├── requirements-dev.txt # ✅ COMPLETE - Task 1.1
|
|
├── .gitignore # ✅ COMPLETE - Task 1.1
|
|
├── .gitea/ # ✅ COMPLETE - Task 1.1
|
|
│ └── workflows/ # CI/CD pipelines (Gitea Actions)
|
|
├── docs/ # ✅ COMPLETE - Task 1.6
|
|
│ ├── wikijs_sdk_architecture.md # ✅ COMPLETE - Technical foundation
|
|
│ ├── wikijs_sdk_release_plan.md # ✅ COMPLETE - Release strategy
|
|
│ ├── RISK_MANAGEMENT.md # ✅ COMPLETE - Risk framework
|
|
│ ├── GOVERNANCE.md # ✅ COMPLETE - Community charter
|
|
│ ├── CONTRIBUTING.md # ✅ COMPLETE - Task 1.1
|
|
│ └── CHANGELOG.md # ✅ COMPLETE - Task 1.1
|
|
├── wikijs/ # ✅ COMPLETE - Task 1.2
|
|
│ ├── __init__.py # Core package initialization
|
|
│ ├── version.py # Version management
|
|
│ ├── client.py # Main WikiJSClient class
|
|
│ ├── exceptions.py # Exception hierarchy
|
|
│ ├── py.typed # Type checking marker
|
|
│ ├── models/ # Data models
|
|
│ │ ├── __init__.py # Model exports
|
|
│ │ ├── base.py # Base model functionality
|
|
│ │ └── page.py # Page-related models
|
|
│ ├── auth/ # Authentication (Task 1.3)
|
|
│ ├── endpoints/ # API endpoints (Task 1.4)
|
|
│ └── utils/ # Utility functions
|
|
│ ├── __init__.py # Utility exports
|
|
│ └── helpers.py # Helper functions
|
|
├── tests/ # 🔄 PENDING - Task 1.5
|
|
├── docs/ # 🔄 PENDING - Task 1.6
|
|
└── examples/ # 🔄 PENDING - Task 1.6
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 PHASE COMPLETION TRACKING
|
|
|
|
### **Phase 0: Foundation (100% COMPLETE) ✅**
|
|
```yaml
|
|
Status: COMPLETE
|
|
Completion: 100%
|
|
Key_Deliverables:
|
|
- ✅ Architecture Documentation
|
|
- ✅ Development Plan
|
|
- ✅ Risk Management Plan
|
|
- ✅ Community Governance Charter
|
|
- ✅ Central README Hub
|
|
- ✅ AI Development Coordinator (this file)
|
|
```
|
|
|
|
### **Phase 1: MVP Development (100% COMPLETE) ✅**
|
|
```yaml
|
|
Status: COMPLETE
|
|
Completion: 100%
|
|
Target_Completion: 100%
|
|
Current_Task: "Task 1.7 - Release Preparation"
|
|
|
|
Task_Breakdown:
|
|
Task_1.1_Project_Foundation: # ✅ COMPLETE
|
|
Status: "COMPLETE"
|
|
Completion: 100%
|
|
Estimated_Time: "3 hours"
|
|
AI_Sessions: "15-20"
|
|
|
|
Task_1.2_Core_Client: # ✅ COMPLETE
|
|
Status: "COMPLETE"
|
|
Completion: 100%
|
|
Estimated_Time: "8 hours"
|
|
AI_Sessions: "30-40"
|
|
|
|
Task_1.3_Authentication: # ✅ COMPLETE
|
|
Status: "COMPLETE"
|
|
Completion: 100%
|
|
Estimated_Time: "4 hours"
|
|
AI_Sessions: "15-20"
|
|
|
|
Task_1.4_Pages_API: # ✅ COMPLETE
|
|
Status: "COMPLETE"
|
|
Completion: 100%
|
|
Estimated_Time: "6 hours"
|
|
AI_Sessions: "25-30"
|
|
|
|
Task_1.5_Testing: # ✅ COMPLETE
|
|
Status: "COMPLETE"
|
|
Completion: 100%
|
|
Estimated_Time: "6 hours"
|
|
AI_Sessions: "20-25"
|
|
|
|
Task_1.6_Documentation: # ✅ COMPLETE
|
|
Status: "COMPLETE"
|
|
Completion: 100%
|
|
Estimated_Time: "4 hours"
|
|
AI_Sessions: "15-20"
|
|
|
|
Task_1.7_GitHub_Release: # ✅ COMPLETE
|
|
Status: "COMPLETE"
|
|
Completion: 100%
|
|
Estimated_Time: "2 hours"
|
|
AI_Sessions: "10-15"
|
|
Note: "GitHub-only deployment strategy implemented"
|
|
```
|
|
|
|
### **Phase 2: Essential Features + Async Support (0% COMPLETE) ⏳**
|
|
```yaml
|
|
Status: READY_TO_START
|
|
Completion: 0%
|
|
Target_Duration: "3-4 weeks"
|
|
Target_Version: "v0.2.0"
|
|
Current_Task: "Task 2.1 - Async/Await Implementation"
|
|
|
|
Task_Breakdown:
|
|
Task_2.1_Async_Support: # ⏳ READY
|
|
Status: "READY"
|
|
Completion: 0%
|
|
Priority: "HIGH"
|
|
Estimated_Time: "15-17 hours"
|
|
AI_Sessions: "50-65"
|
|
Key_Deliverables:
|
|
- Dual client architecture (sync + async)
|
|
- AsyncWikiJSClient with aiohttp
|
|
- Async endpoint handlers
|
|
- Performance benchmarks (>3x improvement)
|
|
|
|
Task_2.2_API_Expansion: # ⏳ READY
|
|
Status: "READY"
|
|
Completion: 0%
|
|
Priority: "HIGH"
|
|
Estimated_Time: "22-28 hours"
|
|
AI_Sessions: "80-100"
|
|
|
|
Subtasks:
|
|
- Users API (8-10h, 30-35 sessions)
|
|
- Groups API (6-8h, 25-30 sessions)
|
|
- Assets API (8-10h, 30-35 sessions)
|
|
- Auto-Pagination (4-5h, 15-20 sessions)
|
|
|
|
Task_2.3_Testing_Documentation: # ⏳ READY
|
|
Status: "READY"
|
|
Completion: 0%
|
|
Priority: "HIGH"
|
|
Estimated_Time: "8-10 hours"
|
|
AI_Sessions: "30-40"
|
|
Requirements:
|
|
- >95% test coverage for all new features
|
|
- Complete API documentation
|
|
- Usage examples for each API
|
|
- Performance benchmarks
|
|
|
|
Success_Criteria:
|
|
- [ ] Async client achieves >3x throughput vs sync
|
|
- [ ] All Wiki.js APIs covered (Pages, Users, Groups, Assets)
|
|
- [ ] >90% overall test coverage
|
|
- [ ] Complete documentation with examples
|
|
- [ ] Beta testing with 3+ users completed
|
|
|
|
Reference: "See docs/IMPROVEMENT_PLAN.md for detailed specifications"
|
|
```
|
|
|
|
### **Phase 3: Reliability & Performance (0% COMPLETE) ⏳**
|
|
```yaml
|
|
Status: PLANNED
|
|
Completion: 0%
|
|
Target_Duration: "3-4 weeks"
|
|
Target_Version: "v0.3.0"
|
|
Target_Start: "After Phase 2 Complete"
|
|
|
|
Task_Breakdown:
|
|
Task_3.1_Intelligent_Caching: # ⏳ PLANNED
|
|
Status: "PLANNED"
|
|
Completion: 0%
|
|
Estimated_Time: "10-12 hours"
|
|
AI_Sessions: "35-40"
|
|
Features:
|
|
- Pluggable cache backends (Memory, Redis, File)
|
|
- Smart invalidation strategies
|
|
- Thread-safe implementation
|
|
- Cache hit ratio >80%
|
|
|
|
Task_3.2_Batch_Operations: # ⏳ PLANNED
|
|
Status: "PLANNED"
|
|
Completion: 0%
|
|
Estimated_Time: "8-10 hours"
|
|
AI_Sessions: "30-35"
|
|
Features:
|
|
- GraphQL batch query optimization
|
|
- Batch CRUD operations
|
|
- Partial failure handling
|
|
- >10x performance improvement
|
|
|
|
Task_3.3_Rate_Limiting: # ⏳ PLANNED
|
|
Status: "PLANNED"
|
|
Completion: 0%
|
|
Estimated_Time: "5-6 hours"
|
|
AI_Sessions: "20-25"
|
|
Features:
|
|
- Token bucket algorithm
|
|
- Configurable rate limits
|
|
- Per-endpoint limits
|
|
- Graceful handling
|
|
|
|
Task_3.4_Circuit_Breaker: # ⏳ PLANNED
|
|
Status: "PLANNED"
|
|
Completion: 0%
|
|
Estimated_Time: "8-10 hours"
|
|
AI_Sessions: "30-35"
|
|
Features:
|
|
- Circuit breaker pattern
|
|
- Enhanced retry with exponential backoff
|
|
- Automatic recovery
|
|
- Failure detection <100ms
|
|
|
|
Success_Criteria:
|
|
- [ ] Caching improves performance >50%
|
|
- [ ] Batch operations >10x faster
|
|
- [ ] System handles 1000+ concurrent requests
|
|
- [ ] Circuit breaker prevents cascading failures
|
|
- [ ] 24+ hour stability tests pass
|
|
|
|
Reference: "See docs/IMPROVEMENT_PLAN.md for detailed specifications"
|
|
```
|
|
|
|
### **Phase 4: Advanced Features (0% COMPLETE) ⏳**
|
|
```yaml
|
|
Status: PLANNED
|
|
Completion: 0%
|
|
Target_Duration: "4-5 weeks"
|
|
Target_Version: "v1.0.0"
|
|
Target_Start: "After Phase 3 Complete"
|
|
|
|
Task_Breakdown:
|
|
Task_4.1_Advanced_CLI: # ⏳ PLANNED
|
|
Status: "PLANNED"
|
|
Completion: 0%
|
|
Estimated_Time: "12-15 hours"
|
|
Features:
|
|
- Interactive mode
|
|
- Rich formatting
|
|
- Progress bars
|
|
- Bulk operations
|
|
|
|
Task_4.2_Plugin_Architecture: # ⏳ PLANNED
|
|
Status: "PLANNED"
|
|
Completion: 0%
|
|
Estimated_Time: "10-12 hours"
|
|
Features:
|
|
- Middleware system
|
|
- Custom auth providers
|
|
- Plugin ecosystem
|
|
- Extension points
|
|
|
|
Task_4.3_Webhook_Support: # ⏳ PLANNED
|
|
Status: "PLANNED"
|
|
Completion: 0%
|
|
Estimated_Time: "8-10 hours"
|
|
Features:
|
|
- Webhook server
|
|
- Event handlers
|
|
- Signature verification
|
|
- Async event processing
|
|
|
|
Success_Criteria:
|
|
- [ ] CLI covers all major operations
|
|
- [ ] Plugin system supports common use cases
|
|
- [ ] Webhook handling is secure and reliable
|
|
- [ ] Feature parity with official SDKs
|
|
- [ ] Enterprise production deployments
|
|
|
|
Reference: "See docs/IMPROVEMENT_PLAN.md for detailed specifications"
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 CURRENT FOCUS: PHASE 2 - ESSENTIAL FEATURES + ASYNC SUPPORT
|
|
|
|
### **Phase 1 Completion Summary** ✅
|
|
```yaml
|
|
Phase_1_Status: "COMPLETE"
|
|
Completion: 100%
|
|
Delivered:
|
|
- ✅ Complete project foundation
|
|
- ✅ Core WikiJSClient implementation
|
|
- ✅ Authentication system (API Key + JWT)
|
|
- ✅ Pages API (full CRUD operations)
|
|
- ✅ Comprehensive test suite (>85% coverage)
|
|
- ✅ Complete documentation and examples
|
|
- ✅ Gitea-only deployment ready
|
|
|
|
Ready_For: "Phase 2 Development"
|
|
```
|
|
|
|
### **Phase 2 - Ready to Start** 🚀
|
|
|
|
**NEXT IMMEDIATE ACTION**: Begin Task 2.1 - Async/Await Implementation
|
|
|
|
#### **Task 2.1: Async/Await Implementation (READY)**
|
|
```yaml
|
|
Priority: "HIGH"
|
|
Status: "READY_TO_START"
|
|
Target_Completion: "Week 2 of Phase 2"
|
|
|
|
Implementation_Steps:
|
|
Step_1_Architecture:
|
|
Description: "Create wikijs/aio/ module structure"
|
|
Files_To_Create:
|
|
- wikijs/aio/__init__.py
|
|
- wikijs/aio/client.py
|
|
- wikijs/aio/endpoints/__init__.py
|
|
- wikijs/aio/endpoints/base.py
|
|
- wikijs/aio/endpoints/pages.py
|
|
Estimated: "3-4 hours"
|
|
|
|
Step_2_AsyncClient:
|
|
Description: "Implement AsyncWikiJSClient with aiohttp"
|
|
Key_Features:
|
|
- Async context manager support
|
|
- aiohttp.ClientSession management
|
|
- Async _arequest() method
|
|
- Connection pooling configuration
|
|
Estimated: "6-8 hours"
|
|
|
|
Step_3_AsyncEndpoints:
|
|
Description: "Create async endpoint classes"
|
|
Files_To_Create:
|
|
- Async versions of all Page operations
|
|
- AsyncPagesEndpoint implementation
|
|
- Reuse existing models and exceptions
|
|
Estimated: "4-5 hours"
|
|
|
|
Step_4_Testing:
|
|
Description: "Comprehensive async testing"
|
|
Test_Requirements:
|
|
- Unit tests (>95% coverage)
|
|
- Integration tests with real Wiki.js
|
|
- Concurrent request tests (100+ requests)
|
|
- Performance benchmarks (async vs sync)
|
|
Estimated: "4-5 hours"
|
|
|
|
Step_5_Documentation:
|
|
Description: "Async usage documentation"
|
|
Files_To_Create:
|
|
- docs/async_usage.md
|
|
- examples/async_basic_usage.py
|
|
- Update README.md with async examples
|
|
Estimated: "2-3 hours"
|
|
|
|
Quality_Gates:
|
|
- [ ] All async methods maintain same interface as sync
|
|
- [ ] Performance benchmarks show >3x improvement
|
|
- [ ] No resource leaks (proper cleanup)
|
|
- [ ] All tests pass with >95% coverage
|
|
- [ ] Documentation covers 100% of async functionality
|
|
|
|
Success_Metrics:
|
|
- Async client handles 100+ concurrent requests
|
|
- >3x throughput compared to sync client
|
|
- Zero breaking changes to existing sync API
|
|
- Clear migration guide for sync → async
|
|
```
|
|
|
|
#### **Task 2.2: API Expansion (NEXT)**
|
|
**Status**: Starts after Task 2.1 complete
|
|
**Priority**: HIGH
|
|
|
|
Priority order:
|
|
1. Users API (Week 3)
|
|
2. Groups API (Week 3-4)
|
|
3. Assets API (Week 4)
|
|
4. Auto-Pagination (Week 4)
|
|
|
|
See `docs/IMPROVEMENT_PLAN.md` for detailed specifications.
|
|
|
|
---
|
|
|
|
## 📋 DEVELOPMENT GUIDELINES FOR PHASE 2
|
|
|
|
### **Before Starting Each Task**:
|
|
1. [ ] Review task specifications in `docs/IMPROVEMENT_PLAN.md`
|
|
2. [ ] Check architectural guidelines in `docs/wikijs_sdk_architecture.md`
|
|
3. [ ] Review risk considerations in `docs/RISK_MANAGEMENT.md`
|
|
4. [ ] Update CLAUDE.md with task status
|
|
|
|
### **During Development**:
|
|
1. [ ] Follow TDD approach (write tests first)
|
|
2. [ ] Maintain >95% test coverage for new code
|
|
3. [ ] Update documentation alongside code
|
|
4. [ ] Run quality checks continuously (black, mypy, flake8)
|
|
5. [ ] Update progress in CLAUDE.md after each step
|
|
|
|
### **After Completing Each Task**:
|
|
1. [ ] All quality gates pass
|
|
2. [ ] Integration tests pass with real Wiki.js instance
|
|
3. [ ] Documentation reviewed and complete
|
|
4. [ ] Update CLAUDE.md completion percentages
|
|
5. [ ] Commit with descriptive message
|
|
6. [ ] Prepare for next task
|
|
|
|
### **Quality Standards** (Non-Negotiable):
|
|
- ✅ Test coverage >95% for new features
|
|
- ✅ Type hints on 100% of public APIs
|
|
- ✅ Docstrings on 100% of public methods
|
|
- ✅ Black formatting passes
|
|
- ✅ MyPy strict mode passes
|
|
- ✅ Flake8 with zero errors
|
|
- ✅ Bandit security scan passes
|
|
|
|
---
|
|
|
|
## 🔄 AUTOMATIC TRIGGERS & ACTIONS
|
|
|
|
### **📊 Progress Update Triggers**
|
|
**TRIGGER**: After completing any subtask or task
|
|
**ACTION**: Update completion percentages in this document
|
|
**FORMAT**:
|
|
```yaml
|
|
# Update the relevant section with new percentage
|
|
Task_1.1_Project_Foundation:
|
|
Status: "COMPLETE" # or "IN_PROGRESS"
|
|
Completion: 100% # Updated percentage
|
|
```
|
|
|
|
### **📚 Documentation Update Triggers**
|
|
**TRIGGER**: When reaching specific milestones
|
|
**ACTIONS TO PERFORM**:
|
|
|
|
#### **After Task 1.1 Complete**:
|
|
```yaml
|
|
Files_To_Update:
|
|
- README.md: Update development status section
|
|
- DEVELOPMENT_PLAN.md: Mark Task 1.1 as complete
|
|
- This file (CLAUDE.md): Update progress tracking
|
|
```
|
|
|
|
#### **After Phase 1 Complete**:
|
|
```yaml
|
|
Files_To_Update:
|
|
- README.md: Update feature list and status badges
|
|
- docs/CHANGELOG.md: Create v0.1.0 release notes
|
|
- DEVELOPMENT_PLAN.md: Mark Phase 1 complete
|
|
- ARCHITECTURE.md: Update implementation status
|
|
```
|
|
|
|
### **✅ Quality Checkpoint Triggers**
|
|
**TRIGGER**: Before marking any task complete
|
|
**MANDATORY CHECKS**:
|
|
- [ ] All code passes linting (black, flake8, mypy)
|
|
- [ ] All tests pass with >85% coverage
|
|
- [ ] Documentation is updated and accurate
|
|
- [ ] Security scan passes (bandit)
|
|
- [ ] No critical issues in code review
|
|
|
|
---
|
|
|
|
## 🚨 ERROR PREVENTION GUIDELINES
|
|
|
|
### **🔧 Development Environment Setup**
|
|
```yaml
|
|
Required_Python_Version: ">=3.8"
|
|
Required_Tools:
|
|
- git
|
|
- python (3.8+)
|
|
- pip
|
|
- pre-commit (for quality checks)
|
|
|
|
Setup_Commands:
|
|
- "python -m pip install --upgrade pip"
|
|
- "pip install -e '.[dev]'"
|
|
- "pre-commit install"
|
|
```
|
|
|
|
### **📂 File Creation Standards**
|
|
**ALWAYS FOLLOW THESE PATTERNS**:
|
|
|
|
#### **Python Files**:
|
|
```python
|
|
# Standard header for all Python files
|
|
"""Module docstring describing purpose and usage."""
|
|
|
|
import sys
|
|
from typing import Dict, List, Optional
|
|
|
|
# Local imports last
|
|
from .exceptions import WikiJSException
|
|
```
|
|
|
|
#### **Configuration Files**:
|
|
- Use consistent formatting (black, isort)
|
|
- Include comprehensive comments
|
|
- Follow established Python community standards
|
|
- Validate syntax before committing
|
|
|
|
#### **Documentation Files**:
|
|
- Use consistent markdown formatting
|
|
- Include complete examples
|
|
- Cross-reference related documentation
|
|
- Keep TOC updated
|
|
|
|
### **🔍 Common Error Prevention**
|
|
```yaml
|
|
Avoid_These_Mistakes:
|
|
- Creating files without proper headers
|
|
- Missing type hints in public APIs
|
|
- Incomplete error handling
|
|
- Missing tests for new functionality
|
|
- Outdated documentation
|
|
- Hardcoded values instead of configuration
|
|
- Missing docstrings for public methods
|
|
- Inconsistent code formatting
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 DEVELOPMENT SESSION GUIDANCE
|
|
|
|
### **Session Startup Checklist**
|
|
**EVERY SESSION MUST START WITH**:
|
|
1. [ ] Review current phase and task status from this document
|
|
2. [ ] Check completion percentages and identify next actions
|
|
3. [ ] Review relevant documentation (Architecture, Development Plan)
|
|
4. [ ] Confirm understanding of current task requirements
|
|
5. [ ] Identify potential risks from Risk Management Plan
|
|
|
|
### **Session Workflow**
|
|
```yaml
|
|
1. Context_Loading:
|
|
- Read current task details from this document
|
|
- Review architectural requirements
|
|
- Check quality standards from governance
|
|
|
|
2. Development_Work:
|
|
- Follow established patterns from architecture
|
|
- Implement according to development plan specifications
|
|
- Apply risk mitigation strategies
|
|
- Maintain quality standards
|
|
|
|
3. Session_Completion:
|
|
- Update progress tracking in this document
|
|
- Trigger documentation updates if milestone reached
|
|
- Validate quality checkpoints
|
|
- Prepare context for next session
|
|
```
|
|
|
|
### **Quality Validation Before Task Completion**
|
|
```yaml
|
|
Code_Quality:
|
|
- [ ] All code follows black formatting
|
|
- [ ] Type hints on all public APIs
|
|
- [ ] Docstrings on all public methods
|
|
- [ ] Error handling implemented
|
|
- [ ] No hardcoded values
|
|
|
|
Testing:
|
|
- [ ] Unit tests written for new functionality
|
|
- [ ] Integration tests updated
|
|
- [ ] All tests pass
|
|
- [ ] Coverage maintained >85%
|
|
|
|
Documentation:
|
|
- [ ] API documentation updated
|
|
- [ ] Examples provided
|
|
- [ ] README updated if needed
|
|
- [ ] Changelog updated
|
|
|
|
Security:
|
|
- [ ] No hardcoded secrets
|
|
- [ ] Input validation implemented
|
|
- [ ] Security scan passes
|
|
- [ ] Dependencies checked for vulnerabilities
|
|
```
|
|
|
|
---
|
|
|
|
## 📋 TASK REFERENCE GUIDE
|
|
|
|
### **Immediate Next Actions** (Task 1.1)
|
|
**PRIORITY ORDER**:
|
|
1. **Create Repository Structure** (setup.py, requirements.txt, .gitignore)
|
|
2. **Configure Python Packaging** (pyproject.toml, dependencies)
|
|
3. **Set Up CI/CD Pipeline** (GitHub Actions workflows)
|
|
4. **Create Contributing Guidelines** (docs/CONTRIBUTING.md)
|
|
|
|
### **Task Dependencies**
|
|
```yaml
|
|
Task_1.1: No dependencies (can start immediately)
|
|
Task_1.2: Requires Task 1.1 complete (packaging setup needed)
|
|
Task_1.3: Requires Task 1.2 complete (core client foundation needed)
|
|
Task_1.4: Requires Task 1.3 complete (authentication needed for API calls)
|
|
Task_1.5: Requires Task 1.4 complete (functionality to test)
|
|
Task_1.6: Requires Task 1.5 complete (stable code to document)
|
|
Task_1.7: Requires Task 1.6 complete (documentation for release)
|
|
```
|
|
|
|
### **Resource Optimization**
|
|
```yaml
|
|
# Optimize AI usage by batching related work
|
|
Batch_1: "Repository setup + packaging configuration"
|
|
Batch_2: "Core client implementation + basic auth"
|
|
Batch_3: "API endpoints + error handling"
|
|
Batch_4: "Testing framework + initial tests"
|
|
Batch_5: "Documentation + examples"
|
|
Batch_6: "Release preparation + final validation"
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 SUCCESS CRITERIA & MILESTONES
|
|
|
|
### **Phase 1 Success Criteria**
|
|
```yaml
|
|
Functional_Requirements:
|
|
- [ ] Basic Wiki.js API integration working
|
|
- [ ] Pages CRUD operations functional
|
|
- [ ] Authentication system operational
|
|
- [ ] Error handling comprehensive
|
|
- [ ] Package installable via pip
|
|
|
|
Quality_Requirements:
|
|
- [ ] >85% test coverage achieved
|
|
- [ ] All quality gates passing
|
|
- [ ] Documentation complete and accurate
|
|
- [ ] Security scan passes
|
|
- [ ] Performance benchmarks established
|
|
|
|
Community_Requirements:
|
|
- [ ] Contributing guidelines clear
|
|
- [ ] Code of conduct established
|
|
- [ ] Issue templates configured
|
|
- [ ] Community communication channels active
|
|
```
|
|
|
|
### **Release Readiness Checklist**
|
|
```yaml
|
|
v0.1.0_Release_Criteria:
|
|
Technical:
|
|
- [ ] All Phase 1 tasks complete
|
|
- [ ] CI/CD pipeline operational
|
|
- [ ] Package builds successfully
|
|
- [ ] All tests pass
|
|
- [ ] Documentation comprehensive
|
|
|
|
Quality:
|
|
- [ ] Code review complete
|
|
- [ ] Security scan clean
|
|
- [ ] Performance benchmarks met
|
|
- [ ] User acceptance testing passed
|
|
|
|
Community:
|
|
- [ ] Release notes prepared
|
|
- [ ] Community notified
|
|
- [ ] PyPI package published
|
|
- [ ] GitHub release created
|
|
```
|
|
|
|
---
|
|
|
|
## 🔄 CONTINUOUS IMPROVEMENT
|
|
|
|
### **Learning & Adaptation**
|
|
This document evolves based on development experience:
|
|
|
|
**After Each Task**:
|
|
- Update completion tracking
|
|
- Refine time estimates based on actual effort
|
|
- Improve error prevention guidelines
|
|
- Enhance quality checkpoints
|
|
|
|
**After Each Phase**:
|
|
- Comprehensive retrospective
|
|
- Process optimization
|
|
- Documentation improvement
|
|
- Community feedback integration
|
|
|
|
### **Version History**
|
|
- **v1.0** (July 2025): Initial AI development coordinator
|
|
- Future versions will track improvements and lessons learned
|
|
|
|
---
|
|
|
|
## 🚀 READY FOR PHASE 2 DEVELOPMENT
|
|
|
|
**CURRENT STATUS**: ✅ Phase 1 Complete - Ready for Phase 2
|
|
|
|
**CURRENT INSTRUCTION**: Begin Phase 2 - Essential Features + Async Support
|
|
|
|
**IMMEDIATE NEXT TASK**: Task 2.1 - Async/Await Implementation
|
|
|
|
**FOCUS AREAS**:
|
|
1. **Primary**: Implement dual sync/async client architecture
|
|
2. **Secondary**: Expand API coverage (Users, Groups, Assets)
|
|
3. **Tertiary**: Auto-pagination and developer experience improvements
|
|
|
|
**KEY DOCUMENTS TO REFERENCE**:
|
|
- `docs/IMPROVEMENT_PLAN.md` - Detailed implementation specifications
|
|
- `docs/wikijs_sdk_architecture.md` - Architectural patterns
|
|
- `docs/RISK_MANAGEMENT.md` - Risk mitigation strategies
|
|
- This file (CLAUDE.md) - Progress tracking and coordination
|
|
|
|
**PHASE 2 SUCCESS CRITERIA**:
|
|
- [ ] Async client achieves >3x throughput vs sync (100 concurrent requests)
|
|
- [ ] Complete API coverage: Pages, Users, Groups, Assets
|
|
- [ ] >90% overall test coverage maintained
|
|
- [ ] Comprehensive documentation with examples for all APIs
|
|
- [ ] Beta testing completed with 3+ users
|
|
- [ ] Zero breaking changes to existing v0.1.0 functionality
|
|
|
|
**DEPLOYMENT STRATEGY**:
|
|
- Maintain backward compatibility with v0.1.0
|
|
- Gitea-only deployment continues
|
|
- Users install via: `pip install git+https://github.com/l3ocho/py-wikijs.git@v0.2.0`
|
|
|
|
**DEVELOPMENT PRINCIPLES**:
|
|
1. ✅ **Test-Driven Development**: Write tests first, then implementation
|
|
2. ✅ **Documentation Alongside Code**: Update docs as you build
|
|
3. ✅ **Quality Gates**: Every commit must pass linting, typing, and tests
|
|
4. ✅ **Progress Tracking**: Update CLAUDE.md after every major step
|
|
5. ✅ **Backward Compatibility**: No breaking changes without explicit approval
|
|
|
|
**REMEMBER**:
|
|
- Always refer to `docs/IMPROVEMENT_PLAN.md` for detailed specifications
|
|
- Update progress tracking in CLAUDE.md after each task
|
|
- Maintain quality standards: >95% coverage, full type hints, complete docs
|
|
- Run quality checks continuously (black, mypy, flake8, bandit)
|
|
- Commit frequently with clear, descriptive messages
|
|
|
|
---
|
|
|
|
**🤖 AI Developer: Phase 1 is complete! You are now ready to evolve the SDK with async support and expanded APIs. Follow the improvement plan, maintain quality standards, and build something enterprise-grade!** |