mirror of
https://github.com/ivuorinen/everforest-resources.git
synced 2026-01-26 03:04:02 +00:00
feat: initial scaffold and generator
- Complete project structure with directories for all target platforms - Template system for CLI tools with color placeholder replacement - Working generator that processes templates for 6 theme variants - GitHub workflows for build, snapshots, commitlint, and cli-verify - Installer and verifier scripts for CLI tool deployment - Comprehensive documentation and specifications - Biome 2.x linting and formatting setup - Husky git hooks for pre-commit validation
This commit is contained in:
123
.serena/memories/architecture-deep-dive.md
Normal file
123
.serena/memories/architecture-deep-dive.md
Normal file
@@ -0,0 +1,123 @@
|
||||
# Architecture Deep Dive - Everforest Resources
|
||||
|
||||
## Core Generator Architecture
|
||||
|
||||
### EverforestGenerator Class
|
||||
Located in `scripts/generate-themes.mjs`, this is the heart of the system:
|
||||
|
||||
```javascript
|
||||
class EverforestGenerator {
|
||||
constructor() {
|
||||
this.palette = null; // Loaded from palettes/everforest.json
|
||||
}
|
||||
|
||||
// Key methods:
|
||||
async loadPalette() // Loads JSON palette definition
|
||||
async processTemplate() // Processes template.txt with placeholders
|
||||
getColorsForVariant() // Maps palette to color variables
|
||||
async generateAll() // Main entry point - generates all variants
|
||||
async generateVariant() // Processes single variant
|
||||
}
|
||||
```
|
||||
|
||||
### Template Processing System
|
||||
1. **Template Files**: Each CLI tool has `template.txt` in its directory
|
||||
2. **Placeholders**: `{{bg}}`, `{{fg}}`, `{{red}}`, etc. replaced with actual colors
|
||||
3. **Variant Processing**: Generates 6 versions (dark/light × hard/medium/soft)
|
||||
4. **Output Generation**: Creates final config files from processed templates
|
||||
|
||||
### Palette Structure
|
||||
```json
|
||||
{
|
||||
"variants": {
|
||||
"dark": { "hard": {...}, "medium": {...}, "soft": {...} },
|
||||
"light": { "hard": {...}, "medium": {...}, "soft": {...} }
|
||||
},
|
||||
"accents": { "red": "#e67e80", "orange": "#e69875", ... },
|
||||
"grays": { "dark": {...}, "light": {...} }
|
||||
}
|
||||
```
|
||||
|
||||
## Supported Tools & Platforms
|
||||
|
||||
### CLI Tools (24+ supported)
|
||||
- **System Monitors**: btop, bottom, glances, neofetch, htop
|
||||
- **File Management**: ranger, lf, mc, LS_COLORS, eza/exa
|
||||
- **Git Tools**: lazygit, gitui, tig, delta
|
||||
- **Search & Processing**: ripgrep, fzf, fd, jq, bat
|
||||
- **Shell & Productivity**: starship, zsh, fish, tmux, less
|
||||
- **Modern Utils**: zoxide, atuin
|
||||
|
||||
### Editors (5 types)
|
||||
- **Neovim**: Lua module with setup() function
|
||||
- **VS Code**: JSON themes + package.json
|
||||
- **JetBrains**: Unified .icls files (IntelliJ, WebStorm, PyCharm, etc.)
|
||||
- **Zed**: JSON theme files
|
||||
- **Sublime Text**: .sublime-color-scheme files
|
||||
|
||||
### Terminals
|
||||
- WezTerm, Alacritty, Kitty, Windows Terminal, Ghostty
|
||||
|
||||
## Color Philosophy
|
||||
|
||||
### ANSI vs Hex Usage
|
||||
- **CLI Tools**: ANSI-16 SGR codes only (no raw hex)
|
||||
- **GUI Applications**: Hex values allowed (from generator only)
|
||||
- **Consistent Mapping**: Same semantic colors across all tools
|
||||
|
||||
### Theme Variants
|
||||
- **Dark**: hard/medium/soft (different background intensities)
|
||||
- **Light**: hard/medium/soft (different background intensities)
|
||||
- **Fallback**: Medium variant if specific not available
|
||||
|
||||
## File Structure Pattern
|
||||
|
||||
```
|
||||
cli/
|
||||
starship/
|
||||
template.txt # Template with {{color}} placeholders
|
||||
starship.toml # Generated output (never edit directly)
|
||||
README.md # Tool-specific documentation
|
||||
|
||||
fish/
|
||||
colors-template.txt # Multiple templates for complex tools
|
||||
prompt-template.txt
|
||||
tide-template.txt
|
||||
everforest-*.fish # Generated variants
|
||||
README.md
|
||||
```
|
||||
|
||||
## Development Patterns
|
||||
|
||||
### Generator Extension
|
||||
To add new CLI tool:
|
||||
1. Create `cli/newtool/template.txt`
|
||||
2. Add processing logic to generator
|
||||
3. Update installer and verifier
|
||||
4. Add to documentation
|
||||
|
||||
### Template Design
|
||||
- Use semantic color names: `{{bg}}` not `{{color1}}`
|
||||
- Include tool-specific syntax
|
||||
- Test with all 6 variants
|
||||
- Follow tool's native config format
|
||||
|
||||
### Error Handling
|
||||
- Graceful failures with descriptive messages
|
||||
- Exit codes for CI integration
|
||||
- Emoji-prefixed console output for visibility
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### Required Checks
|
||||
1. **build**: Generator runs successfully
|
||||
2. **snapshots**: Web demo renders correctly
|
||||
3. **commitlint**: Conventional commit format
|
||||
4. **cli-verify**: Generated configs work in container
|
||||
|
||||
### Validation Pipeline
|
||||
1. Palette structure validation
|
||||
2. Template processing verification
|
||||
3. No raw hex in CLI configs
|
||||
4. All variants present
|
||||
5. File structure compliance
|
||||
139
.serena/memories/code-style-conventions.md
Normal file
139
.serena/memories/code-style-conventions.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# Code Style & Conventions - Everforest Resources
|
||||
|
||||
## JavaScript/Node.js Style
|
||||
|
||||
### Module System
|
||||
- **ES Modules**: All files use `.mjs` extension
|
||||
- **Imports**: Use ES6 import/export syntax
|
||||
- **Type**: `"type": "module"` in package.json
|
||||
|
||||
### Biome Configuration
|
||||
The project uses **Biome 2.x** for linting and formatting with these settings:
|
||||
- **Version**: 2.2.3 (latest)
|
||||
- **Indent**: 2 spaces
|
||||
- **Line width**: 100 characters
|
||||
- **Quotes**: Single quotes for JavaScript, double for JSX
|
||||
- **Semicolons**: Always required
|
||||
- **Trailing commas**: ES5 style
|
||||
- **Arrow parentheses**: As needed
|
||||
|
||||
### Class Structure
|
||||
```javascript
|
||||
class EverforestGenerator {
|
||||
constructor() {
|
||||
this.palette = null;
|
||||
}
|
||||
|
||||
async methodName() {
|
||||
// Async/await preferred over Promises
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Naming Conventions
|
||||
- **Classes**: PascalCase (`EverforestGenerator`)
|
||||
- **Methods**: camelCase (`loadPalette`, `processTemplate`)
|
||||
- **Constants**: camelCase for most, UPPER_SNAKE_CASE for true constants
|
||||
- **Files**: kebab-case (`generate-themes.mjs`)
|
||||
|
||||
### Error Handling
|
||||
- Use try-catch blocks for async operations
|
||||
- Log errors with emoji prefixes: `console.error('❌ Failed to load palette')`
|
||||
- Exit with code 1 on critical errors: `process.exit(1)`
|
||||
|
||||
### Console Output
|
||||
- Use emoji for visual feedback:
|
||||
- ✅ Success messages
|
||||
- ❌ Error messages
|
||||
- 🎨 Starting operations
|
||||
- 📝 Progress updates
|
||||
- ✨ Completion messages
|
||||
|
||||
### Code Quality Rules
|
||||
- **Variables**: Use `const` by default, `let` when reassignment needed
|
||||
- **Functions**: Prefer arrow functions for callbacks
|
||||
- **Imports**: Organize imports automatically with Biome
|
||||
- **Unused Variables**: Not allowed (error level)
|
||||
- **Block Statements**: Always use braces for control structures
|
||||
- **forEach**: Allowed for side effects (useIterableCallbackReturn disabled)
|
||||
|
||||
## Template System Conventions
|
||||
|
||||
### Placeholder Format
|
||||
- Use double curly braces: `{{colorName}}`
|
||||
- Available placeholders: `{{bg}}`, `{{fg}}`, `{{red}}`, `{{orange}}`, `{{yellow}}`, `{{green}}`, `{{aqua}}`, `{{blue}}`, `{{purple}}`, `{{gray1}}`, `{{gray2}}`, `{{gray3}}`
|
||||
|
||||
### Template Files
|
||||
- Named `template.txt` in each tool directory
|
||||
- Multiple templates for complex tools (e.g., `colors-template.txt`, `prompt-template.txt`)
|
||||
- Never edit generated output files directly
|
||||
|
||||
## Documentation Style
|
||||
|
||||
### Code Comments
|
||||
- Use JSDoc-style comments for classes and methods
|
||||
- Include purpose and architecture notes at file top
|
||||
- Explain complex logic inline
|
||||
|
||||
### Markdown
|
||||
- **Critical Rule**: Use indented code blocks only (4 spaces)
|
||||
- Never use triple backticks (```)
|
||||
- Use emoji in headers and lists for visual hierarchy
|
||||
|
||||
## Git Conventions
|
||||
|
||||
### Commit Messages
|
||||
- Follow Conventional Commits format
|
||||
- Examples:
|
||||
- `feat: add starship theme generator`
|
||||
- `fix: correct color mapping in templates`
|
||||
- `docs: update CLI installation guide`
|
||||
|
||||
### Branch Strategy
|
||||
- Main branch: `main`
|
||||
- All CI checks must pass for merge
|
||||
- Required checks: lint + build + snapshots + commitlint + cli-verify
|
||||
|
||||
## File Organization
|
||||
|
||||
### Directory Structure
|
||||
```
|
||||
palettes/ # Color definitions (JSON/YAML)
|
||||
scripts/ # Generator and validation scripts
|
||||
cli/ # CLI tool templates and configs
|
||||
editors/ # Editor theme files
|
||||
terminals/ # Terminal configurations
|
||||
web/ # CSS and demo files
|
||||
docs/ # Documentation
|
||||
meta/ # Project specifications
|
||||
biome.json # Biome 2.x configuration
|
||||
```
|
||||
|
||||
### File Naming
|
||||
- Scripts: `kebab-case.mjs`
|
||||
- Configs: Tool-specific conventions
|
||||
- Templates: `template.txt` or `tool-template.txt`
|
||||
|
||||
### Biome File Processing
|
||||
Biome processes these files:
|
||||
- JavaScript modules: `scripts/**/*.mjs`, `scripts/**/*.js`
|
||||
- JSON files: `*.json`
|
||||
- Root level JS files: `*.mjs`, `*.js`
|
||||
|
||||
Biome ignores:
|
||||
- Generated output files
|
||||
- Node modules and build artifacts
|
||||
- Unknown file types (by default)
|
||||
|
||||
## Development Commands
|
||||
```bash
|
||||
# Format code
|
||||
npm run format # Format all files with Biome 2.x
|
||||
|
||||
# Lint code
|
||||
npm run lint # Check for issues
|
||||
npm run lint:fix # Auto-fix issues
|
||||
|
||||
# Before committing
|
||||
npm run lint:fix && npm run format
|
||||
```
|
||||
47
.serena/memories/project-overview.md
Normal file
47
.serena/memories/project-overview.md
Normal file
@@ -0,0 +1,47 @@
|
||||
# Everforest Resources - Project Overview
|
||||
|
||||
## Purpose
|
||||
The **everforest-resources** repository is an unofficial hub for Everforest color scheme resources. It generates theme files, configurations, and color schemes for terminals, CLI tools, and editors from canonical palette definitions.
|
||||
|
||||
## Key Philosophy
|
||||
- **Generator-first approach**: All outputs are generated from `palettes/everforest.json`
|
||||
- **Template system**: Uses `template.txt` files with color placeholders (e.g., `{{bg}}`, `{{fg}}`, `{{red}}`)
|
||||
- **No manual editing**: Generated artifacts must never be hand-edited
|
||||
- **Comprehensive coverage**: Supports 24+ CLI tools, 5+ editors, multiple terminals
|
||||
|
||||
## Tech Stack
|
||||
- **Runtime**: Node.js with ES modules (type: "module")
|
||||
- **Language**: JavaScript (.mjs files)
|
||||
- **Code Quality**: Biome 2.2.3 for linting and formatting
|
||||
- **Testing**: Playwright for web snapshots (when implemented)
|
||||
- **CI/CD**: Husky for git hooks, conventional commits
|
||||
- **Package Management**: npm
|
||||
|
||||
## Core Architecture
|
||||
- **Palette**: JSON definitions with 6 variants (dark/light × hard/medium/soft)
|
||||
- **Generator**: `EverforestGenerator` class processes templates and generates themes
|
||||
- **Templates**: Color placeholder system for consistent theming
|
||||
- **Output**: Generates configs for terminals, CLI tools, editors, and web
|
||||
|
||||
## Target Platforms
|
||||
- **Terminals**: WezTerm, Alacritty, Kitty, Windows Terminal, Ghostty
|
||||
- **CLI Tools**: 24+ tools including btop, lazygit, starship, fzf, ripgrep
|
||||
- **Editors**: Neovim, VS Code, JetBrains IDEs, Zed, Sublime Text
|
||||
- **Web**: CSS variables with media queries
|
||||
|
||||
## Development Status
|
||||
- ✅ Project structure and specifications complete
|
||||
- ✅ Basic generator scaffold implemented
|
||||
- ✅ Biome 2.x linting and formatting integrated and working
|
||||
- ✅ Code quality pipeline working (lint → generate → validate)
|
||||
- ✅ Latest tooling versions (Biome 2.2.3)
|
||||
- ⏳ Full template processing implementation pending
|
||||
- ⏳ CLI tool generators pending
|
||||
- ⏳ Editor theme generators pending
|
||||
- ⏳ Playwright web tests pending
|
||||
|
||||
## Quality Assurance
|
||||
- **Biome 2.x**: All JavaScript code passes linting and formatting with latest version
|
||||
- **Validation**: Generator outputs validated for structure and compliance
|
||||
- **CI Pipeline**: Automated checks for code quality and generation consistency
|
||||
- **Modern Tooling**: Using latest stable versions of all development tools
|
||||
97
.serena/memories/suggested-commands.md
Normal file
97
.serena/memories/suggested-commands.md
Normal file
@@ -0,0 +1,97 @@
|
||||
# Suggested Commands - Everforest Resources
|
||||
|
||||
## Core Development Commands
|
||||
|
||||
### Theme Generation
|
||||
```bash
|
||||
npm run generate # Generate all theme files from palettes
|
||||
node scripts/generate-themes.mjs # Direct generator execution
|
||||
```
|
||||
|
||||
### Code Quality & Linting
|
||||
```bash
|
||||
npm run lint # Check code with Biome linter
|
||||
npm run lint:fix # Auto-fix linting issues with Biome
|
||||
npm run format # Format code with Biome
|
||||
npm run validate # Validate generated outputs and structure
|
||||
npm run ci # Full CI suite: lint + generate + validate + snapshots
|
||||
```
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
npm run snapshots # Generate Playwright web snapshots
|
||||
playwright test # Direct Playwright execution
|
||||
```
|
||||
|
||||
### Git & Setup
|
||||
```bash
|
||||
npm run prepare # Install Husky git hooks
|
||||
npm install # Install dependencies
|
||||
```
|
||||
|
||||
### Alternative Commands (Makefile - when implemented)
|
||||
```bash
|
||||
make generate # Alternative to npm run generate
|
||||
make validate # Alternative to npm run validate
|
||||
make ci # Alternative to npm run ci
|
||||
make snapshots # Generate web snapshots
|
||||
make demo # Run web demo server
|
||||
```
|
||||
|
||||
## Installation & Deployment
|
||||
```bash
|
||||
./cli/install.sh # Deploy all configs to ~/.config (when implemented)
|
||||
ENGINE=docker ./verify/verify.sh # Verify in container (when implemented)
|
||||
```
|
||||
|
||||
## Development Workflow Commands
|
||||
```bash
|
||||
# 1. Edit palette or templates
|
||||
vim palettes/everforest.json
|
||||
vim cli/starship/template.txt
|
||||
|
||||
# 2. Lint and format code
|
||||
npm run lint:fix # Fix any linting issues
|
||||
npm run format # Ensure consistent formatting
|
||||
|
||||
# 3. Generate themes
|
||||
npm run generate
|
||||
|
||||
# 4. Validate output
|
||||
npm run validate
|
||||
|
||||
# 5. Test web components
|
||||
npm run snapshots
|
||||
|
||||
# 6. Full CI check
|
||||
npm run ci
|
||||
|
||||
# 7. Commit changes
|
||||
git add -A
|
||||
git commit -m "feat: update starship theme colors"
|
||||
```
|
||||
|
||||
## Biome Commands
|
||||
```bash
|
||||
biome check . # Check all files for issues
|
||||
biome check . --write # Auto-fix issues
|
||||
biome format . --write # Format all supported files
|
||||
biome lint . # Lint JavaScript/TypeScript files
|
||||
```
|
||||
|
||||
## System Commands (macOS/Darwin)
|
||||
```bash
|
||||
# File operations
|
||||
ls -la # List files with details
|
||||
find . -name "*.mjs" # Find JavaScript modules
|
||||
grep -r "template" . # Search for template references
|
||||
|
||||
# Directory navigation
|
||||
pwd # Current directory
|
||||
cd scripts/ # Change to scripts directory
|
||||
|
||||
# Git operations
|
||||
git status # Check git status
|
||||
git log --oneline # View commit history
|
||||
git diff # View changes
|
||||
```
|
||||
141
.serena/memories/task-completion-checklist.md
Normal file
141
.serena/memories/task-completion-checklist.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# Task Completion Checklist - Everforest Resources
|
||||
|
||||
## When a Development Task is Completed
|
||||
|
||||
### 1. Code Quality Checks
|
||||
```bash
|
||||
# Lint and format code first
|
||||
npm run lint:fix # Auto-fix any linting issues
|
||||
npm run format # Ensure consistent formatting
|
||||
|
||||
# Generate themes from updated templates/palettes
|
||||
npm run generate
|
||||
|
||||
# Validate all outputs
|
||||
npm run validate
|
||||
|
||||
# Check for any errors or warnings
|
||||
# All validation must pass before proceeding
|
||||
```
|
||||
|
||||
### 2. Testing Requirements
|
||||
```bash
|
||||
# Run Playwright snapshots (for web changes)
|
||||
npm run snapshots
|
||||
|
||||
# Full CI pipeline (includes linting)
|
||||
npm run ci
|
||||
|
||||
# Verify no errors in any step
|
||||
```
|
||||
|
||||
### 3. File Verification
|
||||
- **Never commit generated files without running generator**
|
||||
- **Always commit palette + template + generated files together**
|
||||
- Check that all 6 variants are generated (dark/light × hard/medium/soft)
|
||||
- Ensure code passes Biome linting and formatting
|
||||
|
||||
### 4. Documentation Updates
|
||||
- Update relevant README or docs if adding new tools
|
||||
- Ensure all examples use indented code blocks (4 spaces)
|
||||
- Never use triple backticks in documentation
|
||||
- Run `npm run format` to ensure consistent formatting
|
||||
|
||||
### 5. Git Workflow
|
||||
```bash
|
||||
# Check status
|
||||
git status
|
||||
|
||||
# Lint and format before committing
|
||||
npm run lint:fix
|
||||
npm run format
|
||||
|
||||
# Stage all changes (palette + template + generated)
|
||||
git add -A
|
||||
|
||||
# Commit with conventional format
|
||||
git commit -m "feat: add new CLI tool theme"
|
||||
# or
|
||||
git commit -m "fix: correct color mapping in starship"
|
||||
# or
|
||||
git commit -m "docs: update installation guide"
|
||||
|
||||
# Push changes
|
||||
git push
|
||||
```
|
||||
|
||||
### 6. CI/CD Requirements
|
||||
All these checks must pass in CI before merge:
|
||||
- ✅ **lint**: Biome linting and formatting checks
|
||||
- ✅ **build**: Generator + validation
|
||||
- ✅ **snapshots**: Playwright demo renders
|
||||
- ✅ **commitlint**: Conventional Commits enforcement
|
||||
- ✅ **cli-verify**: Install + verify generated configs
|
||||
|
||||
### 7. Critical Rules Verification
|
||||
- [ ] Code passes Biome linting (no errors)
|
||||
- [ ] Code is properly formatted with Biome
|
||||
- [ ] No raw hex values in CLI configs (ANSI only)
|
||||
- [ ] All generated files come from templates/palettes
|
||||
- [ ] No manual edits to generated files
|
||||
- [ ] Template placeholders used correctly
|
||||
- [ ] All 6 theme variants present where applicable
|
||||
|
||||
### 8. Special Considerations
|
||||
|
||||
#### For New CLI Tools
|
||||
- Create `template.txt` with proper placeholders
|
||||
- Add to generator processing logic
|
||||
- Update installer script
|
||||
- Add to verifier container
|
||||
- Document in appropriate README
|
||||
- Ensure any new JS/MJS files follow Biome style
|
||||
|
||||
#### For Palette Changes
|
||||
- Regenerate ALL theme files
|
||||
- Verify no breaking changes in output formats
|
||||
- Test web demo still renders correctly
|
||||
- Check that ANSI mappings remain valid
|
||||
|
||||
#### For Template Updates
|
||||
- Test with all 6 variants
|
||||
- Verify placeholder replacement works
|
||||
- Check output format matches tool expectations
|
||||
|
||||
#### For JavaScript/Code Changes
|
||||
- Run `npm run lint:fix` to auto-fix issues
|
||||
- Run `npm run format` for consistent formatting
|
||||
- Ensure imports are organized correctly
|
||||
- Follow established naming conventions
|
||||
|
||||
### 9. Before Pushing
|
||||
```bash
|
||||
# Final verification with full CI
|
||||
npm run ci
|
||||
|
||||
# If all passes, ready to push
|
||||
git push origin main
|
||||
```
|
||||
|
||||
## Emergency Fixes
|
||||
If CI fails after push:
|
||||
1. Check error logs in GitHub Actions
|
||||
2. For linting errors: `npm run lint:fix` locally
|
||||
3. For generation errors: `rm -rf generated/ && npm run generate`
|
||||
4. Fix locally with proper workflow above
|
||||
5. Push fix immediately
|
||||
|
||||
## Biome-Specific Troubleshooting
|
||||
```bash
|
||||
# Check what Biome would fix
|
||||
npm run lint
|
||||
|
||||
# Auto-fix all fixable issues
|
||||
npm run lint:fix
|
||||
|
||||
# Format all files
|
||||
npm run format
|
||||
|
||||
# Check specific file
|
||||
biome check scripts/generate-themes.mjs
|
||||
```
|
||||
Reference in New Issue
Block a user