reorg and add templates + readme

Author: soodoku

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+# Generated by preen — do not edit manually
+# Regenerate with: preen sync
+
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        os: [ubuntu-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync
+      - run: uv run pytest
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync
+      - run: uv run ruff check
+      - run: uv run ruff format --check

.gitignore

@@ -1,2 +1,6 @@
 .DS_Store
 /preen/__pycache__
+/tests/__pycache__
+/preen/templates/__pycache__
+/preen/checks/__pycache__
+/preen.egg-info

CITATION.cff

@@ -5,11 +5,10 @@ cff-version: 1.2.0
 message: "If you use this software, please cite it as below."
 title: preen
 version: 0.1.0
-date-released: 2025-12-04
-url: https://github.com/username/preen
-repository-code: https://github.com/username/preen
-license: MIT
+date-released: 2025-12-03
+url: https://github.com/gojiplus/preen
+repository-code: https://github.com/gojiplus/preen
 authors:
   - family-names: Sood
     given-names: Gaurav
-    email: [email protected]
+    email: [email protected]

README.md

@@ -1,7 +1,250 @@
 # preen
 
-*An opinionated, agentic CLI for Python package hygiene and release.*
+**An opinionated, agentic CLI for Python package hygiene and release**
 
-`preen` helps Python package maintainers keep their metadata, configuration files and workflows in sync.  It reads information from your `pyproject.toml` and regenerates derived files such as GitHub Actions workflows, documentation configuration and a `CITATION.cff` file.  The tool is intended as the last step before a release to ensure that everything is consistent and ready for publication.
+*"Get your feathers in order before you fly"*
 
-This repository contains the early implementation of `preen`.  The current scope focuses on the sync functionality, which reads a project's metadata and writes a set of standardised files.  Future versions will add an interactive check runner, initialisation helpers and release workflows as described in the vision.
+`preen` is a comprehensive tool for Python package maintenance that treats `pyproject.toml` as the single source of truth. It automatically generates and synchronizes derived files, runs comprehensive pre-release checks, and provides an opinionated workflow for package development and release.
+
+## Features
+
+- 🔍 **7 comprehensive checks** - linting, tests, dependencies, CI matrix, project structure, version consistency, and citation validation
+- 🔧 **Interactive fixes** - preview diffs and apply fixes automatically or selectively
+- 📦 **Package initialization** - scaffold new packages with opinionated best practices
+- 🔄 **File synchronization** - generate CI workflows, documentation config, and CITATION.cff from pyproject.toml
+- 📈 **Version management** - semantic versioning with automatic derived file updates
+- 🎯 **Modern tooling** - uv-native workflows, GitHub Actions, and trusted publishing
+
+## Installation
+
+```bash
+pip install preen
+```
+
+Requires Python 3.9+
+
+## Quick Start
+
+### Create a new package
+```bash
+preen init mypackage
+cd mypackage
+pip install -e .[dev]
+```
+
+### Run checks and fixes
+```bash
+preen check          # Interactive check with fix prompts
+preen check --fix    # Apply all fixes automatically
+preen check --strict # Exit 1 if any issues (perfect for CI)
+```
+
+### Sync derived files
+```bash
+preen sync                    # Update all derived files
+preen sync --only citation   # Update only CITATION.cff
+preen sync --check          # Check if files need updating (CI mode)
+```
+
+### Manage versions
+```bash
+preen bump patch    # 1.0.0 → 1.0.1
+preen bump minor    # 1.0.1 → 1.1.0
+preen bump major    # 1.1.0 → 2.0.0
+```
+
+## Commands
+
+### `preen init`
+Initialize new Python packages with opinionated structure:
+- Modern `pyproject.toml` with setuptools backend
+- `src/` layout for better import isolation  
+- Comprehensive `tests/` directory at project root
+- GitHub Actions workflows for CI, docs, and release
+- Pre-configured development dependencies (pytest, ruff)
+- CITATION.cff for academic software
+
+```bash
+preen init mypackage                    # Interactive mode
+preen init mypackage --dir ./custom     # Specify directory
+```
+
+### `preen check`
+Run comprehensive pre-release checks:
+
+| Check | Description |
+|-------|-------------|
+| **ruff** | Code linting and formatting |
+| **tests** | Run pytest suite |
+| **deps** | Find unused/missing dependencies (requires deptry) |
+| **ci-matrix** | Verify CI tests all declared Python versions |
+| **structure** | Enforce project structure best practices |
+| **version** | Detect hardcoded version strings |
+| **citation** | Ensure CITATION.cff matches pyproject.toml |
+
+```bash
+preen check                     # Interactive mode
+preen check --fix              # Auto-apply all fixes
+preen check --only ruff,tests  # Run specific checks
+preen check --skip deps        # Skip dependency check
+preen check --strict           # CI mode (exit 1 on issues)
+```
+
+### `preen sync`
+Synchronize derived files from `pyproject.toml`:
+- `.github/workflows/ci.yml` - CI matrix from Python classifiers
+- `.github/workflows/docs.yml` - Documentation deployment
+- `.github/workflows/release.yml` - PyPI publishing with trusted publisher
+- `docs/conf.py` - Sphinx configuration
+- `CITATION.cff` - Citation metadata for academic software
+
+```bash
+preen sync                      # Update all derived files
+preen sync --only ci,citation  # Update specific targets
+preen sync --check             # Verify files are up to date
+```
+
+### `preen bump`
+Semantic version management:
+- Updates version in `pyproject.toml`
+- Regenerates all derived files with new version
+- Commits changes to git with conventional commit message
+
+```bash
+preen bump patch        # Bug fixes: 1.0.0 → 1.0.1
+preen bump minor        # New features: 1.0.1 → 1.1.0  
+preen bump major        # Breaking changes: 1.1.0 → 2.0.0
+preen bump patch --dry-run     # Preview changes
+preen bump minor --no-commit   # Skip git commit
+```
+
+## Configuration
+
+Customize behavior in `pyproject.toml`:
+
+```toml
+[tool.preen]
+# CI configuration
+ci_os = ["ubuntu-latest", "macos-latest"]
+ci_runner = "uv"  # or "pip"
+
+# Documentation
+sphinx_theme = "furo"
+use_myst = true
+
+# Structure preferences  
+src_layout = true
+tests_at_root = true
+
+# Skip specific checks
+skip_checks = ["deps", "structure"]
+```
+
+## Development Workflow
+
+Typical workflow for package maintenance:
+
+```bash
+# 1. Initialize new package
+preen init myawesome-package
+cd myawesome-package
+
+# 2. Develop your package
+# ... write code, tests ...
+
+# 3. Pre-release checks
+preen check --fix
+
+# 4. Version bump and release prep
+preen bump minor
+git push origin main
+
+# 5. Manual steps (for now)
+# - Create GitHub release
+# - CI will build and publish to PyPI via trusted publisher
+```
+
+## Philosophy
+
+**pyproject.toml as Single Source of Truth**
+- All metadata lives in one place
+- Derived files are generated, never edited manually
+- Eliminates version mismatches and configuration drift
+
+**Opinionated Best Practices**
+- `src/` layout for better import isolation
+- `tests/` at project root, not inside package
+- Modern Python packaging (setuptools, trusted publishing)
+- Comprehensive CI matrix matching declared Python support
+
+**DRY Across Configuration**
+- CI matrix generated from Python classifiers
+- Documentation config reflects project metadata
+- CITATION.cff stays in sync with authors and version
+
+## Generated Files
+
+When you run `preen sync`, these files are generated/updated:
+
+```
+.github/workflows/
+├── ci.yml           # Test matrix + linting
+├── docs.yml         # Documentation deployment  
+└── release.yml      # PyPI publishing
+
+docs/
+└── conf.py          # Sphinx configuration
+
+CITATION.cff         # Citation metadata
+```
+
+All generated files include a header indicating they're managed by preen:
+```yaml
+# Generated by preen — do not edit manually
+# Regenerate with: preen sync
+```
+
+## Integration
+
+**GitHub Actions**
+```yaml
+# .github/workflows/quality.yml
+- name: Package hygiene
+  run: |
+    pip install preen
+    preen check --strict
+    preen sync --check
+```
+
+**Pre-commit Hook**
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: local
+    hooks:
+      - id: preen-check
+        name: preen check
+        entry: preen check --strict
+        language: system
+        pass_filenames: false
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run `preen check` to ensure code quality
+5. Submit a pull request
+
+For development setup:
+```bash
+git clone https://github.com/gojiplus/preen.git
+cd preen
+pip install -e .[dev]
+preen check
+```

preen/__init__.py

@@ -7,7 +7,7 @@
 """
 
 from importlib.metadata import version as _get_version  # type: ignore
-from pathlib import Path
+
 from .syncer import sync_project
 
 __all__ = ["__version__", "sync_project"]
@@ -22,4 +22,4 @@ def __getattr__(name: str):
     """
     if name == "__version__":
         return _get_version(__name__)
-    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

preen/__main__.py

@@ -0,0 +1,6 @@
+"""Allow preen to be run as a module."""
+
+from .cli import run
+
+if __name__ == "__main__":
+    run()

preen/checks/__init__.py

@@ -0,0 +1,10 @@
+"""Check framework for preen.
+
+This module provides the base infrastructure for running checks and
+managing issues/fixes.
+"""
+
+from .base import Check, CheckResult, Issue, Fix, Severity
+from .runner import run_checks
+
+__all__ = ["Check", "CheckResult", "Issue", "Fix", "Severity", "run_checks"]