refactron (Python wrapper)

The verification layer for AI code change. Refactron proves that a change, your AI agent's, a codemod's, or your own, preserved behavior. It applies the diff in an isolated shadow tree, runs your real test suite, and returns a three-way verdict: SAFE, UNSAFE, or UNPROVEN. Your working tree is never touched.

This package is a thin Python shim around the npm refactron package. It exists so a Python-first toolchain can put the refactron command on your PATH without adding Node to your project manifest. All the real work happens in the Node CLI.

Requirements

  • Node.js 18+ on your PATH. This wrapper does not remove the Node dependency; it only saves you from wiring the CLI in by hand.
  • Python 3.8+, plus coverage.py in the environment your tests run in if you want coverage-backed verdicts.

Install

pip install refactron==0.3.0
npm install -g refactron@0.3.0

Both lines matter. The pip package gives you the refactron entry point; the npm package is what it runs. Keep the two versions equal: the wrapper prints a warning to stderr when they disagree.

The wrapper does not install the npm package for you. A pip install that silently ran npm install -g would write outside your Python environment and would pull whatever version is latest, which is not necessarily the version you pinned. If the Node CLI is missing, the wrapper tells you the exact command to run and exits non-zero.

Prefer not to install globally? Skip the pip package and use npx refactron@0.3.0 <command> directly.

Usage

Identical to the npm package. Every argument is passed straight through.

refactron login                                  # or set REFACTRON_TOKEN in CI
refactron verify-diff . --diff change.diff --test-cmd "python3 -m pytest -q"
refactron preflight ./my-sqlalchemy-app
refactron analyze .
refactron run --apply

verify-diff exits 1 on UNSAFE, 2 on bad input, 7 when unauthenticated, and 0 on both SAFE and UNPROVEN. UNPROVEN is a warning, not a rejection: read the verdict field from --json if you want CI to fail on it.

Coverage attestation is Python-only, via coverage.py. A TypeScript, mixed, or otherwise non-Python diff caps at UNPROVEN; it never returns a false SAFE.

MCP server

The npm package also ships a refactron-mcp binary, a stdio MCP server exposing a verify_change tool your agent calls before it lands a change. It is not routed through this wrapper: point your MCP client at refactron-mcp directly. See the MCP docs.

Environment variables

Variable Effect
REFACTRON_TOKEN Authenticates non-interactive runs (CI).
REFACTRON_SKIP_VERSION_CHECK Set to 1 to silence the wrapper's version-skew warning.

License

Apache-2.0. See LICENSE and NOTICE.

Full docs: https://docs.refactron.dev

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.4.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for omsherikar from gravatar.com omsherikar

Credits

Author: Om Sherikar

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

Apache Software License (Apache-2.0)

Requires

Python >=3.8

Tags

verification ai-agents mcp code-review testing ci refactoring python typescript ast cli

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

refactron-0.3.0.tar.gz (10.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

refactron-0.3.0-py3-none-any.whl (11.2 kB view details)

Uploaded Python 3

File details

Details for the file refactron-0.3.0.tar.gz.

File metadata

  • Download URL: refactron-0.3.0.tar.gz
  • Upload date:
  • Size: 10.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for refactron-0.3.0.tar.gz
Algorithm Hash digest
SHA256 d9191ec919ced6ea66385e8ab8a2fd5f3d1f3b79ecba3b29912773e506ea4669
MD5 051b5c9f2ca8b68070328592ea3e40ff
BLAKE2b-256 d0be89eb8d73cf6e972a4dd031af5fe7c176202c341d8ab35088072fa580850e

See more details on using hashes here.

Provenance

The following attestation bundles were made for refactron-0.3.0.tar.gz:

Publisher: release.yml on Refactron-ai/Refactron_Lib_TS

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file refactron-0.3.0-py3-none-any.whl.

File metadata

  • Download URL: refactron-0.3.0-py3-none-any.whl
  • Upload date:
  • Size: 11.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for refactron-0.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 76d2df92f3f0236166e2460f4680f74b48776cc8c5b996b7e4d29a432abe8f8e
MD5 e136224173a9e2168cf45c873471972c
BLAKE2b-256 7cafe35a75ecb92167fb48eb1ee8ebd5e615a78dcc2f54c950875fb599ee9aca

See more details on using hashes here.

Provenance

The following attestation bundles were made for refactron-0.3.0-py3-none-any.whl:

Publisher: release.yml on Refactron-ai/Refactron_Lib_TS

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page