diff --git a/.agent/workflows/publish-change.md b/.agent/workflows/publish-change.md index 650b3e6..b4b705a 100644 --- a/.agent/workflows/publish-change.md +++ b/.agent/workflows/publish-change.md @@ -48,5 +48,12 @@ Finalize the snapshot and push to the remote. Once the PR is approved and merged into the integration branch: -7. Create a release tag - `gh release create v1.0.0 --generate-notes` +8. Create a release tag (Automated) + + ```bash + # Dry run to check version + jj next-minor + + # Create release + gh release create $(jj next-minor) --generate-notes + ``` diff --git a/.trunk/trunk.yaml b/.trunk/trunk.yaml index 78141de..f4d9763 100644 --- a/.trunk/trunk.yaml +++ b/.trunk/trunk.yaml @@ -21,12 +21,16 @@ lint: - yamllint@1.37.1 - actionlint@1.7.9 - checkov@3.2.496 + - codespell@2.2.6 - git-diff-check - markdownlint@0.47.0 - prettier@3.7.4 - - shellcheck@0.11.0 + - ruff@0.1.6 + - shellcheck@0.11.0: + autofix: false - shfmt@3.6.0 - taplo@0.10.0 + - trivy@0.48.1 - trufflehog@3.92.4 actions: disabled: diff --git a/README.md b/README.md index a51b786..5cb1f7a 100644 --- a/README.md +++ b/README.md @@ -5,64 +5,43 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-1.1.0-blue.svg)](https://github.com/Thomo1318/jjConfig/releases) [![jj](https://img.shields.io/badge/jj-0.23.0+-purple.svg)](https://github.com/jj-vcs/jj) -[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md) +[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](docs/guides/contributing.md) --- ## ✨ Features -- ⚡ 20+ command aliases for efficient workflows -- 🔍 Smart revsets for advanced commit selection -- 🔗 Git integration with colocated repo support -- 🤖 GitMCP: AI context generation via local Git hooks -- 📦 Repomix: Full repository consolidation for AI context injection -- 🖥️ TUI support: jj-fzf, lazyjj, and gg integration -- 📚 21 reference files for tiered configurations -- 📦 SemVer tracking and versioned backups -- 🚀 Makefile: one-command symlink deployment -- 🎨 Synthwave84 color scheme (retro-futuristic, 30+ custom terminal colors) +- ⚡ **20+ command aliases** for efficient workflows +- 🔗 **Git & GitHub Integration** with colocated repo support +- 🤖 **GitMCP**: AI context generation via local Git hooks +- 📦 **Repomix**: Full repository consolidation for AI context injection +- 🖥️ **TUI support**: jj-fzf, lazyjj, and gg integration +- 🎨 **Synthwave84** color scheme (retro-futuristic) +- 🔒 **Security**: Pre-push hooks, PII sanitization, and secret scanning --- -## 📋 Table of Contents +## 📚 Documentation -- [Prerequisites](#prerequisites) -- [Quick Start](#quick-start) -- [Installation](#installation) -- [Usage](#usage) -- [Basic Workflow](#basic-workflow) -- [Configuration](#configuration) -- [GitMCP Integration](#gitmcp-integration) -- [Repomix Integration](#repomix-integration) -- [Directory Structure](#directory-structure) -- [Version History](#version-history) -- [Contributing](#contributing) -- [Troubleshooting](#troubleshooting) -- [License](#license) +| Guide | Description | +| :---------------------------------------------- | :-------------------------------------------- | +| **[Setup Guide](docs/guides/setup.md)** | Installation, prerequisites, and quick start. | +| **[User Guide](docs/guides/usage.md)** | Basic workflows, Repomix, and TUI usage. | +| **[Contributing](docs/guides/contributing.md)** | How to backup, test, and submit PRs. | +| **[Troubleshooting](TROUBLESHOOTING.md)** | Solutions for common installation issues. | ---- - -## 🔧 Prerequisites - -| Requirement | Version | Installation | -| ---------------- | ------- | ---------------------------------------------------------------------- | -| **Jujutsu (jj)** | 0.23.0+ | `brew install jj` or [build from source](https://github.com/jj-vcs/jj) | -| **Git** | 2.40+ | `brew install git` | -| **Bash** | 4.0+ | Pre-installed on macOS/Linux | -| **Make** | 3.81+ | Pre-installed on macOS/Linux | +### ⚙️ Reference -**Optional:** - -- [jj-fzf](https://github.com/Cretezy/jj-fzf) -- [lazyjj](https://github.com/Cretezy/lazyjj) -- [gg](https://github.com/gulbanana/gg) -- [micro editor](https://micro-editor.github.io/) +- **[Aliases](docs/reference/aliases.md)**: Full list of custom commands. +- **[Configuration](config.toml)**: Main configuration file (v1.1.0). +- **[Tasks & Roadmap](TASKS.md)**: Project status and future plans. +- **[Version History](backups/VERSION_HISTORY.md)**: Changelog and release notes. --- ## 🚀 Quick Start -For a fast setup, see [QUICKSTART.md](QUICKSTART.md). +For a fast setup, see the **[Setup Guide](docs/guides/setup.md)**. ```bash # Clone and deploy @@ -72,243 +51,35 @@ make deploy # Verify jj config list user - -# Initialize new project with GitMCP -mkdir my-project && cd my-project -jj init -``` - ---- - -## 📝 Installation - -```bash -# Symlink deployment -make deploy -# Backup is automatic; for manual backup: -cp -r ~/.config/jj ~/.config/jj.backup-$(date +%Y%m%d-%H%M%S) -# Verify: -jj config list user -``` - ---- - -## 💡 Usage - -### Basic Commands - -```bash -jj init # Initialize repo (with GitMCP) -jj st # Status -jj ll # Log last 20 commits -jj d # Diff -jj ci # Commit interactively -jj push # Push bookmarks -jj sync # Sync remotes -# Launch TUIs -jj fzf # jj-fzf -jj tui # lazyjj -jj ui # gg ``` -More aliases, advanced workflows, and troubleshooting: see [`aliases/README.md`](aliases/README.md). - ---- - -## 🔁 Basic Workflow - -```bash -# 1. Start working -jj new - -# 2. Make changes -echo "Some content" >> file.txt - -# 3. Check what changed -jj st -jj d - -# 4. Describe your change -jj describe -m "feat: add new feature" - -# 5. Push to remote -jj push -``` - ---- - -## ⚙️ Configuration - -Main config: `config.toml` (v1.1.0-mcp-integration) - -Sections include: - -- `[user]` name and email -- `[ui]` editor, pager, colors -- `[git]` integration settings -- `[templates]` log and show templates -- `[revset-aliases]` custom commit queries - -Reference documentation: - -- [`aliases/README.md`](aliases/README.md) for command aliases and workflow scripts -- [`revsets/README.md`](revsets/README.md) for revset language and practical queries -- [`ui-configs/README.md`](ui-configs/README.md) for UI, color, and diff/pager settings -- [`git-configs/README.md`](git-configs/README.md) for extra Git integration and multiple remote configuration -- [`template-configs/README.md`](template-configs/README.md) for output formatting and template aliasing -- [`revsets-config/README.md`](revsets-config/README.md) for `[revsets]` log/graph/view behaviors - -Above files have verified relevant documentation for usage and implementation. - ---- - -## 🤖 GitMCP Integration - -GitMCP provides local AI repository context for tools—no API tokens required. - -**How It Works:** - -- Git hooks (`post-commit`, `post-merge`, `post-checkout`) generate `.mcp/context.json` -- 100% local processing -- Compatible with IDEs and desktop AIs - -**Setup:** - -```bash -cat .mcp/cursor-config.json >> ~/.cursor/mcp.json # Cursor IDE -cat .mcp/claude-config.json >> ~/Library/Application\ Support/Claude/claude_desktop_config.json # Claude Desktop -``` - -MCP server URL: -`https://gitmcp.io/Thomo1318/jjConfig` - -See [MCP docs](https://gitmcp.io/docs) for details. - ---- - -## 📦 Repomix Integration - -Repomix consolidates your entire repository into a single AI-friendly file for context injection. - -**How It Works:** - -- Git hooks automatically generate `.repomix/repomix-latest.txt` after commits -- Contains full repository content optimized for AI tools -- Includes token counts and file statistics -- Automatic cleanup (keeps last 3 versions) - -**Generated Files:** - -``` -.repomix/ -├── context.json # Metadata and usage info -├── repomix-latest.txt # Symlink to latest (use this!) -├── repomix-repo-TIMESTAMP.txt # Latest generation -└── repomix-repo-TIMESTAMP.txt # Previous versions -``` - -**Usage:** - -```bash -# Copy to AI tool -cat .repomix/repomix-latest.txt | pbcopy - -# Check token count -repomix --token-count-tree 50 . - -# View file stats -wc -l .repomix/repomix-latest.txt -``` - -**Aliases:** - -```bash -jj repomix-update # Install/update hooks -jj repomix-status # Show status -jj repomix-generate # Manual generation -jj repomix-view # Open in editor -jj repomix-tokens # Show token counts -``` - -**Install repomix:** `npm install -g repomix` -See [templates/repomix-hooks/README.md](templates/repomix-hooks/README.md) for details. - --- ## 📂 Directory Structure ``` jjConfig/ -├── README.md # Main guide -├── QUICKSTART.md # 5-min setup -├── CONTRIBUTING.md # Dev guides -├── TROUBLESHOOTING.md # Issue help -├── TASKS.md # Roadmap -├── LICENSE # MIT -├── Makefile # Deploy script +├── docs/ # 📚 Centralized Documentation +│ ├── guides/ # Setup, Contributing, Usage +│ ├── reference/ # Aliases, Architecture +│ └── architecture/ # Deep dive notes ├── config.toml # Main config ├── .mcp/ # GitMCP context -│ ├── context.json -│ ├── cursor-config.json -│ ├── claude-config.json -│ └── README.md ├── .repomix/ # Repomix AI context -│ ├── context.json -│ ├── repomix-latest.txt -│ └── repomix-*.txt -├── aliases/ # Alias configs -│ ├── README.md -│ └── ... -├── revsets/ # Revset configs -│ ├── README.md -│ └── ... -├── ui-configs/ # UI configs -│ ├── README.md -│ └── ... -├── git-configs/ # Git config -│ ├── README.md -│ └── ... -├── template-configs/ # Output templates -│ ├── README.md -│ └── ... -├── revsets-config/ # Revsets section config -│ ├── README.md -│ └── ... -└── backups/ # Version history +└── aliases/, revsets/, ... # Config modules ``` --- -## 📜 Version History - -| Version | Date | Description | -| ------- | ---------- | --------------------------------- | -| v1.1.0 | 2025-11-07 | GitMCP integration, hooks, AI gen | -| v1.0.0 | 2025-11-01 | Synthwave84, aliases, references | -| v0.1.0 | 2025-11-01 | Original basic config | - -Full changelog: [`backups/VERSION_HISTORY.md`](backups/VERSION_HISTORY.md) -Roadmap: [`TASKS.md`](TASKS.md) - ---- - ## 🤝 Contributing -Contributions welcome! - -- See [`CONTRIBUTING.md`](CONTRIBUTING.md) for setup, backups, code style, PR process. - ---- - -## 🐛 Troubleshooting +Contributions are welcome! Please read the **[Contributing Guide](docs/guides/contributing.md)** for details on our "Golden Workflow" and code standards. -See [`TROUBLESHOOTING.md`](TROUBLESHOOTING.md) for common issues: +All PRs must pass: -- Installation -- Symlinks -- GitMCP hook failures -- Color scheme -- Aliases +1. **Security Checks** (GitGuardian) +2. **Linting** (Trunk.io) +3. **Validation** (Workflow tests) --- @@ -320,31 +91,6 @@ MIT License. See [LICENSE](LICENSE). ## 👤 Author -**Thomo1318** -Email: +**Thomo1318** +Email: GitHub: [@Thomo1318](https://github.com/Thomo1318) - ---- - -## 🙏 Acknowledgments - -- Jujutsu VCS -- jj Community -- GitMCP -- Synthwave84 color scheme - ---- - -## ⭐ Additional Resources - -- [jj docs](https://jj-vcs.github.io/jj/latest/) -- [jj tutorial](https://github.com/jj-vcs/jj) -- [Revset language](https://github.com/jj-vcs/jj/discussions) -- [jj Discord](https://discord.gg/dkmfj3aGQN) - -
- -⭐ Star this repo if you find it helpful! -Report bugs · Request features · Join discussions - -
diff --git a/TASKS.md b/TASKS.md index b88d7ce..75a7271 100644 --- a/TASKS.md +++ b/TASKS.md @@ -1,335 +1,74 @@ -# JJ Configuration - Pending Tasks & Future Enhancements +# JJ Configuration - Roadmap & Tasks -## Immediate Tasks +## 🚀 Immediate Roadmap -### TASK 1: Evaluate Pager Configuration - -**Priority:** Medium -**Version:** v1.1.0-pager -**Status:** Pending - -**Current:** Using `:builtin` pager -**Action:** Test in daily use, consider alternatives (delta, bat, diff-so-fancy) -**Reference:** `ui-configs/tier3-advanced-ui.toml` - -### TASK 2: Audit Trunk Configuration - -**Priority:** High -**Status:** Pending -**Action:** Investigate `trunk check` autofix behavior (caused brace corruption in shell scripts). Ensure `.trunk/trunk.yaml` is configured for safety (Gold Standard). - -### TASK 3: Documentation Overhaul +### v3.1.0 - Documentation Site **Priority:** High -**Status:** Pending -**Action:** Consolidate fragmented READMEs, fix broken links, standardize formatting, and improve navigation. -**Reference:** `documentation_audit.md` - -### TASK 4: Docs Site Generation - -**Priority:** Medium **Status:** Planned -**Action:** Evaluate and implement a static site generator (e.g., MkDocs) for project documentation. - -### TASK 5: Update Roadmap - -**Priority:** Medium -**Status:** Pending -**Action:** Review and refine the project roadmap (TASKS.md, VERSION_HISTORY.md) to ensure it reflects current priorities and completed work. - ---- - -## Future Version Tasks - -### v2.0.0-formatters - Code Formatters & Linters - -**Priority:** High -**Status:** Planned - -**Tools to Integrate:** - -- [x] Ruff (Configured in Trunk) -- [x] Prettier (Configured in Trunk) -- [x] MegaLinter (Skipped - using Trunk) -- [ ] python-lsp (Language server) -- [ ] pylint (Python linter) -- [ ] black (Python formatter) -- [ ] pyright (Python type checker) -- [x] Trunk.io (Implemented v1.2.0) - -**Configuration Section:** `[fix.tools]` -**Reference:** `ui-configs/tier3-advanced-ui.toml` - ---- - -### v3.0.0-conventional - Conventional Commits - -**Priority:** Medium -**Status:** Planned - -**Spec:** https://www.conventionalcommits.org/en/v1.0.0/ - -**Implementation:** - -- [ ] Commit message templates -- [ ] Validation hooks -- [ ] Changelog generation -- [ ] Scope definitions - -**Configuration:** `templates.draft_commit_description` - ---- - -### v4.0.0-release-automation - Release Management - -**Priority:** Medium -**Status:** Planned - -**Tool Options (Choose ONE):** - -- [ ] release-please (https://github.com/googleapis/release-please) -- [ ] semantic-release (https://github.com/semantic-release/semantic-release) -- [ ] GitVersion (https://github.com/GitTools/GitVersion) -- [ ] release-it (https://github.com/release-it/release-it) - -**Features:** - -- Automated version bumping -- Changelog generation -- GitHub release creation -- Tag management - ---- - -### v5.0.0-cicd - CI/CD Integration - -**Priority:** High -**Status:** Planned - -**Platforms:** -- [ ] GitHub Actions -- [ ] CircleCI (https://circleci.com/) -- [ ] Jenkins (https://www.jenkins.io/) +Transition static markdown files to a searchable, beautiful static site. -**Workflows:** +- [ ] Evaluate Static Site Generators (MkDocs-Material recommended) +- [ ] Set up `mkdocs.yml` configuration +- [ ] Configure GitHub Pages deployment +- [ ] Migrate existing `docs/` content +- [ ] Implement versioning selector (if needed) -- Automated testing -- Code quality checks -- Security scanning -- Deployment automation +### v3.2.0 - CI/CD Foundation ---- - -### v6.0.0-security - Security & Code Quality - -**Priority:** High +**Priority:** Medium **Status:** Planned -**Tools to Integrate:** - -- [x] GitGuardian ggshield (Implemented v1.2.0) -- [ ] Snyk (Deferred to agent rules) -- [ ] Semgrep (via Trunk) -- [ ] Trivy (via Trunk) -- [ ] SonarQube (https://www.sonarsource.com/products/sonarqube/) -- [ ] Checkmarx (https://checkmarx.com/) -- [ ] CodeScene-CE (https://codescene.com/product/codescene-for-open-source) -- [ ] Task (https://github.com/go-task/task) - -**Integration Points:** +Establish a robust Continuous Integration pipeline to enforce quality gates automatically. -- Pre-commit hooks -- CI/CD pipelines -- IDE integration -- Automated scanning +- [ ] **Linting Workflow**: Run `trunk check` on PRs +- [ ] **Security Workflow**: Run `ggshield` and `trivy` on PRs +- [ ] **Commit Workflow**: Enforce Conventional Commits (via `commitlint` or `jj` check) +- [ ] **Build Workflow**: Verify `mkdocs build` passes --- -## Task Tracking +## 🔮 Future Vision -### Completed +### v4.0.0 - Advanced Security & Insights -- [x] v0.1.0 - Original config backup -- [x] v1.0.0 - Optimized configuration with Synthwave84 +**Priority:** Low +**Status:** backlog -### In Progress - -- [ ] v1.1.0 - Pager evaluation - -### Planned - -- [x] v2.0.0 - Code formatters (Trunk.io integrated) -- [ ] v3.0.0 - Conventional commits -- [ ] v4.0.0 - Release automation -- [ ] v5.0.0 - CI/CD integration -- [x] v6.0.0 - Security tools (Partially Implemented v1.2.0) +- [ ] Snyk Integration (Vulnerability scanning) +- [ ] SonarQube / CodeScene (Code health metrics) +- [ ] SBOM Generation --- -## Notes - -- All tier2/tier3 reference files created and ready for implementation -- 21 reference files across 6 directories -- SemVer backup structure in place -- Configuration tested and working - ---- - -## TODO Items - -### TODO 1: Assess Raycast AI MCP Integration - -**Priority:** Medium -**Version:** TBD -**Status:** Research needed - -**Question:** Can Raycast AI automatically use `.mcp/context.json` files for repo context? - -**Action Items:** - -- [ ] Check Raycast AI documentation for MCP support -- [ ] Test if Raycast AI can read local `.mcp/` files -- [ ] Determine if manual configuration needed -- [ ] If not supported: Create workaround (e.g., prompt templates) -- [ ] If supported: Document configuration steps - -**Current State:** - -- GitMCP integration creates `.mcp/context.json` locally -- Works with Cursor IDE, Claude Desktop (confirmed) -- Raycast AI compatibility: **UNKNOWN** - -**Fallback:** - -- Use context files as reference in prompts -- Copy `.mcp/README.md` content when needed -- Use MCP-compatible tools (Cursor, Claude) for AI-assisted development - -**Reference:** - -- GitMCP article: https://medium.com/the-context-layer/stop-letting-ai-guess-your-code-instantly-make-every-github-repo-ai-savvy-with-this-one-liner-cc23e00c9ea2 -- Raycast AI docs: https://developers.raycast.com/ - ---- - -## GitHub Integration TODO - -### TODO 4: GitHub CLI Integration with Interactive Prompts - -**Priority:** High -**Version:** v1.1.1-gh-integration -**Status:** ✅ Implemented - -**Purpose:** Streamline GitHub repo creation from jj - -**Implementation:** External script approach (recommended in Task4.md analysis) - -**Features Implemented:** - -- [x] Interactive repo creation with prompts -- [x] Auto-generate description from repo content (README.md, package.json, pyproject.toml, Cargo.toml) -- [x] Choose public/private visibility -- [x] Dynamic GitHub username detection (no hardcoding) -- [x] Input validation and error handling -- [x] Dependency checking (gh, jj, git) -- [x] All-in-one init-github workflow -- [x] Clone and initialize workflow -- [x] Colored output and better UX -- [ ] Automatic commit signing (deferred to v1.2.0-security) - -**Implemented Solution:** - -**File Structure:** - -``` -~/.config/jj/ -├── scripts/ -│ ├── gh-helper.sh # Main helper script -│ └── README.md # Documentation -└── config.toml # JJ config with aliases -``` - -**Aliases (in config.toml):** - -```toml -[aliases] -# GitHub integration (uses external script for better UX) -gh-create = ["util", "exec", "--", "bash", "-c", "~/.config/jj/scripts/gh-helper.sh create"] -init-github = ["util", "exec", "--", "bash", "-c", "~/.config/jj/scripts/gh-helper.sh init-github"] -gh-clone = ["util", "exec", "--", "bash", "-c", "~/.config/jj/scripts/gh-helper.sh clone \"$@\"", "--"] -``` - -**Usage Examples:** - -```bash -# Create a new GitHub repo (interactive) -jj gh-create - -# Initialize jj repo and create GitHub repo (all-in-one) -jj init-github - -# Clone and initialize with jj -jj gh-clone owner/repo -jj gh-clone https://github.com/owner/repo -``` - -**Key Improvements Over Original Plan:** - -| Feature | Original Plan | Implemented Solution | -| --------------- | -------------------------- | ----------------------------------------- | -| Error Handling | Minimal (`set -e`) | Comprehensive validation | -| Username | Hardcoded "Thomo1318" | Dynamic via `gh api user` | -| Description | Basic README check | Multi-source (README, package.json, etc.) | -| Maintainability | Inline bash (hard to edit) | Separate script file | -| UX | Plain text | Colored output, progress indicators | -| Testing | Difficult | Easy to test independently | -| Dependencies | No checking | Validates gh, jj, git, auth status | - -**Installation Steps:** +## ✅ Completed Tasks (Archive) -```bash -# 1. Create scripts directory -mkdir -p ~/.config/jj/scripts +### v3.0.0 - Conventional Commits & Quality -# 2. Copy gh-helper.sh script -cp ~/.config/jj/scripts/gh-helper.sh ~/.config/jj/scripts/ -chmod +x ~/.config/jj/scripts/gh-helper.sh +**Released:** 2026-01-02 -# 3. Update config.toml with new aliases (already done) +- [x] **Conventional Commits**: Implemented `jj` template & validation. +- [x] **Trunk Optimization**: Enabled `ruff`, `codespell`, `trivy`. +- [x] **Release Automation**: Integrated `git-semver` for auto-versioning. -# 4. Test the script -~/.config/jj/scripts/gh-helper.sh help +### v1.2.0 - Security Hardening -# 5. Ensure gh is authenticated -gh auth status || gh auth login -``` +**Released:** 2026-01-01 -**Testing Results:** +- [x] **GitGuardian**: `pre-push` hooks for secret scanning. +- [x] **Sanitization**: `sanitize_email.py` for PII protection. -- ✅ Help command works -- ✅ Script is executable -- ✅ All dependencies available (gh, jj, git) -- ✅ Invalid command handling works -- ✅ Auto-description generation works -- ⚠️ Interactive tests require GitHub authentication +### v1.1.0 - UI Enhancements -**Commit Signing Integration:** +**Released:** 2026-01-02 -**Note:** Commit signing moved to v1.2.0-security for proper implementation -with key management and testing. +- [x] **Pager**: Configured `delta` for rich diffs. +- [x] **Documentation**: Overhauled structure into `docs/` directory. -```toml -[signing] -sign-all = true -backend = "ssh" -key = "~/.ssh/id_ed25519" -``` +### v1.0.0 - Initial Optimization -**Reference:** +**Released:** 2025-11-01 -- GitHub CLI: https://cli.github.com/ -- SSH signing: https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification -- jj signing docs: https://jj-vcs.github.io/jj/latest/config/#signing -- Bash best practices: https://google.github.io/styleguide/shellguide.html -- Task4.md analysis: Comprehensive evaluation of implementation approaches +- [x] **Synthwave84**: Custom color scheme. +- [x] **Aliases**: Core `jj` workflow aliases. diff --git a/backups/VERSION_HISTORY.md b/backups/VERSION_HISTORY.md index 017985c..61ac169 100644 --- a/backups/VERSION_HISTORY.md +++ b/backups/VERSION_HISTORY.md @@ -14,6 +14,18 @@ --- +## v1.2.1-docs (2026-01-01) + +**Location:** `backups/v1.2.1-docs/` (TBD) +**Status:** Released +**Description:** Documentation Overhaul and centralisation. + +**Key Features:** + +- **Centralized Docs**: New `docs/` directory with `guides/`, `reference/`, `architecture/`. +- **Navigation Hub**: Root `README.md` simplified to point to sub-docs. +- **Workflow Guides**: Explicit "Gold Standard" contribution workflow documentation. + ## v1.2.0-security (2026-01-01) **Location:** `backups/v1.2.0-security/` (TBD) @@ -28,6 +40,19 @@ - **Workflow**: Automated `/publish-change` agent workflow - **Automation**: `sanitize_email.py` auto-discovery +## v3.0.0-conventional (2026-01-02) + +**Location:** `backups/v3.0.0-conventional/` +**Status:** Released +**Description:** Implemented Conventional Commits and optimized Trunk configuration. + +**Key Features:** + +- **Conventional Commits**: `jj describe` template (Gold Standard). +- **Trunk Optimization**: Added `ruff` (Python), `codespell` (Typos), and `trivy` (Security). +- **UI**: Upgrade pager to `delta` for rich diffs. +- **Documentation**: Updated `usage.md` and `CONTRIBUTING.md`. + --- ## v1.0.0-optimized (2025-11-01) ← CURRENT diff --git a/commitlint.config.js b/commitlint.config.js new file mode 100644 index 0000000..69b4242 --- /dev/null +++ b/commitlint.config.js @@ -0,0 +1,3 @@ +module.exports = { + extends: ["@commitlint/config-conventional"], +}; diff --git a/config.toml b/config.toml index 697eefa..4fde65c 100644 --- a/config.toml +++ b/config.toml @@ -25,7 +25,10 @@ editor = "micro" diff-editor = "jj-fzf" diff-formatter = ":color-words" graph.style = "curved" -pager = ":builtin" +# Use delta for diffs (Gold Standard) +pager = ["delta", "--dark", "--paging=always", "--line-numbers", "--navigate"] +# Default Pager (Fallback) +# pager = ":builtin" log-word-wrap = true default-command = ["log"] color = "always" @@ -49,6 +52,14 @@ log = "builtin_log_comfortable" show = "builtin_log_detailed" op_log = "builtin_op_log_comfortable" git_push_bookmark = '"Thomo1318/push-" ++ change_id.short()' +draft_commit_description = ''' +concat( + description, + "\n", + "# (): \n", + "# Types: feat, fix, docs, style, refactor, perf, test, chore\n", +) +''' # Template Aliases [template-aliases] @@ -345,33 +356,60 @@ fi ''', ] # Generate repomix file manually -repomix-generate = ["util", "exec", "--", "bash", "-c", ''' +repomix-generate = [ + "util", + "exec", + "--", + "bash", + "-c", + ''' if command -v repomix &> /dev/null; then .git/hooks/post-commit-repomix echo "✓ Repomix file generated" else echo "⚠️ repomix not installed. Install with: npm install -g repomix" fi -'''] +''' +] # View latest repomix file -repomix-view = ["util", "exec", "--", "bash", "-c", ''' +repomix-view = [ + "util", + "exec", + "--", + "bash", + "-c", + ''' if [ -f .repomix/repomix-latest.txt ]; then ${EDITOR:-micro} .repomix/repomix-latest.txt else echo "No repomix file found. Run: jj repomix-generate" fi -'''] +''' +] # Show token counts -repomix-tokens = ["util", "exec", "--", "bash", "-c", ''' +repomix-tokens = [ + "util", + "exec", + "--", + "bash", + "-c", + ''' if command -v repomix &> /dev/null; then repomix --token-count-tree 50 . else echo "⚠️ repomix not installed. Install with: npm install -g repomix" fi -'''] +''' +] # Security Integration (v1.2.0) # Install/update security hooks -security-update = ["util", "exec", "--", "bash", "-c", ''' +security-update = [ + "util", + "exec", + "--", + "bash", + "-c", + ''' set -e echo "Installing security hooks..." @@ -388,7 +426,8 @@ echo " - Sensitive credentials (future)" echo "" echo "To sanitize existing files:" echo " python3 .build-artifacts/sanitize_email.py" -'''] +''' +] # Check for sensitive information security-check = [ "util", @@ -418,14 +457,53 @@ fi ''', ] # Sanitize email addresses -security-sanitize = ["util", "exec", "--", "bash", "-c", ''' +security-sanitize = [ + "util", + "exec", + "--", + "bash", + "-c", + ''' if [ -f .build-artifacts/sanitize_email.py ]; then python3 .build-artifacts/sanitize_email.py else echo "⚠️ Sanitization script not found" echo " Expected: .build-artifacts/sanitize_email.py" fi -'''] +''' +] +# Versioning (git-semver) +semver = ["util", "exec", "--", "git-semver", "-match", "v*"] +next-patch = [ + "util", + "exec", + "--", + "git-semver", + "-target", + "patch", + "-match", + "v*" +] +next-minor = [ + "util", + "exec", + "--", + "git-semver", + "-target", + "minor", + "-match", + "v*" +] +next-major = [ + "util", + "exec", + "--", + "git-semver", + "-target", + "major", + "-match", + "v*" +] # Synthwave84 Color Scheme [colors] diff --git a/docs/architecture/audit-log.md b/docs/architecture/audit-log.md new file mode 100644 index 0000000..e58e40a --- /dev/null +++ b/docs/architecture/audit-log.md @@ -0,0 +1,68 @@ +# Documentation Audit & Improvement Plan + +## 1. Executive Summary + +The current documentation is **functional but fragmented**. While the root `README.md` and newly updated `CONTRIBUTING.md` are high-quality, relevant technical details are scattered across 10+ sub-directory READMEs. This "folder-per-topic" structure hurts discoverability. Additionally, `aliases/README.md` contains outdated status information ("NOT YET CREATED" for files that exist). + +## 2. Issues Identified + +### A. Fragmentation (Too Many READMEs) + +The project attempts to document each config section in its own folder. This leads to deep nesting: + +- `git-configs/README.md` +- `ui-configs/README.md` +- `revsets/README.md` +- `revsets-config/README.md` +- `template-configs/README.md` +- ...and 5 more. + +**Impact**: Users can't generic "search" the docs easily. "How do I configure colors?" requires navigating to `ui-configs/README.md`. + +### B. Outdated Content + +- **`aliases/README.md`**: Lists "Starter aliases" as "Missing/Not Yet Created", but `config.toml` clearly implements them. It references "Status: CREATED" for files that are likely part of the main config now. +- **`QUICKSTART.md`**: Need to verify if this aligns with the new "Golden Workflow". + +### C. Styling Inconsistencies + +- Some files use `## Header` while others (likely the older sub-readmes) might use inconsistent specific formatting. +- `README.md` uses "Synthwave" emoji style (good), but deep docs are dry. + +### D. Table of Contents + +- `README.md` has a decent ToC. +- `CONTRIBUTING.md` has a ToC. +- Sub-READMEs lack navigation back to root. + +## 3. Proposed Improvement Plan (Zero Code Changes) + +### Phase 1: Consolidation (The "Big Merge") + +Instead of hidden READMEs, we should consolidate them into a centralized `docs/` folder or merge them into few, high-impact guides. + +**Recommendation**: + +1. **Create `docs/` directory**. +2. **Move & Rename**: + - `ui-configs/README.md` -> `docs/configuration-ui.md` + - `git-configs/README.md` -> `docs/configuration-git.md` + - `revsets/README.md` -> `docs/configuration-revsets.md` + - `aliases/README.md` -> `docs/configuration-aliases.md` +3. **Update `README.md`**: replace deep links with links to `docs/*.md`. + +### Phase 2: Updating Content + +1. **Refactor `docs/configuration-aliases.md`**: Remove "Status" columns. Just list the aliases available in `config.toml`. +2. **Verify `QUICKSTART.md`**: Ensure it mentions `trunk setup` or `jj security-sanitize` if applicable (or keep it simple for new users). + +### Phase 3: Navigation & Style + +1. Add specific **"Back to Main README"** link at the top of every doc. +2. Add a **"Quick Links"** header to every doc: `[Usage] | [Config] | [Contributing]`. + +## 4. Immediate Action Items (Next Phase) + +1. Verify content of `QUICKSTART.md`. +2. Verify `ui-configs/README.md` content to see if it's worth keeping or merging. +3. **Present this plan to user**. diff --git a/Task4.md b/docs/architecture/gh-cli-analysis.md similarity index 100% rename from Task4.md rename to docs/architecture/gh-cli-analysis.md diff --git a/IMPLEMENTATION.md b/docs/architecture/gh-cli-integration.md similarity index 100% rename from IMPLEMENTATION.md rename to docs/architecture/gh-cli-integration.md diff --git a/CONTRIBUTING.md b/docs/guides/contributing.md similarity index 83% rename from CONTRIBUTING.md rename to docs/guides/contributing.md index 7a9d17b..f41e7dc 100644 --- a/CONTRIBUTING.md +++ b/docs/guides/contributing.md @@ -43,7 +43,7 @@ Follow this "Inner Loop" to ensure quality and security: > **Goal**: Get the code working and documented locally. 1. **Code**: `micro config.toml` (Edit your files) 2. **Test**: `make test` or `trunk check` (Verify immediately) -3. **Docs**: Update `README.md` or `alias/*.md` **in parallel** with code changes. +3. **Docs**: Update `../../README.md` or `../reference/aliases.md` **in parallel** with code changes. 4. *Repeat until tests pass and docs match code.* #### 2. Quality Assurance @@ -66,8 +66,8 @@ Follow this "Inner Loop" to ensure quality and security: ### Adding New Features 1. Create reference file in appropriate directory 2. Add to README in that directory -3. Update main README if user-facing -4. Add to TASKS.md if part of roadmap +3. Update main [README](../../README.md) if user-facing +4. Add to [TASKS.md](../../TASKS.md) if part of roadmap 🧪 Testing Changes Syntax Validation 
# Test configuration syntax @@ -100,7 +100,7 @@ When releasing a new version: 
# Create version backup mkdir -p backups/v1.X.Y-description cp config.toml backups/v1.X.Y-description/ -
Update ⁠backups/VERSION_HISTORY.md with: +
Update [backups/VERSION_HISTORY.md](../../backups/VERSION_HISTORY.md) with: • Version number
 • Date
 • Description
 • Breaking changes
 • New features 🔢 Version Numbering We follow Semantic Versioning: @@ -121,9 +121,25 @@ jj describe -m "feat: add new feature" # Push to your fork jj push 
2. Create Pull Request - • Title: Use conventional commit format - ▪ ⁠feat: - New feature
 ▪ ⁠fix: - Bug fix
 ▪ ⁠docs: - Documentation only
 ▪ ⁠style: - Formatting, no code change
 ▪ ⁠refactor: - Code restructuring
 ▪ ⁠test: - Adding tests
 ▪ ⁠chore: - Maintenance tasks
 • Description: Include: - ▪ What changed
 ▪ Why it changed
 ▪ How to test
 ▪ Related issues + * **Title**: MUST use [Conventional Commits](https://www.conventionalcommits.org/) format. + * **Format**: `(): ` + + | Type | Description | + | :--- | :--- | + | `feat` | New feature | + | `fix` | Bug fix | + | `docs` | Documentation only | + | `style` | Formatting, no code change | + | `refactor` | Code restructuring | + | `perf` | Performance improvement | + | `test` | Adding missing tests | + | `chore` | Maintenance tasks | + + * **Description**: Include: + * What changed + * Why it changed + * How to test + * Related issues 3. Review Process • Maintainer will review within 7 days
 • Address any feedback
 • Once approved, changes will be merged 📝 Code Style @@ -174,7 +190,9 @@ echo "Hello" \`\`\` 
🐛 Reporting Issues Before Creating an Issue - 1. Check existing issues
 2. Review TROUBLESHOOTING.md
 3. Test with latest version + 1. Check existing issues + 2. Review [TROUBLESHOOTING.md](../../TROUBLESHOOTING.md) + 3. Test with latest version Issue Template 
**Description** Clear description of the issue diff --git a/QUICKSTART.md b/docs/guides/setup.md similarity index 76% rename from QUICKSTART.md rename to docs/guides/setup.md index 7c8a4b0..0056c72 100644 --- a/QUICKSTART.md +++ b/docs/guides/setup.md @@ -111,9 +111,17 @@ jj tui # Alternative UI (gg) jj ui 
Next Steps - • Read the full README: README.md
 • Explore aliases: aliases/README.md
 • Learn revsets: revsets/README.md
 • Customize colors: ui-configs/README.md
 • Official tutorial: https://jj-vcs.github.io/jj/latest/tutorial/ + • Read the full README: [README.md](../../README.md) + • Explore aliases: [Aliases Reference](../reference/aliases.md) + • Learn revsets: [revsets/README.md](../../revsets/README.md) + • Customize colors: [ui-configs/README.md](../../ui-configs/README.md) + • Official tutorial: https://jj-vcs.github.io/jj/latest/tutorial/ + Need Help? - • Troubleshooting: TROUBLESHOOTING.md
 • Contributing: CONTRIBUTING.md
 • Issues: https://github.com/Thomo1318/jjConfig/issues
 • jj Discord: https://discord.gg/dkmfj3aGQN + • Troubleshooting: [TROUBLESHOOTING.md](../../TROUBLESHOOTING.md) + • Contributing: [CONTRIBUTING.md](contributing.md) + • Issues: https://github.com/Thomo1318/jjConfig/issues + • jj Discord: https://discord.gg/dkmfj3aGQN Happy hacking! 🎉 
 --- diff --git a/docs/guides/usage.md b/docs/guides/usage.md new file mode 100644 index 0000000..64e2a3e --- /dev/null +++ b/docs/guides/usage.md @@ -0,0 +1,156 @@ +# User Guide + +This guide covers basic usage, workflows, and advanced integrations for `jjConfig`. + +--- + +## 🔁 Basic Workflow + +```bash +# 1. Start working +jj new + +# 2. Make changes +echo "Some content" >> file.txt + +# 3. Check what changed +jj st +jj d + +# 4. Describe your change +jj describe -m "feat: add new feature" + +# 5. Push to remote +jj push +``` + +--- + +## 💡 Common Commands + +```bash +jj init # Initialize repo (with GitMCP) +jj st # Status +jj ll # Log last 20 commits +jj d # Diff +jj ci # Commit interactively +jj push # Push bookmarks +jj sync # Sync remotes +``` + +### TUI Tools + +- `jj fzf`: Launch jj-fzf +- `jj tui`: Launch lazyjj +- `jj ui`: Launch gg + +--- + +## 🤖 GitMCP Integration + +GitMCP provides local AI repository context for tools—no API tokens required. + +**How It Works:** + +- Git hooks (`post-commit`, `post-merge`, `post-checkout`) generate `.mcp/context.json` +- 100% local processing +- Compatible with IDEs and desktop AIs + +**Setup:** + +```bash +cat .mcp/cursor-config.json >> ~/.cursor/mcp.json # Cursor IDE +cat .mcp/claude-config.json >> ~/Library/Application\ Support/Claude/claude_desktop_config.json # Claude Desktop +``` + +**MCP server URL:** `https://gitmcp.io/Thomo1318/jjConfig` +See [MCP docs](https://gitmcp.io/docs) for details. + +--- + +## 📦 Repomix Integration + +Repomix consolidates your entire repository into a single AI-friendly file for context injection. + +**How It Works:** + +- Git hooks automatically generate `.repomix/repomix-latest.txt` after commits +- Contains full repository content optimized for AI tools +- Includes token counts and file statistics + +**Generated Files in `.repomix/`:** + +- `context.json`: Metadata +- `repomix-latest.txt`: Symlink to latest (use this!) + +**Usage:** + +```bash +# Copy to AI tool +cat .repomix/repomix-latest.txt | pbcopy + +# Check token count +repomix --token-count-tree 50 . + +# Show status +jj repomix-status +``` + +--- + +## 🏷️ Versioning (Automated) + +We use `git-semver` to automatically calculate the next version based on Conventional Commits and tags. + +### Aliases + +| Command | Description | Example Output | +| :-------------- | :---------------------- | :------------- | +| `jj semver` | Show current version | `v1.2.0` | +| `jj next-patch` | Show next patch version | `v1.2.1` | +| `jj next-minor` | Show next minor version | `v1.3.0` | +| `jj next-major` | Show next major version | `v2.0.0` | + +### Release Workflow + +```bash +# create a release with the correct version +gh release create $(jj next-minor) --generate-notes +``` + +--- + +## 🏷️ Versioning (Automated) + +We use `git-semver` to automatically calculate the next version based on Conventional Commits and tags. + +### Composing Commits + +When you run `jj describe`, `jjConfig` provides a strict template to help you follow [Conventional Commits](https://www.conventionalcommits.org/): + +``` +# (): +# Types: feat, fix, docs, style, refactor, perf, test, chore +``` + +### Aliases + +| Command | Description | Example Output | +| :-------------- | :---------------------- | :------------- | +| `jj semver` | Show current version | `v1.2.0` | +| `jj next-patch` | Show next patch version | `v1.2.1` | +| `jj next-minor` | Show next minor version | `v1.3.0` | +| `jj next-major` | Show next major version | `v2.0.0` | + +### Release Workflow + +```bash +# create a release with the correct version +gh release create $(jj next-minor) --generate-notes +``` + +--- + +## 🔧 Troubleshooting + +See [TROUBLESHOOTING.md](../../TROUBLESHOOTING.md) for solutions to common install issues. diff --git a/aliases/README.md b/docs/reference/aliases.md similarity index 100% rename from aliases/README.md rename to docs/reference/aliases.md