Package Exports

@technicalshree/auto-fix
@technicalshree/auto-fix/dist/cli.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@technicalshree/auto-fix) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

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

Ensure you are logged in to npm:

npm login

Bump the version:

npm version patch

Build and validate the package contents:

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

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

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
src/ui/: terminal renderer and progress hooks
dist/: compiled JavaScript output
docs/: product requirement docs and notes

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

License

ISC

@technicalshree/auto-fix