ForgeFix

One command to set up, health-check, and repair any open-source project.

forgefix doctor tells a newcomer exactly what a repository is missing — README, install line, lockfile, CI, security policy, license, working dev environment — with a deterministic 0–100 health score and concrete fixes. forgefix up then does the bring-up: it detects the stack, repairs missing setup files, installs dependencies, and runs the tests.

• Original code, MIT licensed. ForgeFix reads repository metadata only (file names, README text, config keys). It never copies source code from the projects it inspects.
• No shells, no eval. Every external command runs as a sanitized argument list with a bounded timeout. bandit and gitleaks are wired into CI and pre-commit.

Quickstart (30 seconds)

pip install forgefix        # once published; or: pip install -e .
cd your-project
forgefix doctor             # see the score + what to fix
forgefix up                 # dry-run: shows the bring-up plan
forgefix up --apply         # repairs + venv + deps + tests (never overwrites files)
forgefix report             # writes reports/forgefix-report.md

Try it on the bundled fixtures right now:

forgefix doctor --path tests/fixtures/broken_repo    # -> 42/100
forgefix doctor --path tests/fixtures/minimal_repo   # -> 100/100

Why

Every contributor's first hour in a new repository is the same loop: clone, guess the install command, discover there is no lockfile, hunt for the test runner, wonder whether the project is even maintained. Maintainers keep re-explaining the same missing pieces in issues. ForgeFix turns that tribal knowledge into one deterministic, scriptable check that both humans and CI can run.

Features

The health score is deterministic and unit-tested: every rule carries fixed fail/warn weights, so the same repository always scores the same.

How it compares (by category, not by name)

ForgeFix does not replace linters, formatters, or container starters — it complements them, one layer higher:

Safety model

• Read-only scans. doctor and report open files and read text. They never execute repository code and never touch the network.
• up is dry-run by default. With --apply it only creates missing files (README skeleton, SECURITY.md, .editorconfig, CI workflow) and never overwrites an existing file. It deliberately never invents a LICENSE for you.
• No shell interpolation. Commands are fixed argument lists with full executable paths, shell=False, and bounded timeouts.

Plugins

# my_forgefix_plugin.py
from pathlib import Path
from forgefix.core.rules import Finding


class MyPlugin:
    name = "my-plugin"

    def check(self, root: Path) -> list[Finding]: ...

Register it under the forgefix.plugins entry-point group; ForgeFix discovers it automatically. A broken plugin is logged and skipped — it can never break a scan. See docs/plugins.md.

Roadmap

• Deterministic doctor/report/serve + bring-up
• Plugin API (forgefix.plugins)
• Richer stack detection (rust, java/gradle) and per-rule fix scripts
• SARIF export for GitHub code scanning
• forgefix cloud hosted dashboard for private repos — see docs/monetization.md

Development

make setup     # editable install + pre-commit hooks
make test      # pytest (coverage gate 85%)
make lint      # ruff check + format check
make type      # mypy
make gif       # regenerate demo/demo.gif with vhs

Full guidelines in CONTRIBUTING.md. Docs site: mkdocs serve (config in mkdocs.yml, pages in docs/).

Security

Report vulnerabilities privately per SECURITY.md — 48h acknowledgement SLA.

License

MIT © ForgeFix contributors. Original code; no source copied from other projects.