feat: Initial commit

.github/workflows/ci.yml

@@ -0,0 +1,14 @@
+name: Commit CI
+
+on:
+  push:
+
+jobs:
+  ci:
+    name: CI
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - name: Run CI with fonk
+        run: uv run fonk all

.github/workflows/release.yml

@@ -0,0 +1,20 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "*"
+
+jobs:
+  pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv build
+      - run: uv publish --trusted-publishing always

.gitignore

@@ -0,0 +1,18 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.python-version
+
+# Virtual environments
+.venv
+
+# IDE
+.vscode/
+.idea/
+
+# Caches
+.*_cache/

LICENSE.md

@@ -0,0 +1,8 @@
+Copyright 2025 Thijs Miedema
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

README.md

@@ -0,0 +1,40 @@
+# Fonk
+
+Fonk is an open-source command runner that is fully configured via `pyproject.toml`.
+
+## Usage
+
+First add an entry into your `pyproject.toml` file that contains the command you want to run:
+
+```toml
+[tool.fonk.command.my_command]
+description = "Run my command"
+command = "echo Hello"
+type = "shell"
+``` 
+
+Then run the command using the following command:
+
+```bash
+uvx fonk my_command
+```
+## Contributing
+
+We welcome contributions from the community. To contribute to Fonk, follow these steps:
+
+1. Fork the repository.
+2. Create a new branch (`git checkout -b feature-branch`).
+3. Make your changes.
+4. Commit your changes (`git commit -m 'feat: Add new feature'`).
+5. Push to the branch (`git push origin feature-branch`).
+6. Open a pull request.
+
+Please ensure your code adheres to our coding standards. Since this is a task runner, the required CI steps are also defined as Fonk commands in the `pyproject.toml` file. Simply use `uv run fonk` to run all steps.
+
+## License
+
+Fonk is licensed under the MIT License. See the [LICENSE](./LICENSE.md) file for more details.
+
+## Contact
+
+For any questions or feedback, please open an issue on the [GitHub repository](https://github.com/yourusername/fonk).

pyproject.toml

@@ -0,0 +1,109 @@
+[project]
+name = "fonk"
+version = "0.1.0"
+description = "fonk: pyproject.toml based task runner"
+readme = "README.md"
+license = { file = "LICENSE.md" }
+requires-python = ">=3.9"
+dependencies = [
+    "rich>=13.9.4",
+]
+authors = [
+    {name = "Thijs Miedema", email = "opensource@tmiedema.com"},
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.14.1",
+    "pytest>=8.3.4",
+]
+
+[project.scripts]
+fonk = "fonk.cli:app"
+
+[tool.uv]
+package = true
+
+[tool.fonk]
+flags = [
+    {name = "fix", description = "Autofix issues where possible"},
+    {name = "debug", description = "Enable debugging in test suite"},
+]
+
+[tool.fonk.default]
+description = "Most commonly used: run all checks in fix mode"
+command = "all"
+flags = ["fix"]
+
+[tool.fonk.alias.all]
+description = "Run all checks"
+commands = ["uv-lock", "ruff-check", "ruff-format", "mypy", "pytest"]
+
+[tool.fonk.alias.format]
+description = "Check and/or fix code formatting/styling"
+commands = ["ruff-check", "ruff-format"]
+flags = ["fix"]
+
+[tool.fonk.alias.typecheck]
+description = "Run the type checker"
+commands = ["mypy"]
+
+[tool.fonk.alias.test]
+description = "Run the test suite"
+commands = ["pytest"]
+
+[tool.fonk.command.uv-lock]
+type = "shell"
+description = "Check if the lock file is up to date"
+arguments = ["uv", "lock", "--check"]
+flags = [
+    {on = "verbose", add = "--verbose"},
+    {on = "quiet", add = "--quiet"},
+    {on = "fix", remove = "--check"},
+]
+
+[tool.fonk.command.ruff-check]
+type = "uvx"
+description = "Check and/or fix the code style"
+arguments = ["ruff", "check", "src"]
+flags = [
+    {on = "verbose", add = "--verbose"},
+    {on = "quiet", add = "--quiet"},
+    {on = "fix", add = "--fix"},
+]
+
+[tool.fonk.command.ruff-format]
+type = "uvx"
+description = "Check and/or fix code formatting"
+arguments = ["ruff", "format", "--check", "src"]
+flags = [
+    {on = "verbose", add = "--verbose"},
+    {on = "quiet", add = "--quiet"},
+    {on = "fix", remove = "--check"},
+]
+
+[tool.fonk.command.mypy]
+type = "uv"
+description = "Perform static type checking"
+arguments = ["mypy", "src"]
+flags = [
+    {on = "verbose", add = "--verbose"},
+    {on = "quiet", add = "--no-error-summary"}
+]
+
+[tool.fonk.command.pytest]
+type = "uv"
+description = "Run the test suite with pytest"
+arguments = ["pytest", "tests", "--verbose"]
+flags = [
+    {on = "verbose", add = "-vvv", remove = "--verbose"},
+    {on = "quiet", add = ["-q", "--no-summary"], remove = "--verbose"},
+    {on = "fail-quick", add = "-x"},
+    {on = "debug", add = "--pdb"}
+]

src/fonk/__main__.py

@@ -0,0 +1,5 @@
+from fonk.cli import app
+
+
+if __name__ == "__main__":
+    app()

src/fonk/cli.py

@@ -0,0 +1,93 @@
+import asyncio
+from fonk.config import (
+    get_config,
+    ConfigurationError,
+    Flag,
+    FLAG_CONCURRENT,
+    FLAG_HELP,
+    FLAG_FAIL_QUICK,
+    FLAG_QUIET,
+    FLAG_VERBOSE,
+)
+import sys
+import rich
+from fonk.render import render_help, render_help_command
+from fonk.session import Session, SessionError
+
+
+def app() -> None:
+    try:
+        config = get_config()
+    except ConfigurationError as e:
+        rich.print(f"💥[bold red] {e}")
+        sys.exit(1)
+
+    flags: set[Flag] = set()
+    runnables: list[str] = []
+
+    for arg in sys.argv[1:]:
+        if arg.startswith("-"):
+            if arg.startswith("--"):
+                flag_name = arg[2:]
+                for flag in config.flags:
+                    if flag_name == flag.name:
+                        flags.add(flag)
+                        break
+                else:
+                    rich.print(f"💥[bold red] Unknown flag: {flag_name}")
+                    sys.exit(1)
+            else:
+                shorthands = arg[1:]
+
+                for flag in config.flags:
+                    if flag.shorthand and flag.shorthand in shorthands:
+                        flags.add(flag)
+                        shorthands = shorthands.replace(flag.shorthand, "")
+
+                if shorthands:
+                    rich.print(f"💥[bold red] Unknown flag shorthand: {shorthands}")
+                    sys.exit(1)
+
+            for flag in config.flags:
+                if arg == f"--{flag.name}" or arg == f"-{flag.shorthand}":
+                    flags.add(flag)
+                    break
+        else:
+            runnables.append(arg)
+
+    if FLAG_HELP in flags:
+        if runnables:
+            for runnable in runnables:
+                render_help_command(config, runnable)
+        else:
+            render_help(config)
+
+        sys.exit(0)
+
+    if not runnables:
+        default = config.default
+
+        if default is None:
+            rich.print("💥[bold red] No runnables provided and no default set")
+            sys.exit(1)
+
+        runnables.append(default.command)
+        flags.update({flag for flag in config.flags if flag.name in default.flags})
+
+    session = Session(
+        config,
+        FLAG_QUIET in flags,
+        FLAG_VERBOSE in flags,
+        FLAG_FAIL_QUICK in flags,
+    )
+
+    try:
+        if FLAG_CONCURRENT in flags:
+            asyncio.run(session.run_runnables_concurrently(runnables, flags))
+        else:
+            session.run_runnables(runnables, flags)
+    except SessionError as e:
+        rich.print(f"💥[bold red] {e}")
+        sys.exit(1)
+
+    session.exit()