auto-fix

auto-fix is a TypeScript CLI that detects local development environment issues and applies safe, explainable fixes for Node, Python, and Docker-based projects.

What it does

• Detects project stack (Node, Python, Docker Compose)
• Diagnoses common local setup problems
• Builds an explicit fix plan before execution
• Runs safe fixes by default
• Supports gated destructive cleanup (--deep, --approve)
• Writes run reports and snapshot metadata for rollback
• Supports best-effort undo for snapshotted changes
• Syncs .env files from .env.example templates (v1.2)
• Detects Node/Python runtime version drift (v1.2)
• Auto-configures VS Code Python interpreter path (v1.2)
• Provides actionable guidance for EPERM/EBUSY file lock errors (v1.2)

Requirements

• Node.js 18+
• npm (or compatible Node package manager for development)
• Optional tools (used only when relevant to your project):
  • Python + pip/uv/poetry/pipenv
  • Docker + Docker Compose

Installation

1) Install from npm (recommended)

Run directly without installing globally:

npx auto-fix doctor

Install globally:

npm install -g @technicalshree/auto-fix
auto-fix --help

2) Install from source (development)

Clone and install dependencies:

git clone <your-repo-url>
cd ts-cli-tool
npm install

Build the CLI:

npm run build

Run locally:

npm start

Use as a CLI command (auto-fix)

After build, the executable is exposed via:

• Bin name: auto-fix
• Entry point: dist/cli.js

You can run it in either of these ways:

npm start -- doctor

node dist/cli.js doctor

To install globally from this repo:

npm run build
npm link

Then use:

auto-fix

To remove global link:

npm unlink -g auto-fix

Publish to npm

1. Ensure you are logged in to npm:

npm login

2. Bump the version:

npm version patch

3. Build and validate the package contents:

npm run build
npm pack --dry-run --cache /tmp/npm-cache-autofix

4. Publish:

npm publish

Quick start

Run safe fixes (default behavior):

auto-fix

Diagnosis only (no changes):

auto-fix doctor

Preview plan without executing:

auto-fix plan

Show latest report as JSON:

auto-fix report --json

Rollback latest run (best-effort):

auto-fix undo

Clear global package manager caches:

auto-fix clear-npm-cache
auto-fix clear-yarn-cache
auto-fix clear-pnpm-cache

v1.2 Features

Environment Variable Synchronization

auto-fix detects .env.example files and helps keep your local .env in sync:

• Missing .env: If .env.example exists but .env does not, auto-fix will copy it automatically.
• Missing keys: If both files exist, auto-fix compares the keys and appends any missing keys from .env.example to your .env with empty values.
• Changes to .env are snapshotted for undo coverage.

# See env sync in action
auto-fix plan
# Output: ● Copy .env.example to .env
# Output: ● Append 2 missing key(s) to .env

Runtime Engine Version Checks

auto-fix validates that your local Node.js and Python versions match what the project expects:

• Node: Reads .nvmrc or .node-version and compares the major version against process.version. Emits a warning with suggested action (nvm use).
• Python: Reads .python-version and flags a version drift warning.
• These checks run before dependency installations to catch mismatches early.
• Engine checks fire based on version file existence alone — no package.json or pyproject.toml required.

auto-fix plan
# Output: ● Node version drift detected: expected ~18, running v22.x — Run nvm use
# Output: ● Python version drift: project expects 3.11

VS Code Python Integration

When a Python virtual environment (.venv) exists or is being created, auto-fix automatically configures VS Code to use it:

• Sets python.defaultInterpreterPath in .vscode/settings.json
• Prevents false-positive Pylance/Pyright linting errors for new developers
• The change is snapshotted for undo coverage

EPERM/EBUSY Error Guidance

When node_modules cleanup or dependency installation fails due to file locks (common on Windows and macOS), auto-fix now provides specific, actionable error messages:

✖ Permission/lock error (EPERM/EBUSY). Close your IDE, dev servers, or file watchers and retry.

This replaces the previous generic "One or more commands failed" message.

Commands

auto-fix [command] [flags]

• Default command (auto-fix): detect + execute safe fixes
• doctor: detection and diagnosis only (no modifications)
• plan: prints execution plan (same as dry-run)
• report: reads latest report (--run runs fresh first)
• undo: best-effort restore using latest run snapshots
• clear-npm-cache: runs npm cache clean --force
• clear-yarn-cache: runs yarn cache clean
• clear-pnpm-cache: runs pnpm store prune
• help: show CLI help

Flags (all)

Safety and execution control

• --dry-run: show actions, do not execute
• --deep: enable destructive cleanup steps (for example deleting node_modules)
• --approve: skip interactive prompts and allow destructive steps
• --force-fresh: allow fresh rebuild actions (requires --deep or --approve)
• --focus <subsystem>: restrict execution to one subsystem
  • Allowed values: node, python, docker, all
• --checks <list>: checks phase selector
  • Comma-separated values from: lint,test,format
  • Example: --checks lint,test
• --kill-ports [ports]: enable port cleanup
  • Optional comma-separated ports
  • If omitted, defaults are used from config

Output and reporting

• --verbose: print commands and command outputs
• --quiet: minimal output, still prints final summary
• --no-color: disable ANSI colors
• --json: print machine-readable JSON report to stdout
• --report-path <path>: override report directory path
• --run: with report, run a fresh execution instead of reading latest

Typical usage patterns

Safe default run:

auto-fix

Plan before execution:

auto-fix plan

Deep cleanup with explicit approval:

auto-fix --deep --approve

Only Node subsystem:

auto-fix --focus node

Run only lint + test checks:

auto-fix --checks lint,test

Kill default configured ports then execute:

auto-fix --kill-ports

Kill specific ports:

auto-fix --kill-ports 3000,5173,9229

Read latest report:

auto-fix report --json

Trigger run and emit JSON in one command:

auto-fix report --run --json

Clear npm global cache:

auto-fix clear-npm-cache

Clear yarn global cache:

auto-fix clear-yarn-cache

Clear pnpm global cache:

auto-fix clear-pnpm-cache

Configuration

auto-fix works without config. To customize behavior, create .autofix.yml in project root.

The loader searches current directory upward until git root.

Example .autofix.yml

version: 1

ports:
  default: [3000, 5173, 8000, 8080]
  extra: [9229]

node:
  package_manager: auto # auto | npm | pnpm | yarn
  deep_cleanup:
    remove_node_modules: true
    remove_lockfile: false
  caches:
    next: true
    vite: true
    directories: [".turbo", ".cache"]

python:
  venv_path: .venv
  install:
    prefer: uv # uv | pip | poetry | pipenv | auto
  tools:
    format: ["ruff format", "black ."]
    lint: ["ruff check ."]
    test: ["pytest -q"]

docker:
  compose_file: auto
  safe_down: true
  rebuild: true
  prune: false

checks:
  default: [lint, format, test]

output:
  report_dir: .autofix/reports
  snapshot_dir: .autofix/snapshots
  verbosity: normal # quiet | normal | verbose

Reports and artifacts

By default:

• Reports: .autofix/reports/
• Latest report: .autofix/reports/latest.json
• Snapshots: .autofix/snapshots/

auto-fix also ensures .autofix/ is in .gitignore.

If the configured snapshot directory is not writable, snapshots fall back to a temp directory:

• macOS/Linux pattern: /tmp/autofix/<run_id>

Undo behavior (important)

auto-fix undo is best-effort and limited to steps that:

• Are marked undoable
• Have snapshot paths recorded in the report
• Still have snapshot files available

Undo cannot restore changes that were never snapshotted or are irreversible by nature.

Exit codes

• 0: successful run or expected non-error output
• 1: runtime error, missing latest report for report/undo, or doctor found issues

Development

Scripts

• npm run dev: run CLI from source with tsx (src/cli.ts)
• npm run build: compile TypeScript to dist/
• npm start: run built CLI (dist/cli.js)
• npm test: build silently and run Node test runner
• npm run lint: TypeScript type-check only (tsc --noEmit)

Local development workflow

npm install
npm run lint
npm test
npm run dev -- doctor
npm run build

Project structure

• src/cli.ts: CLI entrypoint and argument parsing
• src/core/: detection, planning, execution, safety, undo
• src/config/: defaults and config loading
• src/report/: summary and report writing
• src/subsystems/: subsystem-specific checks/fixes
  • environment.ts: .env sync logic (v1.2)
  • engines.ts: runtime version checks (v1.2)
• src/ui/: terminal renderer and progress hooks
• dist/: compiled JavaScript output
• docs/: product requirement docs and notes
• test/: test suites
  • smoke.test.mjs: CLI smoke tests
  • v1.2.test.mjs: v1.2 feature unit tests

Troubleshooting

auto-fix command not found:

• Run npm run build first
• Use node dist/cli.js ... directly
• If using global link, run npm link in project root

No report found for report or undo:

• Run auto-fix once first
• Check custom --report-path usage
• Verify .autofix/reports/latest.json exists

Non-interactive environments behave conservatively:

• In polyglot projects (Node + Python + Docker), non-interactive mode without --approve may limit execution to a safe subset

Changelog

v1.2.0

• Environment sync: Auto-copy .env.example → .env; detect and append missing keys
• Engine version checks: Validate Node (.nvmrc) and Python (.python-version) versions before dependency install
• VS Code integration: Auto-configure python.defaultInterpreterPath when .venv exists
• EPERM handling: Actionable error messages for file lock failures in node steps
• Snapshot improvements: Non-destructive steps with declared snapshot paths are now backed up
• Undo fix: Nested file paths (e.g., .vscode/settings.json) are now restored correctly
• Test coverage: Added 8 unit tests for v1.2 features

v1.1.x

• Initial release with Node, Python, Docker detection and safe fix execution
• Polyglot project support with interactive confirmation
• Run reports, snapshots, and best-effort undo
• CLI help, version banner, and configurable .autofix.yml

License

ISC