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:
167
AGENTS.md
Normal file
167
AGENTS.md
Normal file
@@ -0,0 +1,167 @@
|
||||
# Everforest Resources — Specification
|
||||
|
||||
This document consolidates all gathered knowledge for the github.com/ivuorinen/everforest-resources repository. It is the authoritative spec for implementation. All instructions SHALL be followed strictly. LLM AGENTS SHALL NOT DEVIATE FROM THE THEME SPEC.
|
||||
|
||||
## 1. Philosophy
|
||||
|
||||
- This repository is the unofficial hub for Everforest resources.
|
||||
- All outputs are generator-first, derived strictly from palettes/everforest.(json|yaml).
|
||||
- Template system: CLI tools use template.txt files with color placeholders (e.g., {{bg}}, {{fg}}, {{red}}) that are replaced by the generator.
|
||||
- CLI tools and prompts use ANSI-16 SGR codes only. No raw hex or 256-color indices.
|
||||
- GUI/editor themes may use hex values but only those emitted by the generator.
|
||||
- Generated artifacts MUST NOT be hand-edited.
|
||||
|
||||
## 2. Theme Variants
|
||||
|
||||
- Variants: dark/light × hard/medium/soft.
|
||||
- If a variant is missing, fallback to medium.
|
||||
- All variants MUST be present for terminals, CLI tools, editors, and web.
|
||||
|
||||
## 3. Repository Layout
|
||||
|
||||
- palettes/: canonical Everforest palette definitions (json/yaml).
|
||||
- scripts/: generator scripts (Node.js, mjs modules).
|
||||
- terminals/: WezTerm, Alacritty, Kitty, Windows Terminal, Ghostty.
|
||||
- web/: CSS vars, demo with Playwright snapshot tests.
|
||||
- cli/: all cli tools and prompts.
|
||||
- editors/: all IDEs and editors.
|
||||
- docs/: CLI.md and other documentation.
|
||||
- verify/: container verifier.
|
||||
- .github/: workflows, CODEOWNERS.
|
||||
|
||||
## 4. CLI Tools
|
||||
|
||||
- LS_COLORS: archives → bold yellow (orange), images → purple, docs → blue.
|
||||
- dircolors: generated alongside LS_COLORS.
|
||||
- eza/exa: export EXA_COLORS/EZA_COLORS.
|
||||
- ripgrep: ripgreprc with ANSI mappings.
|
||||
- fzf: FZF_DEFAULT_OPTS snippet with Everforest accents.
|
||||
- delta: git-delta config with ANSI mapping.
|
||||
- bat: minimal config forwarding to terminal theme.
|
||||
- htop: htoprc with color_scheme=0.
|
||||
- starship: starship.toml with Everforest accent mappings.
|
||||
- zsh: Pure and Powerlevel10k presets.
|
||||
- fish: color schemes, minimal prompt, Tide preset.
|
||||
- tmux: everforest.tmux.conf with ANSI mappings.
|
||||
- btop: modern htop alternative with color customization.
|
||||
- bottom: cross-platform system monitor with color themes.
|
||||
- glances: system monitoring tool with color themes.
|
||||
- neofetch: system information display with color support.
|
||||
- ranger: terminal file manager with color scheme support.
|
||||
- lf: lightweight file manager (ranger alternative).
|
||||
- mc: Midnight Commander with theme support.
|
||||
- lazygit: terminal UI for git with theme support.
|
||||
- gitui: terminal UI for git with color customization.
|
||||
- tig: text-mode git interface with color customization.
|
||||
- fd: find alternative with color output.
|
||||
- jq: JSON processor with syntax highlighting.
|
||||
- less: pager with color support via LESS_TERMCAP.
|
||||
- zoxide: smart cd command with prompt integration.
|
||||
- atuin: shell history with TUI theming.
|
||||
|
||||
## 5. Editors
|
||||
|
||||
- Neovim minimal:
|
||||
- Lua module everforest_minimal.lua.
|
||||
- Accepts setup({ variant, contrast }).
|
||||
- Applies highlights from palette tokens.
|
||||
- VS Code:
|
||||
- Generated themes for all six variants.
|
||||
- package.json scaffold.
|
||||
- Extension can be launched in Dev Host.
|
||||
- JetBrains (unified):
|
||||
- Single .icls theme files for all variants.
|
||||
- Compatible with IntelliJ, WebStorm, PyCharm, CLion, GoLand, PHPStorm, Rider.
|
||||
- Zed:
|
||||
- JSON theme files for all six variants.
|
||||
- Sublime Text:
|
||||
- .sublime-color-scheme files for all six variants.
|
||||
|
||||
## 6. Web
|
||||
|
||||
- CSS vars with media queries.
|
||||
- Playwright snapshots in CI for dark/light × hard/medium/soft.
|
||||
|
||||
## 7. Installer
|
||||
|
||||
- cli/install.sh deploys all configs under ~/.config.
|
||||
- Symlinks or copies files for shells, tools, editors unless file already exists.
|
||||
- If file already exists, check if it is an Everforest config.
|
||||
- If it is, overwrite with new version.
|
||||
- Also loads dircolors automatically if available.
|
||||
|
||||
## 8. Verifier
|
||||
|
||||
- verify/verify.sh builds a Debian container with all cli tools.
|
||||
- Sources and validates all generated configs.
|
||||
- CI job cli-verify runs installer + verifier.
|
||||
|
||||
## 9. CI/CD
|
||||
|
||||
- build: generator + validation.
|
||||
- snapshots: Playwright demo renders, upload PNGs.
|
||||
- commitlint: Conventional Commits enforcement.
|
||||
- cli-verify: install + verify generated configs.
|
||||
- Branch protection requires build + snapshots + commitlint + cli-verify.
|
||||
|
||||
## 10. Contributing
|
||||
|
||||
- Edit only palettes/everforest.(json|yaml) and template.txt files.
|
||||
- Templates use placeholders: {{bg}}, {{fg}}, {{red}}, {{orange}}, {{yellow}}, {{green}}, {{aqua}}, {{blue}}, {{purple}}, {{gray1}}, {{gray2}}, {{gray3}}.
|
||||
- Run npm run generate and commit both palette + template + generated files.
|
||||
- Pre-commit hooks block raw hex and enforce regeneration.
|
||||
- LLM AGENTS SHALL NOT DEVIATE FROM THE THEME SPEC.
|
||||
|
||||
TL;DR (README section)
|
||||
|
||||
1. Edit only palettes and templates.
|
||||
2. Run generate.
|
||||
3. Commit palette + template + generated.
|
||||
4. CI must pass build + snapshots + verify.
|
||||
|
||||
CODEOWNERS
|
||||
|
||||
`* @ivuorinen`
|
||||
|
||||
CONTRIBUTING.md rules
|
||||
|
||||
- Never hardcode hex outside palettes.
|
||||
- Do not hand-edit generated files.
|
||||
- Edit templates using color placeholders only.
|
||||
- Add new targets by extending generator.
|
||||
- Commit style: Conventional Commits.
|
||||
- PR checklist: palette/template edits, regenerated, validated, snapshots included.
|
||||
|
||||
## 11. Makefile
|
||||
|
||||
Convenience targets:
|
||||
generate → npm run generate
|
||||
validate → npm run validate
|
||||
ci → npm run ci
|
||||
install-lscolors → copy LS_COLORS snippet
|
||||
demo → run web demo server
|
||||
snapshots → run Playwright snapshots
|
||||
|
||||
## 12. Docs `docs/CLI.md`
|
||||
|
||||
### Everforest CLI
|
||||
|
||||
Contains overview of terminals, web, CLI tools, prompts, editors.
|
||||
Install with ./cli/install.sh
|
||||
Verify with ENGINE=docker ./verify/verify.sh
|
||||
|
||||
Notes:
|
||||
LLM AGENTS SHALL NOT DEVIATE FROM THE THEME SPEC. Use palettes or ANSI names. No raw hex.
|
||||
|
||||
## 13. Release Checklist
|
||||
|
||||
- Tag version (start v0.1.0).
|
||||
- Ensure build, snapshots, verify all pass.
|
||||
- Package VS Code extension (vsix).
|
||||
- Announce as unofficial Everforest resource hub.
|
||||
|
||||
## 14. Enforcement
|
||||
|
||||
- Indented code blocks MUST be used in all docs.
|
||||
- No triple backticks allowed.
|
||||
- All new contributions MUST follow this spec exactly.
|
||||
Reference in New Issue
Block a user