Regenerate agent instructions from state-hub templates (CUST-WP-0055 T01)
Sync AGENTS.md, CLAUDE.md, and .claude/rules from updated project_rules templates: workplan-first session protocol, legacy terminology footnote, and GET /workplans/ examples.
This commit is contained in:
parent
9af4c03b6d
commit
85b2dfe318
11 changed files with 361 additions and 363 deletions
374
CLAUDE.md
374
CLAUDE.md
|
|
@ -1,362 +1,12 @@
|
|||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Overview
|
||||
|
||||
**TestDrive-JSUI is a JavaScript-first markdown editor library.**
|
||||
|
||||
This is a pure JavaScript library for interactive markdown editing that works standalone in any browser. Language adapters (Python, Ruby, Java) are **optional integration helpers** - they do NOT provide core functionality.
|
||||
|
||||
**Key Facts**:
|
||||
- **Core:** Complete JavaScript library (`js/testdrive-jsui.js`)
|
||||
- **Dependencies:** Only marked.js for markdown parsing
|
||||
- **Standalone:** Works without any backend (can run from file://)
|
||||
- **Optional Adapters:** Python/Ruby/Java adapters help with asset serving and backend integration
|
||||
- **Architecture:** JavaScript-first design (see `ARCHITECTURE.md`)
|
||||
|
||||
## JavaScript Library
|
||||
|
||||
### Quick Start
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
|
||||
<script src="js/testdrive-jsui.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<div id="editor"></div>
|
||||
<script>
|
||||
const editor = new TestDriveJSUI({
|
||||
container: '#editor',
|
||||
markdown: '# Hello World\n\nEdit me!',
|
||||
mode: 'edit',
|
||||
theme: 'github'
|
||||
});
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
### API
|
||||
|
||||
**Constructor Options:**
|
||||
- `container` (required): CSS selector or DOM element
|
||||
- `markdown`: Initial content
|
||||
- `mode`: 'edit' or 'view' (default: 'edit')
|
||||
- `theme`: Theme name (default: 'github')
|
||||
- `autosave`: Auto-save enabled (default: false)
|
||||
- `shortcuts`: Keyboard shortcuts (default: true)
|
||||
- `sections`: Section-based editing (default: true)
|
||||
- `debug`: Debug mode (default: false)
|
||||
|
||||
**Methods:**
|
||||
- `getMarkdown()`: Get current content
|
||||
- `setMarkdown(markdown)`: Set content
|
||||
- `getStatus()`: Get editor status
|
||||
- `save()`: Trigger save event
|
||||
- `download(filename)`: Download as .md file
|
||||
- `on(event, callback)`: Listen to events
|
||||
- `destroy()`: Clean up
|
||||
|
||||
**Events:** `initialized`, `save`, `content-changed`, `autosave`, `download`, `reset`, `destroyed`
|
||||
|
||||
### Examples
|
||||
|
||||
See `/examples`:
|
||||
- `standalone.html` - Minimal proof of concept
|
||||
- `full-editor.html` - Complete demo with all features
|
||||
|
||||
## Migration Status
|
||||
|
||||
**✅ MIGRATION FULLY COMPLETE - ALL PHASES**
|
||||
|
||||
This capability migration is now **fully complete** including cleanup. The main MarkiTect application exclusively uses the capability location, and legacy files have been removed.
|
||||
|
||||
**Current Status**: ✅ Phase 4 Complete (December 16, 2025)
|
||||
- All 24 original JavaScript files copied to capability ✅
|
||||
- 84 automated tests passing (68 JS + 15 Python + 1 fixes) ✅
|
||||
- Templates updated to use capability location ✅
|
||||
- Main app **fully using capability** (no hybrid approach) ✅
|
||||
- Verified in both view and edit modes ✅
|
||||
- **Legacy files removed** - cleanup complete ✅
|
||||
|
||||
**Key Facts**:
|
||||
- **Main app status**: Fully migrated to capability location
|
||||
- **Original files**: **REMOVED** from `/markitect/static/js/` (Phase 4 cleanup)
|
||||
- **Single source of truth**: All JavaScript in `/capabilities/testdrive-jsui/js/`
|
||||
- **Testing**: All rendering modes work correctly
|
||||
- **Migration**: Fully complete - no further phases needed
|
||||
|
||||
**Documentation**: See `MIGRATION_STATUS.md` for complete migration details, all phases, and final verification results.
|
||||
|
||||
## Build and Test Commands
|
||||
|
||||
### Setup
|
||||
```bash
|
||||
# Complete setup (Python + JavaScript dependencies)
|
||||
make testdrive-jsui-setup
|
||||
|
||||
# Check environment status
|
||||
make testdrive-jsui-status
|
||||
```
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
# Run all tests (recommended before commits)
|
||||
make testdrive-jsui-test-all
|
||||
|
||||
# Run JavaScript tests only (Jest)
|
||||
make testdrive-jsui-test-js
|
||||
npm test
|
||||
|
||||
# Run specific JavaScript test
|
||||
npm test -- --testNamePattern="SectionManager"
|
||||
|
||||
# Run Python integration tests only
|
||||
make testdrive-jsui-test-python
|
||||
pytest tests/ -v
|
||||
|
||||
# Run tests with coverage
|
||||
npm run test:coverage
|
||||
|
||||
# Watch mode for development
|
||||
make testdrive-jsui-watch
|
||||
```
|
||||
|
||||
### Linting and Formatting
|
||||
```bash
|
||||
# Lint JavaScript
|
||||
make testdrive-jsui-lint-js
|
||||
|
||||
# Lint Python
|
||||
make testdrive-jsui-lint-python
|
||||
|
||||
# Format Python code with black
|
||||
make testdrive-jsui-format-python
|
||||
```
|
||||
|
||||
### Cleanup
|
||||
```bash
|
||||
make testdrive-jsui-clean
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
### Directory Structure
|
||||
```
|
||||
testdrive-jsui/
|
||||
├── js/ # JavaScript library (Core functionality)
|
||||
│ ├── testdrive-jsui.js # 🎯 Main library entry point
|
||||
│ ├── core/ # Core JS: debug-system, section-manager
|
||||
│ ├── components/ # UI components: dom-renderer, debug-panel, document-controls
|
||||
│ ├── controls/ # Control panels: edit, debug, status, contents
|
||||
│ ├── plugins/ # JS plugins
|
||||
│ ├── widgets/ # UI widgets
|
||||
│ ├── utils/ # JS utilities
|
||||
│ ├── tests/ # JavaScript tests (Jest)
|
||||
│ ├── config-loader.js # Configuration loader
|
||||
│ ├── main.js # Legacy main entry point
|
||||
│ └── main-updated.js # Refactored main entry
|
||||
├── examples/ # 📚 Working examples
|
||||
│ ├── standalone.html # Minimal proof of concept
|
||||
│ └── full-editor.html # Complete demo
|
||||
├── src/testdrive_jsui/ # Python adapter (optional)
|
||||
│ ├── core/ # Adapter core
|
||||
│ ├── components/ # Adapter helpers
|
||||
│ ├── utils/ # Utilities
|
||||
│ └── testing/ # Python-JS bridge
|
||||
│ ├── js_test_runner.py # JavaScript test execution
|
||||
│ └── integration.py # Pytest integration
|
||||
├── static/ # Static assets
|
||||
│ ├── css/ # Stylesheets (editor, controls, themes)
|
||||
│ ├── images/ # Image assets and icons
|
||||
│ └── templates/ # HTML templates
|
||||
├── tests/ # Python tests
|
||||
├── docs/ # Documentation
|
||||
│ ├── prototypes/ # Archived HTML prototypes
|
||||
│ └── migration/ # Migration records
|
||||
├── ARCHITECTURE.md # JavaScript-first architecture details
|
||||
└── README.md # Main documentation
|
||||
```
|
||||
|
||||
### Key Design Principles
|
||||
|
||||
**JavaScript-First Architecture** (NEW in v1.0.0)
|
||||
- **Core functionality in JavaScript**: All UI logic, rendering, and editing in JS
|
||||
- **Standalone capable**: Works without any backend (can run from file://)
|
||||
- **marked.js only dependency**: For markdown parsing
|
||||
- **Language adapters optional**: Python/Ruby/Java are integration helpers, not functionality providers
|
||||
- **Event-driven API**: Clean event system for integration
|
||||
- **See `ARCHITECTURE.md`** for complete architectural documentation
|
||||
|
||||
**Plugin Independence**
|
||||
- **Self-declaring**: Plugin declares its own location - no hardcoded paths needed
|
||||
- **Single source of truth**: All assets in one capability directory
|
||||
- **Clean boundaries**: JSON config interface between adapters and JavaScript
|
||||
- **No code mixing**: JavaScript stays in `.js` files, never embedded in strings
|
||||
- Works regardless of installation location
|
||||
|
||||
**Testing Architecture**
|
||||
- **Dual-track testing**: JavaScript tests (Jest) + Python integration tests (pytest)
|
||||
- **Python-JS bridge**: `JavaScriptTestRunner` executes JS tests from Python
|
||||
- **Test isolation**: Proper setup/teardown with JSDOM environment
|
||||
- **Coverage integration**: Combines Python and JavaScript coverage
|
||||
|
||||
**Component Organization**
|
||||
- **Core**: `debug-system.js`, `section-manager.js` - fundamental framework components
|
||||
- **Components**: `dom-renderer.js`, `debug-panel.js` - UI rendering components
|
||||
- **Controls**: `control-base.js`, `edit-control.js`, `debug-control.js`, `status-control.js`, `contents-control.js` - interactive control panels
|
||||
- All components are modular and testable in isolation
|
||||
|
||||
### Python-JavaScript Bridge
|
||||
|
||||
The capability provides seamless integration between Python and JavaScript tests:
|
||||
|
||||
**JavaScriptTestRunner** (`src/testdrive_jsui/testing/js_test_runner.py`):
|
||||
- Executes JavaScript tests via subprocess (Node.js + Jest)
|
||||
- Parses JSON test results into Python dataclasses (`JSTestResult`)
|
||||
- Provides methods: `run_js_tests()`, `run_specific_test()`, `list_available_tests()`
|
||||
- Auto-discovers capability root if not specified
|
||||
- Validates Node.js environment before execution
|
||||
|
||||
**Usage Example**:
|
||||
```python
|
||||
from testdrive_jsui.testing import JavaScriptTestRunner
|
||||
|
||||
runner = JavaScriptTestRunner()
|
||||
result = runner.run_js_tests(coverage=True)
|
||||
assert result.success
|
||||
assert result.tests_passed > 0
|
||||
```
|
||||
|
||||
### Jest Configuration
|
||||
|
||||
Located in `package.json` (no separate jest.config.js):
|
||||
- **Test environment**: jsdom
|
||||
- **Test patterns**: `**/js/tests/**/*.test.js`
|
||||
- **Coverage**: Collects from `js/core/`, `js/components/`, `js/utils/`
|
||||
- **Setup**: `js/tests/jest.setup.js`
|
||||
- **Ignored files**: `refactor-test-runner.js`, `setup.js`
|
||||
|
||||
### Pytest Configuration
|
||||
|
||||
Located in `pyproject.toml`:
|
||||
- **Test paths**: `tests/`, `src/testdrive_jsui/tests/`
|
||||
- **Markers**: `@pytest.mark.javascript` for JS integration tests
|
||||
- **Coverage target**: 58% minimum
|
||||
- **Addopts**: Strict markers, verbose output, coverage reports
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Adding JavaScript Components
|
||||
|
||||
1. Create component in appropriate `js/` subdirectory (`core/`, `components/`, `controls/`, etc.)
|
||||
2. Write tests in `js/tests/` with naming: `component-name.test.js` or `test-component-name.js`
|
||||
3. Run tests: `npm test`
|
||||
4. Add Python integration tests if needed in `tests/`
|
||||
|
||||
### Adding Python Integration
|
||||
|
||||
1. Create test in `tests/` directory
|
||||
2. Use `JavaScriptTestRunner` to execute JS tests from Python
|
||||
3. Mark with `@pytest.mark.javascript` for selective test execution
|
||||
4. Run: `pytest tests/ -v -m javascript`
|
||||
|
||||
### Migration Strategy (Copy-First)
|
||||
|
||||
**Status**: ✅ ALL PHASES COMPLETE - See `MIGRATION_STATUS.md` for full details
|
||||
|
||||
The capability followed a **copy-first, verify-later** migration principle:
|
||||
|
||||
**Phase 1: Copy** ✅ COMPLETE (December 16, 2025)
|
||||
1. ✅ Copy all original files to `js/` directory
|
||||
2. ✅ Verify copies are correct
|
||||
3. ✅ Run all tests in capability
|
||||
4. ✅ Document current state
|
||||
|
||||
**Phase 2: Dual-Track Testing** (SKIPPED)
|
||||
- Skipped as Phase 1 testing was comprehensive enough
|
||||
|
||||
**Phase 3: Gradual Switch** ✅ COMPLETE (December 16, 2025)
|
||||
1. ✅ Update templates to use capability location
|
||||
2. ✅ Test each change individually (view & edit modes)
|
||||
3. ✅ Maintain rollback capability (originals preserved)
|
||||
4. ✅ Monitor for issues (none found)
|
||||
|
||||
**Phase 4: Cleanup** ✅ COMPLETE (December 16, 2025)
|
||||
1. ✅ Remove original files (29 files deleted)
|
||||
2. ✅ Update documentation references
|
||||
3. ✅ Archive migration records
|
||||
4. ✅ Tag final migration commit
|
||||
|
||||
**Final State**: Migration **fully complete**. Main app exclusively uses capability location. Legacy files removed. Single source of truth: `/capabilities/testdrive-jsui/js/`. All tests passing. See `MIGRATION_STATUS.md` for complete history.
|
||||
|
||||
## Common Development Tasks
|
||||
|
||||
### Running Single Test
|
||||
```bash
|
||||
# JavaScript
|
||||
npm test -- --testNamePattern="specific test name"
|
||||
|
||||
# Python
|
||||
pytest tests/test_specific.py -v
|
||||
```
|
||||
|
||||
### Debugging Tests
|
||||
```bash
|
||||
# Verbose JavaScript output
|
||||
npm run test:verbose
|
||||
|
||||
# Python with debug output
|
||||
pytest tests/ -v -s
|
||||
```
|
||||
|
||||
### Checking Test Coverage
|
||||
```bash
|
||||
# JavaScript coverage (generates coverage/ directory)
|
||||
npm run test:coverage
|
||||
|
||||
# Python coverage (included in pytest runs)
|
||||
pytest tests/ -v --cov=testdrive_jsui --cov-report=html
|
||||
```
|
||||
|
||||
### Development Watch Mode
|
||||
```bash
|
||||
# Auto-rerun tests on file changes
|
||||
make testdrive-jsui-watch
|
||||
# or
|
||||
npm run test:watch
|
||||
```
|
||||
|
||||
## Important Notes
|
||||
|
||||
### Code Quality Standards
|
||||
- **ESLint**: Standard config with Jest plugin, warns on `console`, errors on `debugger`
|
||||
- **Black**: Python formatting with 88 char line length
|
||||
- **MyPy**: Strict typing for Python code (can be disabled for tests)
|
||||
|
||||
### Test Execution Order
|
||||
When running `make testdrive-jsui-test-all`:
|
||||
1. JavaScript tests (Jest)
|
||||
2. JavaScript fixes test (Python-based validation)
|
||||
3. Python integration tests (pytest)
|
||||
4. HTML manual tests (available for browser testing)
|
||||
|
||||
### Node.js Requirements
|
||||
- Node.js 16+ required for JavaScript testing
|
||||
- npm automatically installs dependencies from `package.json`
|
||||
- If Node.js unavailable, JavaScript tests gracefully skip with warning
|
||||
|
||||
### Rendering Modes
|
||||
The engine supports two modes:
|
||||
- `'edit'`: Interactive editing mode with controls
|
||||
- `'view'`: View-only mode
|
||||
|
||||
Validate modes before rendering:
|
||||
```python
|
||||
if engine.validate_mode('edit'):
|
||||
html = engine.render_document(content, 'edit', config)
|
||||
```
|
||||
# testdrive-jsui — Claude Code Instructions
|
||||
|
||||
@SCOPE.md
|
||||
@.claude/rules/repo-identity.md
|
||||
@.claude/rules/session-protocol.md
|
||||
@.claude/rules/first-session.md
|
||||
@.claude/rules/workplan-convention.md
|
||||
@.claude/rules/stack-and-commands.md
|
||||
@.claude/rules/architecture.md
|
||||
@.claude/rules/repo-boundary.md
|
||||
@.claude/rules/credential-routing.md
|
||||
@.claude/rules/agents.md
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue