rob
/
development-hub
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
development-hub/CLAUDE.md

366 lines
15 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
**Development Hub** is the central orchestration project for Rob's multi-project development ecosystem. It provides:
1. **GUI Application** - PyQt6-based workspace with project list, splittable terminal panes, and session persistence
2. **CLI Tools** - Scripts to create and manage projects following consistent patterns
## GUI Application
### Running the App
```bash
cd ~/PycharmProjects/development-hub
source .venv/bin/activate
python -m development_hub
```
### Architecture
```
src/development_hub/
├── __init__.py
├── __main__.py # Entry point
├── app.py # QApplication subclass
├── main_window.py # Main window with menus
├── project_list.py # Left panel - project list with filter
├── workspace_manager.py # Splittable pane layout management
├── pane_widget.py # Tab container with action menu
├── draggable_tab_widget.py # Cross-pane tab dragging support
├── terminal_widget.py # PTY terminal with search bar
├── terminal_display.py # Terminal rendering with scrollback
├── pty_manager.py # PTY process management
├── project_discovery.py # Auto-discover projects from paths
├── dialogs.py # New Project, Settings, Setup Wizard dialogs
├── settings.py # JSON persistence for settings & session
├── paths.py # Centralized path resolution from settings
├── styles.py # Dark theme stylesheet
├── models/ # Data models (Goal, Todo, Milestone)
├── views/dashboard/ # Dashboard views and components
│ ├── project_dashboard.py
│ ├── data_store.py # Data loading/saving with file watching
│ └── undo_manager.py # Undo/redo support
├── parsers/ # Markdown file parsers
├── services/ # Business logic (git, health, progress)
└── widgets/ # Reusable UI components
```
### Key Classes
| Class | File | Purpose |
|-------|------|---------|
| `MainWindow` | main_window.py | QMainWindow with menus, splitter layout |
| `ProjectListWidget` | project_list.py | Project list with filter and context menu |
| `WorkspaceManager` | workspace_manager.py | Manages splittable pane layout |
| `PaneWidget` | pane_widget.py | Tab container with action menu |
| `DraggableTabWidget` | draggable_tab_widget.py | Tab widget supporting cross-pane drag |
| `TerminalWidget` | terminal_widget.py | PTY terminal with search and auto-accept |
| `TerminalDisplay` | terminal_display.py | Terminal rendering with scrollback buffer |
| `AutoAcceptToast` | terminal_widget.py | Countdown toast for auto-accept prompts |
| `AutoAcceptDialog` | dialogs.py | Duration selection for auto-accept |
| `ImportPlanDialog` | dialogs.py | Import implementation plans to milestones |
| `SetupWizardDialog` | dialogs.py | Multi-page first-run wizard |
| `SettingsDialog` | dialogs.py | Application settings with docs mode |
| `PathResolver` | paths.py | Centralized path resolution singleton |
| `DashboardDataStore` | views/dashboard/data_store.py | Data persistence with file watching |
| `UndoManager` | views/dashboard/undo_manager.py | Undo/redo action management |
### Features
- **Project List**: Discovers projects from configurable search paths
- **Project Filtering**: Filter box to quickly find projects by name or key
- **Context Menu**: Open terminal, editor, git host, docs, deploy (items hidden when not configured)
- **Splittable Panes**: Horizontal/vertical splits, each pane has own tab bar
- **Cross-Pane Tab Dragging**: Drag tabs between panes to reorganize workspace
- **Terminal**: Full PTY with pyte for TUI support (vim, htop work)
- **Terminal Scrollback**: 10,000 line history with Shift+PageUp/Down navigation
- **Terminal Search**: Ctrl+Shift+F to search output with match highlighting
- **Terminal Error Recovery**: Graceful shell crash handling, Enter to restart
- **Drag & Drop**: Drop files/folders into terminal to inject paths
- **Session Persistence**: Remembers pane layout and open terminals
- **External File Watching**: Dashboard auto-reloads when files modified externally
- **New Project Dialog**: Integrates with Ramble for voice input
- **Progress Reports**: Export weekly progress summaries from daily standups
- **Auto-accept Prompts**: Automatically accept Y/yes prompts in terminals for CLI tools (Claude, Codex, etc.)
- **Plan Import**: Import implementation plans into milestones via right-click context menu
- **Phase Grouping**: Todos can be grouped by phase within milestones using `[Phase N]` prefix
- **Milestone Discussions**: Start discussions directly from milestones for implementation planning
- **Workspace Files**: Export/import configuration via YAML for sharing setups
- **First-Run Wizard**: Multi-page setup wizard with Simple/Documentation/Import modes
- **Documentation Modes**: Standalone (local storage) or Project-Docs (Docusaurus integration)
- **Graceful Degradation**: Features hide when dependencies unavailable (CmdForge, git, docs)
### Keyboard Shortcuts
#### Global Shortcuts
| Shortcut | Action |
|----------|--------|
| `Ctrl+Shift+T` | New terminal tab |
| `Ctrl+Shift+W` | Close current tab |
| `Ctrl+Shift+D` | Split pane horizontal |
| `Ctrl+Shift+E` | Split pane vertical |
| `Ctrl+Shift+P` | Close active pane |
| `Ctrl+Alt+Left/Right` | Switch panes |
| `Ctrl+B` | Toggle project panel |
| `Ctrl+G` | Global Dashboard |
| `Ctrl+N` | New project dialog |
| `Ctrl+D` | New discussion |
| `Ctrl+R` | Weekly progress report |
| `Ctrl+Z` | Undo (in dashboard) |
| `Ctrl+Shift+Z` | Redo (in dashboard) |
| `F5` | Refresh project list |
#### Terminal Shortcuts
| Shortcut | Action |
|----------|--------|
| `Ctrl+Shift+F` | Open search bar |
| `Ctrl+Shift+V` | Paste from clipboard |
| `Shift+PageUp/Down` | Scroll through history |
| `Enter` (in search) | Next match |
| `Shift+Enter` (in search) | Previous match |
| `F3` / `Shift+F3` | Next/previous match |
| `Escape` | Close search bar |
### Auto-accept Prompts
The terminal includes an auto-accept feature for handling Y/yes confirmation prompts from CLI tools like Claude Code, Codex, etc. This is useful when running long-running AI tasks that may ask many permission questions.
**How to use:**
1. Click ☰ (action menu) → "Auto-accept prompts..."
2. Select a duration (5 min, 15 min, 30 min, 1 hour, or custom)
3. When a Y/yes prompt is detected, a toast appears with a 5-second countdown
4. Click "Skip" to ignore, "Accept" to confirm immediately, or wait for countdown
5. Tab badge shows remaining time (e.g., `⏱4:32`)
6. Click ☰ → "Stop auto-accept" to disable early
**Supported patterns:**
- Standard `[Y/n]`, `[y/N]`, `(y/n)` prompts
- Claude Code permission dialogs with `❯ 1. Yes` menu selection
#### Dashboard Shortcuts (when dashboard tab is active)
| Shortcut | Action |
|----------|--------|
| `/` | Focus add todo input |
| `Ctrl+1` | Switch to priority view |
| `Ctrl+2` | Switch to milestone view |
| `Ctrl+3` | Switch to show all view |
| `Ctrl+]` | Expand all sections |
| `Ctrl+[` | Collapse all sections |
### Dashboard Data Sync
The dashboard automatically syncs data between documentation files:
- **Deliverables → TODOs**: When loading a project dashboard, deliverables from `milestones.md` tables are synced to `todos.md`. If a deliverable doesn't exist as a todo (matched by text + milestone ID), it's added with the appropriate `@M#` tag and priority.
- **TODOs → Milestone Progress**: The milestone progress bar is calculated from linked todos (items tagged with `@M#`), not from the deliverables table.
This means you can define major work items in milestone deliverable tables, and they'll automatically appear in your todo list for tracking.
### Todo Notes
Todos can have optional notes that provide additional context. Notes are displayed as tooltips when hovering over todo items and are persisted as indented blockquote lines in `todos.md`:
```markdown
- [ ] [Phase 1] Add settings module @M4
> File: settings.py - Add DEFAULTS and properties
- [ ] Task without notes @M4
```
Notes are automatically extracted when importing plans via the Import Plan dialog and preserved through save/reload cycles.
### Workspace Files
Development Hub supports exporting and importing configuration via YAML workspace files. This allows sharing setups between machines or users.
**Export/Import via menu:** File → Export Workspace... / Import Workspace...
**Workspace file format:**
```yaml
# ~/.devhub-workspace.yaml
name: "My Development Environment"
version: 1
paths:
projects_root: ~/PycharmProjects
docs_root: ~/PycharmProjects/project-docs/docs # Optional
documentation:
enabled: true
mode: project-docs # "standalone" | "project-docs"
docusaurus_path: ~/PycharmProjects/project-docs
auto_start_server: true
git_hosting:
type: gitea # "gitea" | "github" | "gitlab"
url: https://gitea.example.com
owner: username
pages_url: https://pages.example.com # Optional
features:
cmdforge_integration: true
progress_tracking: true
```
### Documentation Modes
Development Hub supports two documentation modes:
1. **Standalone Mode**: Data stored locally in `~/.local/share/development-hub/`. No Docusaurus integration. Good for simple use cases.
2. **Project-Docs Mode**: Full Docusaurus integration with centralized documentation. Supports auto-start docs server, deploy scripts, and pages hosting.
The mode is configured during first-run setup or in Settings → Documentation.
### First-Run Wizard
On first launch (when no `settings.json` exists), the setup wizard appears with three options:
1. **Simple Mode**: Quick setup with just a projects directory. Documentation features disabled.
2. **Documentation Mode**: Full setup with Docusaurus path, git hosting, and pages configuration.
3. **Import Workspace**: Load settings from a `.devhub-workspace.yaml` file.
Existing users are unaffected - the wizard only appears when `setup_completed` is false.
## CLI Scripts
### `bin/new-project`
Creates a new project in the ecosystem with all the standard setup:
```bash
# Full usage
new-project myproject --title "My Project" --tagline "Short description"
# Interactive mode (prompts for title/tagline)
new-project myproject
# Options
--title "..." Display title for the project
--tagline "..." Short description
--dry-run Show what would happen without making changes
--skip-gitea Skip Gitea repository creation (for offline use)
```
**What it does:**
1. Creates Gitea repository via API
2. Creates local project directory with git
3. Generates project files from templates (CLAUDE.md, README.md, .gitignore, pyproject.toml)
4. Sets up documentation symlink to project-docs
5. Updates build-public-docs.sh to include the new project
6. Creates initial commit and pushes
## Project Structure
```
development-hub/
├── src/development_hub/ # GUI application (see Architecture above)
├── bin/
│ └── new-project # CLI scaffolding script
├── templates/
│ ├── gitignore.template # Python .gitignore with docs exclusion
│ ├── CLAUDE.md.template # AI context file
│ ├── README.md.template # Basic README
│ ├── pyproject.toml.template
│ ├── overview.md.template # Docs overview
│ └── updating-documentation.md.template
├── docs/ # Symlink to project-docs
├── pyproject.toml # Python packaging with PyQt6 dep
├── CLAUDE.md # This file
├── README.md
└── .gitignore
```
## Template Placeholders
Templates use these placeholders (replaced by sed):
- `{{PROJECT_NAME}}` - lowercase project name (e.g., "my-tool")
- `{{PROJECT_TITLE}}` - display title (e.g., "My Tool")
- `{{PROJECT_TAGLINE}}` - short description
- `{{YEAR}}` - current year
- `{{DATE}}` - creation date
- `{{GITEA_URL}}` - https://gitea.brrd.tech
- `{{GITEA_OWNER}}` - rob
## Configuration
### Settings File
Settings are stored in `~/.config/development-hub/settings.json`. Key settings:
| Setting | Default | Description |
|---------|---------|-------------|
| `docs_mode` | `"auto"` | `"auto"`, `"standalone"`, or `"project-docs"` |
| `docs_root` | `""` | Override docs root path (empty = derive from mode) |
| `docusaurus_path` | `""` | Path to project-docs directory |
| `pages_url` | `""` | URL for documentation pages hosting |
| `cmdforge_path` | `""` | Override CmdForge installation path |
| `progress_dir` | `""` | Override progress log directory |
| `auto_start_docs_server` | `true` | Start Docusaurus dev server on launch |
| `git_host_type` | `""` | `"gitea"`, `"github"`, or `"gitlab"` |
| `git_host_url` | `""` | Git hosting URL |
| `git_host_owner` | `""` | Username or organization |
| `git_host_token` | `""` | API token for repo creation |
### Path Resolution
The `PathResolver` class (`paths.py`) centralizes all path lookups:
```python
from development_hub.paths import paths
paths.projects_root # Primary projects directory
paths.docs_root # Documentation root
paths.project_docs_dir # Docusaurus project directory
paths.progress_dir # Progress log directory
paths.build_script # build-public-docs.sh path
paths.cmdforge_executable # CmdForge binary path
paths.project_docs_path("myproject") # Docs for specific project
paths.git_url("owner", "repo") # Git repository URL
paths.pages_url("owner", "repo") # Pages URL for project
```
### Gitea API Token
The script needs a Gitea API token to create repositories:
1. **Environment variable**: `GITEA_TOKEN`
2. **Config file**: `~/.config/development-hub/gitea-token`
To create a token:
1. Go to https://gitea.brrd.tech/user/settings/applications
2. Generate a new token with 'repo' scope
3. The script will prompt and save it automatically
## Documentation
Documentation lives in the centralized docs system:
- **Source**: `~/PycharmProjects/project-docs/docs/projects/development-hub/`
- **Public URL**: `https://pages.brrd.tech/rob/development-hub/`
When updating documentation:
1. Edit files in `docs/` (the symlink)
2. Use `public: true` frontmatter for public-facing docs
3. Run `~/PycharmProjects/project-docs/scripts/build-public-docs.sh development-hub --deploy` to publish
## Related Projects
This project manages and creates projects in the ecosystem:
- **CmdForge** - AI-powered CLI tool builder
- **CascadingDev** - Cascading Development Framework
- **Orchestrated Discussions** - AI Discussion Framework
- **Artifact Editor** - Code Artifact Editor
- **Ramble** - Voice Note Transcription
All projects follow the same documentation pattern and can be created using `new-project`.
Reference in New Issue View Git Blame Copy Permalink