Skip to content

README.org

Latest commit

 

History

History
514 lines (384 loc) · 15 KB

README.org

File metadata and controls

514 lines (384 loc) · 15 KB
Raw

Developer Tools

Overview

Collection of developer tools and utilities for improving development workflow, code quality, and productivity. These tools help automate common development tasks, enforce code standards, and streamline collaboration.

Quick Navigation

Tools

Build & Testing Tools

Code Quality Tools

devcheck

Automated formatter and linter runner that detects repository context and runs appropriate quality checks. Prioritizes Bazel or Make when those targets exist, otherwise language-specific tools, and prints LLM-friendly output.

Key Features:

  • Automatic detection of project type and build system
  • Unified interface for formatters, linters, and tests
  • Human-readable output optimized for AI agent consumption
  • Zero-configuration operation for standard layouts
  • --dry-run, --filter, --format, --changed-only, --force-fallback

Installation:

go install github.com/jaeyeom/experimental/devtools/devcheck/cmd/devcheck@latest

Usage:

devcheck                    # Run format, lint, and test
devcheck --filter=format    # Run only formatters
devcheck --dry-run          # Preview what would be executed

→ Full Documentation

docsync

Matcher CLI that maps changed files to the docs they likely stale. Judgment (is the doc actually stale, and how to fix it) stays with the human or LLM; the tool only reports which docs a change implicated.

Key Features:

  • Curated docsync.yml glob map from code paths to shadowed docs
  • check against git diff or an explicit file list
  • validate lints the mapping (schema, globs, missing docs)
  • Human-readable and JSON output with CI-friendly exit codes

Installation:

go install github.com/jaeyeom/experimental/devtools/docsync/cmd/docsync@latest

Usage:

docsync check --base main
docsync check --files internal/auth/token.go --json
docsync validate

→ Full Documentation

linters

Collection of linting tools for various file formats, including org-lint for Org-mode files and a Go linter for unnecessary interface assertions.

Available Linters:

  • org-lint: Go wrapper around Emacs org-lint for Org-mode files
  • unnecessary-interface-assertion-linter: flags `var _ Iface = (*T)(nil)` when the interface is otherwise unused

Installation:

go install github.com/jaeyeom/experimental/devtools/linters/cmd/org-lint@latest

Usage:

org-lint README.org file1.org file2.org

→ Full Documentation

Development Utilities

ascii-art

Tools for generating GANTT charts and graphs as ASCII art for embedding in code comments and documentation. Makes test cases, timelines, and complex logic more understandable through visual representations.

Note: Design and requirements documented, but implementation not yet started.

Key Features:

  • GANTT chart generator for timeline visualizations
  • Graph visualizer for node and edge diagrams
  • Configurable comment prefixes and characters
  • Multiple layout algorithms

Installation:

bazel build //devtools/ascii-art/cmd/gantt-chart:gantt-chart
bazel build //devtools/ascii-art/cmd/graph-viz:graph-viz

Usage:

gantt-chart --time-unit=1s --task="Task_A,0s,10s,#,Priority: HIGH"
graph-viz --layout=grid --node="A,0,0" --edge="A,B"

→ Full Documentation

gh-nudge

Suite of GitHub workflow utilities including PR review reminders, Slack integration, merge automation, CODEOWNERS management, and storage utilities.

Available Commands:

  • gh-nudge: Send review reminders for pending PRs
  • gh-slack: Slack notifications for GitHub events
  • gh-merge: Automated PR merging with checks
  • gh-codeowners: CODEOWNERS file management
  • gh-pr-review: PR review workflow automation
  • gh-storage: GitHub storage management utilities

Installation:

go install github.com/jaeyeom/experimental/devtools/gh-nudge/cmd/gh-nudge@latest
go install github.com/jaeyeom/experimental/devtools/gh-nudge/cmd/gh-slack@latest
# ... install other commands as needed

Prerequisites:

  • GitHub CLI (gh) installed and authenticated
  • Slack API token (for slack integration)

→ Full Documentation

rename-jira-keys

Tool for renaming Jira ticket keys across documentation files. Performs content replacement and file renaming to keep documentation in sync when tickets are moved or renumbered.

Key Features:

  • Word boundary matching to prevent partial matches
  • File existence checks to prevent overwrites
  • Updates both file contents and filenames
  • Clear feedback on which files were modified

Installation:

go install github.com/jaeyeom/experimental/devtools/rename-jira-keys/cmd/rename-jira-keys@latest

Usage:

rename-jira-keys --old PROJ-123 --new PROJ-456
rename-jira-keys --old DEV-400 --new DEV-900 -p plan.md -d docs/tickets

→ Full Documentation

claude-usage

CLI for Claude Code 5-hour and 7-day rate-limit usage windows. Resolves OAuth credentials from the macOS Keychain (or legacy credentials file) and queries Anthropic’s OAuth usage API. No claude-hud plugin install required.

Key Features:

  • Human table and stable --json output
  • Standalone credential resolution (Keychain + file fallback)
  • Token never printed; read-only use of existing Claude Code login

Installation:

go install github.com/jaeyeom/experimental/devtools/claude-usage/cmd/claude-usage@latest

Usage:

claude-usage          # human-readable table
claude-usage --json   # stable JSON

→ Full Documentation

magit

Shell wrapper that opens magit-status in a running Emacs via emacsclient. Reuses an existing Magit buffer/perspective for the repository when one exists; otherwise opens Magit (perspective 1 when persp-mode is available). Does not start Emacs.

Key Features:

  • Open Magit for $PWD or an explicit directory from any terminal
  • -c new graphical frame; -t terminal frame in the current tty
  • Perspective-aware reuse of an existing Magit session
  • Canonical-path matching so repos that share a leaf name do not collide

Installation:

cd devtools/setup-dev/ansible
./ensure.sh magit

Usage:

magit                 # magit-status for $PWD
magit -c              # new graphical frame
magit -t              # terminal frame in this tty
magit /path/to/repo   # magit-status for that directory

→ Full Documentation

prsync

Surveys the author’s open GitHub PRs, matches them to running herdr agent tabs, and on request dispatches a prompt to address review comments or rebase. tabs --orphans finds live-agent tabs whose PR already merged.

Key Features:

  • JSON CLI: scan, tabs --orphans, dispatch, comment, gate, logs, version
  • Dry-run by default; --go sends or closes
  • Append-only JSONL run logs under $XDG_STATE_HOME/prsync/ (prsync logs)
  • Shells out to authenticated gh and herdr ≥ 0.8; never embeds a token

Installation:

go install github.com/jaeyeom/experimental/devtools/prsync/cmd/prsync@latest

→ Full Documentation

reviewpush

Codex reviews local commits read-only; the wrapper validates the result and performs git push. Codex never edits code or pushes.

Key Features:

  • Oldest-ahead commit loop until HEAD matches the remote base
  • PUSH vs BLOCKED Codex contract; wrapper performs git push
  • --repo, --base, --max-iterations, --output

Installation:

go install github.com/jaeyeom/experimental/devtools/reviewpush/cmd/review-and-push-loop@latest

→ Full Documentation

Configuration & Setup

setup-dev

Ansible playbooks for automated development environment setup with idempotent, modular installation of tools and configurations.

Key Features:

  • Idempotent Ansible playbooks for each tool
  • Cross-platform support (Linux, macOS, Termux)
  • Modular installation of individual tools
  • Complete development environment setup

Installation:

cd devtools/setup-dev/ansible
./ensure.sh all

→ Full Documentation

repo-sync

Multi-machine development file synchronization using Git-based workflow automation. Selectively synchronizes project-specific files across machines without uploading entire repositories.

Note: Exploring copier templates as a potentially better solution for managing project-specific configurations.

Key Features:

  • Selective synchronization using rsync patterns
  • Git integration with automated commit-pull-push
  • Multi-machine coordination with deletion tracking
  • SQLite database for metadata and operation history

Installation:

bazel build //devtools/repo-sync/cmd/repo-sync:repo-sync
# or use make from devtools/repo-sync directory

Usage:

repo-sync init
repo-sync config add-project myproject --local-dir /path/to/project
repo-sync sync myproject

→ Full Documentation

Installation

Prerequisites

Required

  • Go 1.21+ - For Go-based tools (most tools in this directory)
  • Git - Version control and some tool dependencies

Optional (tool-specific)

  • Bazel - For tools with Bazel build configuration
  • Emacs - For org-lint, the magit CLI, and other Emacs-related tools
  • GitHub CLI (gh) - For gh-nudge utilities
  • Ansible - For setup-dev automation
  • rsync - For repo-sync file synchronization

Common Installation Pattern

Most Go-based tools follow this pattern:

# Install from GitHub (recommended)
go install github.com/jaeyeom/experimental/devtools/<tool-name>/cmd/<tool-name>@latest

# Or install from source
cd devtools/<tool-name>
go install ./cmd/<tool-name>

# Or build with Bazel
bazel build //devtools/<tool-name>/...

Installing All Tools

# Install individual Go-based tools
go install github.com/jaeyeom/experimental/devtools/devcheck/cmd/...@latest
go install github.com/jaeyeom/experimental/devtools/rename-jira-keys/cmd/...@latest

# Install linters
go install github.com/jaeyeom/experimental/devtools/linters/cmd/...@latest

# Install all gh-nudge suite tools
go install github.com/jaeyeom/experimental/devtools/gh-nudge/cmd/...@latest

Contributing

Adding New Tools

  1. Create tool directory under devtools/
  2. Follow project structure conventions: 
    devtools/<tool-name>/
├── cmd/<tool-name>/     # Main entry point
│   └── main.go
├── internal/            # Internal packages
├── BUILD.bazel          # Bazel configuration
├── go.mod               # Go module file (if applicable)
└── README.org           # Tool documentation
  3. Write comprehensive README with:
    • Clear overview and problem statement
    • Installation instructions
    • Usage examples
    • Key features
    • Prerequisites
  4. Add entry to this main README under appropriate category

Documentation Standards

  • Use Org-mode format (.org files) for consistency
  • Include practical examples
  • Document prerequisites and dependencies
  • Provide both basic and advanced usage
  • Link to related issues or PRs

Testing Requirements

  • Include unit tests for core functionality
  • Integration tests for tools with external dependencies
  • Test across supported platforms when applicable
  • Follow Test Driven Development practices

Code Quality

From repository root, run quality checks:

# Format, test, and lint (uses Makefile in repo root)
make

# Or explicitly
make format test lint

Common Patterns

Building with Go

# Build binary
go build ./cmd/<tool-name>

# Build and install to GOPATH/bin from local code (convenient during development)
go install ./cmd/<tool-name>

# Install from local changes using relative path from repo root
go install ./devtools/<tool-name>/cmd/<tool-name>

# Install from GitHub (latest release)
go install github.com/jaeyeom/experimental/devtools/<tool-name>/cmd/<tool-name>@latest

Building with Bazel

# Build specific tool
bazel build //devtools/<tool-name>/...

# Build all devtools
bazel build //devtools/...

# Run tests
bazel test //devtools/<tool-name>/...

Integration with Pre-commit Hooks

Many tools can be integrated into Git pre-commit hooks:

#!/bin/sh
# .git/hooks/pre-commit

# Run affected tests
bazel-affected-tests | xargs bazel test

# Run detected format, lint, and test tools
devcheck

# Lint org files
git diff --cached --name-only --diff-filter=ACM | grep '\.org$' | xargs org-lint

CI/CD Integration

Example GitHub Actions workflow:

- name: Install devtools
  run: |
    go install github.com/jaeyeom/experimental/devtools/devcheck/cmd/devcheck@latest
    go install github.com/jaeyeom/bazel-affected-tests/cmd/bazel-affected-tests@latest

- name: Run format, lint, and test
  run: devcheck

- name: Run affected tests
  run: bazel-affected-tests | xargs bazel test

Related Documentation

License

This project follows the licensing terms of the parent experimental repository.