generated from coulomb/repo-seed
docs: add cleanup report and standalone reusability plan
Added comprehensive documentation for post-migration cleanup and future standalone development: - CLEANUP_REPORT.md: Identifies 6 cleanup opportunities after migration completion (empty dirs, legacy wrappers, relicts, documentation updates) - STANDALONE_PLAN.md: 5-phase plan to achieve 95% standalone maturity (move rendering engine to capability, create examples, update docs, testing, PyPI distribution) - CLAUDE.md: Updated with migration completion status These documents provide clear roadmap for making testdrive-jsui truly pip-installable and reusable independently from MarkiTect. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
287
CLEANUP_REPORT.md
Normal file
287
CLEANUP_REPORT.md
Normal file
@@ -0,0 +1,287 @@
|
||||
# TestDrive-JSUI Cleanup Report
|
||||
|
||||
**Date**: 2025-12-16
|
||||
**Status**: Post-Migration Cleanup Review
|
||||
**Scope**: Identify remaining artifacts and legacy code after successful migration
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
The migration Phase 1 has been completed successfully with all original JavaScript files migrated to the capability. However, several cleanup opportunities remain:
|
||||
|
||||
- ✅ **Good**: No template references to old paths
|
||||
- ⚠️ **Action Needed**: Empty legacy directories
|
||||
- ⚠️ **Action Needed**: Legacy compatibility wrappers still in use
|
||||
- ⚠️ **Action Needed**: Relicts directory with old HTML prototypes
|
||||
- ⚠️ **Action Needed**: Empty placeholder directory structure
|
||||
|
||||
---
|
||||
|
||||
## Cleanup Items
|
||||
|
||||
### Priority 1: Remove Empty Legacy Directories
|
||||
|
||||
**Location**: `/markitect/static/js/`
|
||||
|
||||
**Current State**:
|
||||
```
|
||||
markitect/static/js/
|
||||
├── controls/ (empty - 0 files)
|
||||
└── utils/ (empty - 0 files)
|
||||
```
|
||||
|
||||
**Action**: Remove entire `/markitect/static/js/` directory
|
||||
- Original files already removed
|
||||
- No templates reference this location (verified)
|
||||
- Only empty subdirectories remain
|
||||
|
||||
**Command**:
|
||||
```bash
|
||||
rm -rf /home/worsch/markitect_project/markitect/static/js/
|
||||
```
|
||||
|
||||
**Risk**: ✅ None - directory is empty and unreferenced
|
||||
|
||||
---
|
||||
|
||||
### Priority 2: Remove Empty testdrive-jsui Directory
|
||||
|
||||
**Location**: `/testdrive-jsui/` (project root)
|
||||
|
||||
**Current State**:
|
||||
```
|
||||
testdrive-jsui/
|
||||
└── static/
|
||||
└── js/ (empty - 0 files)
|
||||
```
|
||||
|
||||
**Size**: 20K (essentially empty)
|
||||
|
||||
**Action**: Remove entire `/testdrive-jsui/` directory
|
||||
- Appears to be orphaned/test directory structure
|
||||
- No content (0 JS files)
|
||||
- Confusion risk with actual capability at `/capabilities/testdrive-jsui/`
|
||||
|
||||
**Command**:
|
||||
```bash
|
||||
rm -rf /home/worsch/markitect_project/testdrive-jsui/
|
||||
```
|
||||
|
||||
**Risk**: ✅ Low - verify not referenced in git submodules or docs
|
||||
|
||||
---
|
||||
|
||||
### Priority 3: Consolidate or Remove Legacy Wrapper
|
||||
|
||||
**Location**: `/capabilities/testdrive-jsui/js/components/document-controls-legacy.js`
|
||||
|
||||
**Current State**:
|
||||
- 679 bytes wrapper file
|
||||
- Re-exports `DocumentControls` as `DocumentControlsLegacy`
|
||||
- Created for backward compatibility during migration
|
||||
|
||||
**Referenced By**:
|
||||
1. `js/tests/test-documentcontrols-extraction.js`
|
||||
2. `js/tests/test-full-integration.js`
|
||||
3. `js/tests/test-real-user-functionality.js`
|
||||
4. `tests/test_component_listing.py`
|
||||
5. `scripts/list_components.py`
|
||||
6. Migration and implementation docs
|
||||
|
||||
**Options**:
|
||||
|
||||
**Option A: Remove (Recommended)**
|
||||
- Update 3 test files to use `DocumentControls` directly
|
||||
- Update Python scripts to not list legacy file
|
||||
- Remove wrapper file
|
||||
- **Benefit**: Cleaner codebase, no legacy references
|
||||
- **Effort**: Low (3 test files + 2 scripts)
|
||||
|
||||
**Option B: Keep**
|
||||
- Document as official compatibility layer
|
||||
- Useful if external code depends on legacy name
|
||||
- **Benefit**: No changes needed
|
||||
- **Downside**: Permanent legacy baggage
|
||||
|
||||
**Recommendation**: Option A - Remove after updating tests
|
||||
|
||||
---
|
||||
|
||||
### Priority 4: Clean Up Relicts Directory
|
||||
|
||||
**Location**: `/capabilities/testdrive-jsui/relicts/`
|
||||
|
||||
**Current State**:
|
||||
```
|
||||
relicts/
|
||||
├── AllControlsRudimentary.html (147KB)
|
||||
├── ControlFooter.html (8KB)
|
||||
├── DebugControlContent.html (161KB)
|
||||
└── StatusPsychadelic.html (92KB)
|
||||
Total: 408KB
|
||||
```
|
||||
|
||||
**Purpose**: HTML prototypes from control system development
|
||||
|
||||
**Referenced By**:
|
||||
- `IMPLEMENTATION_NOTES.md` - References `relicts/DebugControlContent.html`
|
||||
|
||||
**Options**:
|
||||
|
||||
**Option A: Archive**
|
||||
- Move to `docs/historical/` or `docs/prototypes/`
|
||||
- Update IMPLEMENTATION_NOTES.md reference
|
||||
- Keep for historical reference
|
||||
- **Benefit**: Preserve development history
|
||||
|
||||
**Option B: Remove**
|
||||
- Delete all prototype files
|
||||
- Remove references from docs
|
||||
- **Benefit**: Smaller repository
|
||||
|
||||
**Recommendation**: Option A - Move to `docs/prototypes/` with README explaining historical context
|
||||
|
||||
---
|
||||
|
||||
### Priority 5: Update MIGRATION_STATUS.md
|
||||
|
||||
**Location**: `/capabilities/testdrive-jsui/MIGRATION_STATUS.md`
|
||||
|
||||
**Current State**:
|
||||
- 400 lines documenting Phase 1 completion
|
||||
- Detailed comparison of old vs new files
|
||||
- Next steps for Phase 2, 3, 4
|
||||
|
||||
**Action**:
|
||||
Since migration is complete:
|
||||
1. Add final section documenting Phase 2-4 completion
|
||||
2. Mark document as "Historical Record"
|
||||
3. Move to `docs/migration/` directory
|
||||
4. Update README.md to remove migration warnings
|
||||
5. Archive as part of project history
|
||||
|
||||
**Recommendation**: Keep as historical record in docs
|
||||
|
||||
---
|
||||
|
||||
### Priority 6: Update Documentation Post-Migration
|
||||
|
||||
**Files to Update**:
|
||||
|
||||
1. **README.md** (Line ~30)
|
||||
- Remove "⚠️ Active Migration in Progress" section
|
||||
- Update status from "Phase 1 Complete" to "Migration Complete"
|
||||
- Simplify intro to focus on usage, not migration
|
||||
|
||||
2. **CLAUDE.md** (Lines 12-30)
|
||||
- Remove migration status section
|
||||
- Simplify to development guide only
|
||||
- Remove references to dual-track testing
|
||||
|
||||
3. **IMPLEMENTATION_NOTES.md**
|
||||
- Update reference to relicts if moved
|
||||
- Add note about legacy wrapper status
|
||||
|
||||
---
|
||||
|
||||
## Files Not Needing Cleanup
|
||||
|
||||
### Intentional Dual Systems
|
||||
|
||||
**Components vs Controls**:
|
||||
- `js/components/` - Original components (dom-renderer, debug-panel, document-controls)
|
||||
- `js/controls/` - New control system (control-base, edit-control, etc.)
|
||||
|
||||
**Analysis**: Both systems serve different purposes:
|
||||
- Components: Core rendering and UI primitives
|
||||
- Controls: Interactive control panels with ControlBase architecture
|
||||
|
||||
**Decision**: ✅ Keep both - not duplicates, complementary systems
|
||||
|
||||
---
|
||||
|
||||
## Cleanup Commands Summary
|
||||
|
||||
```bash
|
||||
# Priority 1: Remove empty legacy JS directory
|
||||
rm -rf /home/worsch/markitect_project/markitect/static/js/
|
||||
|
||||
# Priority 2: Remove empty orphaned directory
|
||||
rm -rf /home/worsch/markitect_project/testdrive-jsui/
|
||||
|
||||
# Priority 3: Handle legacy wrapper (after updating tests)
|
||||
# First update tests to use DocumentControls directly
|
||||
# Then:
|
||||
rm /home/worsch/markitect_project/capabilities/testdrive-jsui/js/components/document-controls-legacy.js
|
||||
|
||||
# Priority 4: Archive relicts
|
||||
mkdir -p /home/worsch/markitect_project/capabilities/testdrive-jsui/docs/prototypes
|
||||
mv /home/worsch/markitect_project/capabilities/testdrive-jsui/relicts/* \
|
||||
/home/worsch/markitect_project/capabilities/testdrive-jsui/docs/prototypes/
|
||||
rmdir /home/worsch/markitect_project/capabilities/testdrive-jsui/relicts/
|
||||
|
||||
# Priority 5: Archive migration documentation
|
||||
mkdir -p /home/worsch/markitect_project/capabilities/testdrive-jsui/docs/migration
|
||||
mv /home/worsch/markitect_project/capabilities/testdrive-jsui/MIGRATION_STATUS.md \
|
||||
/home/worsch/markitect_project/capabilities/testdrive-jsui/docs/migration/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Risks and Validation
|
||||
|
||||
### Before Cleanup
|
||||
|
||||
1. **Verify git status**: Ensure no uncommitted changes
|
||||
2. **Run all tests**: `make testdrive-jsui-test-all`
|
||||
3. **Check main app**: Verify MarkiTect still works
|
||||
|
||||
### After Each Cleanup Step
|
||||
|
||||
1. **Run tests**: `make testdrive-jsui-test-all`
|
||||
2. **Check for broken imports**: `make testdrive-jsui-lint-js`
|
||||
3. **Verify templates**: Check that HTML rendering still works
|
||||
|
||||
### Rollback Plan
|
||||
|
||||
All cleanups involve file deletion or moving. Git provides easy rollback:
|
||||
```bash
|
||||
git checkout HEAD -- <file-or-directory>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Estimated Impact
|
||||
|
||||
| Item | Files Affected | Lines Changed | Test Impact | Risk Level |
|
||||
|------|---------------|---------------|-------------|------------|
|
||||
| Empty dirs | 0 | 0 | None | ✅ None |
|
||||
| Orphan dir | 0 | 0 | None | ✅ None |
|
||||
| Legacy wrapper | 5 files | ~20 lines | 3 tests | 🟡 Low |
|
||||
| Relicts | 0 code | 1 doc ref | None | ✅ None |
|
||||
| Docs | 3 files | ~50 lines | None | ✅ None |
|
||||
|
||||
**Total Effort**: 2-3 hours
|
||||
**Overall Risk**: 🟢 Low
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
**Immediate (Do Today)**:
|
||||
1. ✅ Remove empty directories (Priority 1, 2)
|
||||
2. ✅ Archive relicts (Priority 4)
|
||||
|
||||
**Short-term (This Week)**:
|
||||
3. ⚠️ Update tests and remove legacy wrapper (Priority 3)
|
||||
4. ⚠️ Update documentation (Priority 6)
|
||||
5. ⚠️ Archive migration docs (Priority 5)
|
||||
|
||||
**Optional (Future)**:
|
||||
- Consider consolidating component/control architecture
|
||||
- Add architectural documentation about dual system design
|
||||
|
||||
---
|
||||
|
||||
**End of Cleanup Report**
|
||||
867
STANDALONE_PLAN.md
Normal file
867
STANDALONE_PLAN.md
Normal file
@@ -0,0 +1,867 @@
|
||||
# TestDrive-JSUI Standalone Reusability Plan
|
||||
|
||||
**Date**: 2025-12-16
|
||||
**Goal**: Make testdrive-jsui truly reusable independently from MarkiTect
|
||||
**Current Maturity**: 60% → **Target**: 95%
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
TestDrive-JSUI has excellent JavaScript architecture and testing infrastructure, but its Python rendering engine lives in the MarkiTect codebase, preventing true standalone reuse. This plan outlines how to make it a fully independent, pip-installable package that works in any Python project.
|
||||
|
||||
**Key Problem**: Cannot `pip install testdrive-jsui` and use it in non-MarkiTect projects.
|
||||
|
||||
**Solution**: Move rendering engine and dependencies into the capability package.
|
||||
|
||||
---
|
||||
|
||||
## Current State Analysis
|
||||
|
||||
### What Works ✅
|
||||
- JavaScript components are self-contained
|
||||
- Testing infrastructure is independent
|
||||
- Asset structure is clean
|
||||
- Documentation is comprehensive
|
||||
|
||||
### What Doesn't ❌
|
||||
- Rendering engine in `/markitect/plugins/testdrive_jsui.py`
|
||||
- Depends on `markitect.plugins.rendering.RenderingConfig`
|
||||
- Python package (`src/testdrive_jsui/`) is empty shells
|
||||
- Not pip-installable for standalone use
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Move Core Rendering Engine
|
||||
|
||||
### Objective
|
||||
Move the rendering engine from MarkiTect plugins into the capability package.
|
||||
|
||||
### Current Location
|
||||
```
|
||||
/markitect/plugins/testdrive_jsui.py (242 lines)
|
||||
/markitect/plugins/rendering.py (316 lines - base classes)
|
||||
/markitect/plugins/base.py (Plugin metadata)
|
||||
```
|
||||
|
||||
### Target Location
|
||||
```
|
||||
src/testdrive_jsui/
|
||||
├── __init__.py # Export main classes
|
||||
├── engine.py # TestDriveJSUIEngine (moved)
|
||||
├── rendering.py # RenderingEnginePlugin, RenderingConfig (extracted)
|
||||
├── models.py # PluginMetadata, etc.
|
||||
└── testing/ # ✅ Already independent
|
||||
```
|
||||
|
||||
### Implementation Steps
|
||||
|
||||
#### Step 1.1: Extract Base Classes
|
||||
|
||||
**Create**: `src/testdrive_jsui/models.py`
|
||||
|
||||
```python
|
||||
"""
|
||||
Data models and metadata for TestDrive-JSUI.
|
||||
"""
|
||||
from dataclasses import dataclass
|
||||
from enum import Enum
|
||||
from typing import Optional
|
||||
|
||||
class PluginType(Enum):
|
||||
"""Plugin type enumeration."""
|
||||
RENDERING = "rendering"
|
||||
TESTING = "testing"
|
||||
|
||||
@dataclass
|
||||
class PluginMetadata:
|
||||
"""Plugin metadata information."""
|
||||
name: str
|
||||
version: str
|
||||
description: str
|
||||
author: str
|
||||
plugin_type: PluginType
|
||||
```
|
||||
|
||||
**Why**: Remove dependency on MarkiTect's plugin system.
|
||||
|
||||
---
|
||||
|
||||
#### Step 1.2: Create Standalone Rendering Base
|
||||
|
||||
**Create**: `src/testdrive_jsui/rendering.py`
|
||||
|
||||
Extract and adapt from `/markitect/plugins/rendering.py`:
|
||||
- `RenderingEnginePlugin` (abstract base)
|
||||
- `RenderingConfig` (configuration)
|
||||
- Remove MarkiTect-specific integrations
|
||||
- Make it generic for any Python project
|
||||
|
||||
```python
|
||||
"""
|
||||
Rendering engine plugin architecture for TestDrive-JSUI.
|
||||
|
||||
This module provides a standalone rendering system that can be used
|
||||
independently of MarkiTect or integrated into any Python project.
|
||||
"""
|
||||
from abc import ABC, abstractmethod
|
||||
from typing import Dict, List, Optional, Any
|
||||
from pathlib import Path
|
||||
import json
|
||||
|
||||
class RenderingEnginePlugin(ABC):
|
||||
"""Base class for rendering engine plugins."""
|
||||
|
||||
@abstractmethod
|
||||
def get_supported_modes(self) -> List[str]:
|
||||
"""Return supported rendering modes (e.g., ['edit', 'view'])."""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def get_required_assets(self) -> Dict[str, List[str]]:
|
||||
"""Return required assets by type (js, css, images)."""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def render_document(self, content: str, mode: str,
|
||||
config: 'RenderingConfig') -> str:
|
||||
"""Render markdown content to HTML."""
|
||||
pass
|
||||
|
||||
# ... rest of interface
|
||||
|
||||
class RenderingConfig:
|
||||
"""Configuration for rendering engine."""
|
||||
|
||||
def __init__(self,
|
||||
asset_base_url: str = "_static",
|
||||
development_mode: bool = False,
|
||||
plugin_source_dirs: Optional[Dict[str, Path]] = None,
|
||||
output_directory: Optional[Path] = None):
|
||||
"""Initialize configuration for standalone use."""
|
||||
self.asset_base_url = asset_base_url
|
||||
self.development_mode = development_mode
|
||||
self.plugin_source_dirs = plugin_source_dirs or {}
|
||||
self.output_directory = output_directory
|
||||
|
||||
# ... rest of implementation
|
||||
```
|
||||
|
||||
**Why**: Standalone projects shouldn't import `markitect.plugins.rendering`.
|
||||
|
||||
---
|
||||
|
||||
#### Step 1.3: Move Engine Implementation
|
||||
|
||||
**Create**: `src/testdrive_jsui/engine.py`
|
||||
|
||||
Move from `/markitect/plugins/testdrive_jsui.py`:
|
||||
|
||||
```python
|
||||
"""
|
||||
TestDrive-JSUI Rendering Engine.
|
||||
|
||||
Standalone JavaScript UI rendering engine for markdown content.
|
||||
Can be used independently or integrated into any Python application.
|
||||
"""
|
||||
from pathlib import Path
|
||||
from typing import Dict, List, Optional
|
||||
import json
|
||||
|
||||
from .models import PluginMetadata, PluginType
|
||||
from .rendering import RenderingEnginePlugin, RenderingConfig
|
||||
|
||||
|
||||
class TestDriveJSUIEngine(RenderingEnginePlugin):
|
||||
"""
|
||||
TestDrive JavaScript UI rendering engine.
|
||||
|
||||
Usage:
|
||||
>>> from testdrive_jsui import TestDriveJSUIEngine, RenderingConfig
|
||||
>>> engine = TestDriveJSUIEngine()
|
||||
>>> config = RenderingConfig(development_mode=True)
|
||||
>>> html = engine.render_document("# Hello", "edit", config)
|
||||
"""
|
||||
|
||||
def __init__(self):
|
||||
super().__init__()
|
||||
self._metadata = PluginMetadata(
|
||||
name="testdrive-jsui",
|
||||
version="1.0.0",
|
||||
description="Independent JavaScript UI engine for markdown",
|
||||
author="MarkiTect Team",
|
||||
plugin_type=PluginType.RENDERING
|
||||
)
|
||||
|
||||
# ... full implementation from markitect/plugins/testdrive_jsui.py
|
||||
```
|
||||
|
||||
**Why**: Makes the engine part of the testdrive-jsui package, not MarkiTect.
|
||||
|
||||
---
|
||||
|
||||
#### Step 1.4: Update Package __init__.py
|
||||
|
||||
**Update**: `src/testdrive_jsui/__init__.py`
|
||||
|
||||
```python
|
||||
"""
|
||||
TestDrive-JSUI: Standalone JavaScript UI Rendering Engine and Testing Framework
|
||||
|
||||
A self-contained capability providing:
|
||||
- Interactive JavaScript UI for markdown editing and viewing
|
||||
- Python-JavaScript test integration bridge
|
||||
- Standalone rendering engine for any Python project
|
||||
"""
|
||||
|
||||
__version__ = "1.0.0"
|
||||
__author__ = "MarkiTect Team"
|
||||
|
||||
# Core rendering engine
|
||||
from .engine import TestDriveJSUIEngine
|
||||
from .rendering import RenderingEnginePlugin, RenderingConfig
|
||||
from .models import PluginMetadata, PluginType
|
||||
|
||||
# Testing infrastructure
|
||||
from .testing.js_test_runner import JavaScriptTestRunner, JSTestResult
|
||||
from .testing.integration import PythonJSBridge
|
||||
|
||||
__all__ = [
|
||||
# Engine
|
||||
"TestDriveJSUIEngine",
|
||||
"RenderingEnginePlugin",
|
||||
"RenderingConfig",
|
||||
|
||||
# Models
|
||||
"PluginMetadata",
|
||||
"PluginType",
|
||||
|
||||
# Testing
|
||||
"JavaScriptTestRunner",
|
||||
"JSTestResult",
|
||||
"PythonJSBridge",
|
||||
]
|
||||
```
|
||||
|
||||
**Why**: Clean, documented public API for standalone use.
|
||||
|
||||
---
|
||||
|
||||
### Step 1.5: Maintain MarkiTect Compatibility
|
||||
|
||||
**Update**: `/markitect/plugins/testdrive_jsui.py`
|
||||
|
||||
```python
|
||||
"""
|
||||
TestDrive-JSUI Plugin Integration for MarkiTect.
|
||||
|
||||
This is a thin compatibility wrapper that imports the standalone
|
||||
TestDrive-JSUI engine and integrates it with MarkiTect's plugin system.
|
||||
"""
|
||||
from pathlib import Path
|
||||
|
||||
# Import from standalone package
|
||||
from testdrive_jsui import TestDriveJSUIEngine as StandaloneEngine
|
||||
from testdrive_jsui import RenderingConfig as StandaloneConfig
|
||||
|
||||
# Re-export for MarkiTect compatibility
|
||||
TestDriveJSUIEngine = StandaloneEngine
|
||||
RenderingConfig = StandaloneConfig
|
||||
|
||||
# MarkiTect-specific plugin system integration
|
||||
from .base import PluginMetadata, PluginType
|
||||
from .rendering import RenderingEnginePlugin as MarkitectRenderingPlugin
|
||||
|
||||
# Adapter if needed for MarkiTect's plugin system
|
||||
class MarkitectTestDriveJSUIAdapter(MarkitectRenderingPlugin):
|
||||
"""Adapter to integrate standalone engine with MarkiTect plugin system."""
|
||||
|
||||
def __init__(self):
|
||||
self._engine = StandaloneEngine()
|
||||
|
||||
def __getattr__(self, name):
|
||||
# Delegate all calls to standalone engine
|
||||
return getattr(self._engine, name)
|
||||
```
|
||||
|
||||
**Why**: Existing MarkiTect code continues to work without changes.
|
||||
|
||||
---
|
||||
|
||||
### Step 1.6: Update Dependencies
|
||||
|
||||
**Update**: `pyproject.toml`
|
||||
|
||||
```toml
|
||||
[project]
|
||||
name = "testdrive-jsui"
|
||||
version = "1.0.0"
|
||||
description = "Standalone JavaScript UI rendering engine and testing framework"
|
||||
dependencies = [
|
||||
# Minimal dependencies for standalone use
|
||||
"pathlib2>=2.3.0;python_version<'3.4'",
|
||||
]
|
||||
|
||||
[project.optional-dependencies]
|
||||
# Testing remains same
|
||||
testing = [
|
||||
"pytest>=7.0.0",
|
||||
"pytest-xvfb>=3.0.0",
|
||||
"selenium>=4.0.0",
|
||||
]
|
||||
|
||||
# Development tools
|
||||
dev = [
|
||||
"pytest-cov>=4.0.0",
|
||||
"black>=23.0.0",
|
||||
"flake8>=6.0.0",
|
||||
"mypy>=1.0.0",
|
||||
]
|
||||
|
||||
# MarkiTect integration (optional)
|
||||
markitect = [
|
||||
# Only needed if using with MarkiTect plugin system
|
||||
]
|
||||
```
|
||||
|
||||
**Why**: Minimal dependencies for standalone use.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Create Standalone Examples
|
||||
|
||||
### Objective
|
||||
Provide working examples showing standalone usage without MarkiTect.
|
||||
|
||||
### Implementation
|
||||
|
||||
#### Create: `examples/standalone_basic.py`
|
||||
|
||||
```python
|
||||
"""
|
||||
Basic standalone usage of TestDrive-JSUI.
|
||||
|
||||
This example shows how to use TestDrive-JSUI in any Python project
|
||||
without MarkiTect.
|
||||
"""
|
||||
from pathlib import Path
|
||||
from testdrive_jsui import TestDriveJSUIEngine, RenderingConfig
|
||||
|
||||
# Create engine instance
|
||||
engine = TestDriveJSUIEngine()
|
||||
|
||||
# Configure for standalone use
|
||||
config = RenderingConfig(
|
||||
asset_base_url=".", # Serve from current directory
|
||||
development_mode=True,
|
||||
plugin_source_dirs={
|
||||
'testdrive-jsui': engine.get_plugin_source_dir()
|
||||
}
|
||||
)
|
||||
|
||||
# Markdown content to render
|
||||
markdown_content = """
|
||||
# TestDrive-JSUI Standalone Demo
|
||||
|
||||
This document demonstrates **TestDrive-JSUI** running standalone,
|
||||
without any MarkiTect dependencies.
|
||||
|
||||
## Features
|
||||
|
||||
- Interactive markdown editing
|
||||
- Section management
|
||||
- Debug controls
|
||||
- Keyboard shortcuts
|
||||
|
||||
Try editing this content in the browser!
|
||||
"""
|
||||
|
||||
# Render to HTML
|
||||
html = engine.render_document(
|
||||
content=markdown_content,
|
||||
mode='edit', # or 'view' for read-only
|
||||
config=config
|
||||
)
|
||||
|
||||
# Save to file
|
||||
output_path = Path('output.html')
|
||||
output_path.write_text(html, encoding='utf-8')
|
||||
|
||||
print(f"✅ Rendered to: {output_path.absolute()}")
|
||||
print(f"📂 Open in browser: file://{output_path.absolute()}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Create: `examples/flask_integration.py`
|
||||
|
||||
```python
|
||||
"""
|
||||
Flask integration example.
|
||||
|
||||
Shows how to integrate TestDrive-JSUI into a Flask web application.
|
||||
"""
|
||||
from flask import Flask, render_template_string
|
||||
from testdrive_jsui import TestDriveJSUIEngine, RenderingConfig
|
||||
from pathlib import Path
|
||||
|
||||
app = Flask(__name__)
|
||||
|
||||
# Initialize engine once
|
||||
engine = TestDriveJSUIEngine()
|
||||
config = RenderingConfig(
|
||||
asset_base_url="/static",
|
||||
development_mode=False
|
||||
)
|
||||
|
||||
@app.route('/')
|
||||
def index():
|
||||
"""Render markdown with TestDrive-JSUI."""
|
||||
markdown = """
|
||||
# Flask + TestDrive-JSUI
|
||||
|
||||
Edit this markdown content in your browser!
|
||||
"""
|
||||
|
||||
html = engine.render_document(markdown, 'edit', config)
|
||||
return html
|
||||
|
||||
@app.route('/view/<document_id>')
|
||||
def view_document(document_id):
|
||||
"""View a document in read-only mode."""
|
||||
# Load markdown from database/file
|
||||
markdown = load_document(document_id)
|
||||
|
||||
html = engine.render_document(markdown, 'view', config)
|
||||
return html
|
||||
|
||||
if __name__ == '__main__':
|
||||
app.run(debug=True)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Create: `examples/django_integration.py`
|
||||
|
||||
```python
|
||||
"""
|
||||
Django integration example.
|
||||
|
||||
Shows how to use TestDrive-JSUI in Django views.
|
||||
"""
|
||||
from django.http import HttpResponse
|
||||
from django.views import View
|
||||
from testdrive_jsui import TestDriveJSUIEngine, RenderingConfig
|
||||
|
||||
class MarkdownEditorView(View):
|
||||
"""View for editing markdown with TestDrive-JSUI."""
|
||||
|
||||
def __init__(self):
|
||||
self.engine = TestDriveJSUIEngine()
|
||||
self.config = RenderingConfig(
|
||||
asset_base_url="/static",
|
||||
development_mode=False
|
||||
)
|
||||
|
||||
def get(self, request, document_id=None):
|
||||
"""Render markdown editor."""
|
||||
# Load markdown content
|
||||
markdown = self.load_markdown(document_id)
|
||||
|
||||
# Render with TestDrive-JSUI
|
||||
html = self.engine.render_document(
|
||||
markdown,
|
||||
'edit',
|
||||
self.config
|
||||
)
|
||||
|
||||
return HttpResponse(html)
|
||||
|
||||
def post(self, request, document_id):
|
||||
"""Save markdown content."""
|
||||
markdown = request.POST.get('content')
|
||||
self.save_markdown(document_id, markdown)
|
||||
return HttpResponse(status=200)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Create: `examples/README.md`
|
||||
|
||||
```markdown
|
||||
# TestDrive-JSUI Examples
|
||||
|
||||
## Standalone Usage
|
||||
|
||||
### Basic Example
|
||||
```bash
|
||||
python examples/standalone_basic.py
|
||||
```
|
||||
|
||||
Opens `output.html` with an interactive markdown editor.
|
||||
|
||||
### Flask Integration
|
||||
```bash
|
||||
pip install flask
|
||||
python examples/flask_integration.py
|
||||
```
|
||||
|
||||
Visit http://localhost:5000 to see TestDrive-JSUI in Flask.
|
||||
|
||||
### Django Integration
|
||||
See `django_integration.py` for integration with Django views.
|
||||
|
||||
## Requirements
|
||||
|
||||
All examples work with just:
|
||||
```bash
|
||||
pip install testdrive-jsui
|
||||
```
|
||||
|
||||
No MarkiTect required!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Update Documentation
|
||||
|
||||
### Update README.md
|
||||
|
||||
**Section to Add**: "Standalone Installation"
|
||||
|
||||
```markdown
|
||||
## Standalone Installation
|
||||
|
||||
TestDrive-JSUI can be used completely independently:
|
||||
|
||||
```bash
|
||||
# Install from PyPI
|
||||
pip install testdrive-jsui
|
||||
|
||||
# Or install from source
|
||||
pip install -e ./capabilities/testdrive-jsui
|
||||
```
|
||||
|
||||
## Quick Start (Standalone)
|
||||
|
||||
```python
|
||||
from testdrive_jsui import TestDriveJSUIEngine, RenderingConfig
|
||||
|
||||
engine = TestDriveJSUIEngine()
|
||||
config = RenderingConfig(development_mode=True)
|
||||
html = engine.render_document("# Hello World", "edit", config)
|
||||
```
|
||||
|
||||
See `examples/` directory for Flask, Django, and other integrations.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Create: `docs/STANDALONE_GUIDE.md`
|
||||
|
||||
Comprehensive guide covering:
|
||||
- Installation in non-MarkiTect projects
|
||||
- Configuration options
|
||||
- Asset deployment strategies
|
||||
- Framework integrations (Flask, Django, FastAPI)
|
||||
- Production deployment
|
||||
- Customization options
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Testing and Validation
|
||||
|
||||
### Create Standalone Tests
|
||||
|
||||
**Create**: `tests/test_standalone.py`
|
||||
|
||||
```python
|
||||
"""
|
||||
Test standalone usage without MarkiTect dependencies.
|
||||
|
||||
These tests verify the package works independently.
|
||||
"""
|
||||
import pytest
|
||||
from pathlib import Path
|
||||
|
||||
def test_import_without_markitect():
|
||||
"""Verify imports work without MarkiTect."""
|
||||
# Should not raise ImportError
|
||||
from testdrive_jsui import TestDriveJSUIEngine
|
||||
from testdrive_jsui import RenderingConfig
|
||||
from testdrive_jsui import JavaScriptTestRunner
|
||||
|
||||
assert TestDriveJSUIEngine is not None
|
||||
assert RenderingConfig is not None
|
||||
assert JavaScriptTestRunner is not None
|
||||
|
||||
def test_engine_initialization():
|
||||
"""Test engine can be initialized standalone."""
|
||||
from testdrive_jsui import TestDriveJSUIEngine
|
||||
|
||||
engine = TestDriveJSUIEngine()
|
||||
assert engine is not None
|
||||
assert engine.metadata.name == "testdrive-jsui"
|
||||
|
||||
def test_render_document_standalone():
|
||||
"""Test document rendering works standalone."""
|
||||
from testdrive_jsui import TestDriveJSUIEngine, RenderingConfig
|
||||
|
||||
engine = TestDriveJSUIEngine()
|
||||
config = RenderingConfig(development_mode=True)
|
||||
|
||||
html = engine.render_document("# Test", "edit", config)
|
||||
|
||||
assert html is not None
|
||||
assert "Test" in html
|
||||
assert "<html" in html
|
||||
|
||||
def test_no_markitect_imports():
|
||||
"""Verify no MarkiTect imports in standalone code."""
|
||||
import testdrive_jsui
|
||||
import inspect
|
||||
|
||||
# Get all source code
|
||||
source = inspect.getsource(testdrive_jsui)
|
||||
|
||||
# Should not import from markitect
|
||||
assert "from markitect" not in source
|
||||
assert "import markitect" not in source
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Create Isolated Test Environment
|
||||
|
||||
```bash
|
||||
# Create clean virtual environment
|
||||
python -m venv test_standalone
|
||||
source test_standalone/bin/activate
|
||||
|
||||
# Install ONLY testdrive-jsui (not MarkiTect)
|
||||
pip install -e ./capabilities/testdrive-jsui
|
||||
|
||||
# Run standalone tests
|
||||
pytest capabilities/testdrive-jsui/tests/test_standalone.py -v
|
||||
|
||||
# Try examples
|
||||
python capabilities/testdrive-jsui/examples/standalone_basic.py
|
||||
```
|
||||
|
||||
**Success Criteria**: All tests pass without MarkiTect installed.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Distribution and Packaging
|
||||
|
||||
### Prepare for PyPI
|
||||
|
||||
#### Update pyproject.toml
|
||||
|
||||
```toml
|
||||
[project]
|
||||
name = "testdrive-jsui"
|
||||
version = "1.0.0"
|
||||
description = "Standalone JavaScript UI rendering engine for markdown content"
|
||||
readme = "README.md"
|
||||
license = {text = "MIT"}
|
||||
authors = [
|
||||
{name = "MarkiTect Team", email = "team@markitect.dev"}
|
||||
]
|
||||
|
||||
keywords = [
|
||||
"markdown", "editor", "javascript", "ui", "rendering",
|
||||
"testing", "jest", "pytest", "standalone"
|
||||
]
|
||||
|
||||
classifiers = [
|
||||
"Development Status :: 4 - Beta",
|
||||
"Intended Audience :: Developers",
|
||||
"License :: OSI Approved :: MIT License",
|
||||
"Programming Language :: Python :: 3",
|
||||
"Programming Language :: Python :: 3.8",
|
||||
"Programming Language :: Python :: 3.9",
|
||||
"Programming Language :: Python :: 3.10",
|
||||
"Programming Language :: Python :: 3.11",
|
||||
"Programming Language :: Python :: 3.12",
|
||||
"Topic :: Software Development :: Libraries",
|
||||
"Topic :: Text Editors",
|
||||
"Framework :: Flask",
|
||||
"Framework :: Django",
|
||||
]
|
||||
|
||||
[project.urls]
|
||||
Homepage = "https://github.com/markitect/testdrive-jsui"
|
||||
Documentation = "https://docs.markitect.com/testdrive-jsui"
|
||||
Repository = "https://github.com/markitect/testdrive-jsui"
|
||||
"Bug Tracker" = "https://github.com/markitect/testdrive-jsui/issues"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Include Assets in Package
|
||||
|
||||
**Create**: `MANIFEST.in`
|
||||
|
||||
```
|
||||
# Include JavaScript, CSS, and templates
|
||||
recursive-include src/testdrive_jsui/js *.js
|
||||
recursive-include src/testdrive_jsui/static *.css *.html *.png *.jpg *.svg
|
||||
|
||||
# Include documentation
|
||||
include README.md
|
||||
include LICENSE
|
||||
include CLAUDE.md
|
||||
recursive-include docs *.md
|
||||
|
||||
# Include examples
|
||||
recursive-include examples *.py *.md
|
||||
|
||||
# Exclude development files
|
||||
exclude MIGRATION_STATUS.md
|
||||
exclude CLEANUP_REPORT.md
|
||||
recursive-exclude * __pycache__
|
||||
recursive-exclude * *.py[co]
|
||||
recursive-exclude * .DS_Store
|
||||
```
|
||||
|
||||
**Update**: `pyproject.toml`
|
||||
|
||||
```toml
|
||||
[tool.setuptools]
|
||||
packages = ["testdrive_jsui"]
|
||||
package-dir = {"" = "src"}
|
||||
|
||||
[tool.setuptools.package-data]
|
||||
testdrive_jsui = [
|
||||
"js/**/*.js",
|
||||
"static/**/*",
|
||||
"templates/**/*",
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Build and Test Distribution
|
||||
|
||||
```bash
|
||||
cd capabilities/testdrive-jsui
|
||||
|
||||
# Install build tools
|
||||
pip install build twine
|
||||
|
||||
# Build distribution
|
||||
python -m build
|
||||
|
||||
# Test installation in clean environment
|
||||
python -m venv test_dist
|
||||
source test_dist/bin/activate
|
||||
pip install dist/testdrive_jsui-1.0.0-py3-none-any.whl
|
||||
|
||||
# Verify it works
|
||||
python -c "from testdrive_jsui import TestDriveJSUIEngine; print('✅ Success')"
|
||||
|
||||
# Run example
|
||||
python examples/standalone_basic.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Publish to PyPI (when ready)
|
||||
|
||||
```bash
|
||||
# Test PyPI first
|
||||
python -m twine upload --repository testpypi dist/*
|
||||
|
||||
# Verify installation from Test PyPI
|
||||
pip install --index-url https://test.pypi.org/simple/ testdrive-jsui
|
||||
|
||||
# If all good, publish to real PyPI
|
||||
python -m twine upload dist/*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
### Standalone Usability Checklist
|
||||
|
||||
- [ ] Can `pip install testdrive-jsui` in empty environment
|
||||
- [ ] Can `from testdrive_jsui import TestDriveJSUIEngine` works
|
||||
- [ ] No MarkiTect imports in standalone code
|
||||
- [ ] Examples work without MarkiTect
|
||||
- [ ] All tests pass in isolated environment
|
||||
- [ ] Documentation covers standalone usage
|
||||
- [ ] Package includes all necessary assets
|
||||
- [ ] Works with Flask/Django/FastAPI
|
||||
- [ ] MarkiTect integration still works
|
||||
- [ ] Published to PyPI (optional)
|
||||
|
||||
### Maturity Assessment After Implementation
|
||||
|
||||
| Aspect | Before | After | Target |
|
||||
|--------|--------|-------|--------|
|
||||
| Python API | 60% | 95% | 95% |
|
||||
| Standalone Use | 30% | 95% | 95% |
|
||||
| Documentation | 80% | 95% | 95% |
|
||||
| Distribution | 40% | 90% | 90% |
|
||||
| Examples | 20% | 90% | 90% |
|
||||
| **Overall** | **60%** | **94%** | **95%** |
|
||||
|
||||
---
|
||||
|
||||
## Implementation Timeline
|
||||
|
||||
### Week 1: Core Infrastructure
|
||||
- Day 1-2: Extract base classes (Phase 1.1, 1.2)
|
||||
- Day 3-4: Move engine implementation (Phase 1.3, 1.4)
|
||||
- Day 5: Update dependencies and compatibility (Phase 1.5, 1.6)
|
||||
|
||||
### Week 2: Examples and Documentation
|
||||
- Day 1-2: Create standalone examples (Phase 2)
|
||||
- Day 3-4: Update documentation (Phase 3)
|
||||
- Day 5: Testing and validation (Phase 4)
|
||||
|
||||
### Week 3: Distribution
|
||||
- Day 1-2: Prepare packaging (Phase 5)
|
||||
- Day 3: Test distribution
|
||||
- Day 4-5: Buffer for issues and polish
|
||||
|
||||
**Total Effort**: ~15 days
|
||||
|
||||
---
|
||||
|
||||
## Risks and Mitigation
|
||||
|
||||
### Risk 1: Breaking MarkiTect Integration
|
||||
**Mitigation**:
|
||||
- Keep compatibility wrapper in `/markitect/plugins/`
|
||||
- Run MarkiTect tests after each change
|
||||
- Maintain adapter pattern
|
||||
|
||||
### Risk 2: Missing Assets in Package
|
||||
**Mitigation**:
|
||||
- Comprehensive MANIFEST.in
|
||||
- Test wheel installation
|
||||
- Verify assets accessible
|
||||
|
||||
### Risk 3: Complex Dependencies
|
||||
**Mitigation**:
|
||||
- Keep dependencies minimal
|
||||
- Optional dependencies for advanced features
|
||||
- Document requirements clearly
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Review this plan** with team
|
||||
2. **Create feature branch**: `feature/standalone-reusability`
|
||||
3. **Implement Phase 1**: Core infrastructure
|
||||
4. **Validate**: Test in isolated environment
|
||||
5. **Continue phases**: Examples, docs, distribution
|
||||
6. **Release v1.0.0**: First standalone release
|
||||
|
||||
---
|
||||
|
||||
**End of Standalone Reusability Plan**
|
||||
Reference in New Issue
Block a user