@technicalshree/auto-fix 1.1.0

package/README.md

@@ -0,0 +1,408 @@
+# 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:
+
+```bash
+npx auto-fix doctor
+```
+
+Install globally:
+
+```bash
+npm install -g @technicalshree/auto-fix
+auto-fix --help
+```
+
+### 2) Install from source (development)
+
+Clone and install dependencies:
+
+```bash
+git clone <your-repo-url>
+cd ts-cli-tool
+npm install
+```
+
+Build the CLI:
+
+```bash
+npm run build
+```
+
+Run locally:
+
+```bash
+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:
+
+```bash
+npm start -- doctor
+```
+
+```bash
+node dist/cli.js doctor
+```
+
+To install globally from this repo:
+
+```bash
+npm run build
+npm link
+```
+
+Then use:
+
+```bash
+auto-fix
+```
+
+To remove global link:
+
+```bash
+npm unlink -g auto-fix
+```
+
+## Publish to npm
+
+1. Ensure you are logged in to npm:
+
+```bash
+npm login
+```
+
+2. Bump the version:
+
+```bash
+npm version patch
+```
+
+3. Build and validate the package contents:
+
+```bash
+npm run build
+npm pack --dry-run --cache /tmp/npm-cache-autofix
+```
+
+4. Publish:
+
+```bash
+npm publish
+```
+
+## Quick start
+
+Run safe fixes (default behavior):
+
+```bash
+auto-fix
+```
+
+Diagnosis only (no changes):
+
+```bash
+auto-fix doctor
+```
+
+Preview plan without executing:
+
+```bash
+auto-fix plan
+```
+
+Show latest report as JSON:
+
+```bash
+auto-fix report --json
+```
+
+Rollback latest run (best-effort):
+
+```bash
+auto-fix undo
+```
+
+Clear global package manager caches:
+
+```bash
+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:
+
+```bash
+auto-fix
+```
+
+Plan before execution:
+
+```bash
+auto-fix plan
+```
+
+Deep cleanup with explicit approval:
+
+```bash
+auto-fix --deep --approve
+```
+
+Only Node subsystem:
+
+```bash
+auto-fix --focus node
+```
+
+Run only lint + test checks:
+
+```bash
+auto-fix --checks lint,test
+```
+
+Kill default configured ports then execute:
+
+```bash
+auto-fix --kill-ports
+```
+
+Kill specific ports:
+
+```bash
+auto-fix --kill-ports 3000,5173,9229
+```
+
+Read latest report:
+
+```bash
+auto-fix report --json
+```
+
+Trigger run and emit JSON in one command:
+
+```bash
+auto-fix report --run --json
+```
+
+Clear npm global cache:
+
+```bash
+auto-fix clear-npm-cache
+```
+
+Clear yarn global cache:
+
+```bash
+auto-fix clear-yarn-cache
+```
+
+Clear pnpm global cache:
+
+```bash
+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`
+
+```yaml
+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
+
+```bash
+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

package/dist/cli.js

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { loadConfig } from "./config/loadConfig.js";
+import { runAutoFix } from "./core/run.js";
+import { renderSummary, renderQuietSummary } from "./report/renderSummary.js";
+import { writeRunReport } from "./report/writeReport.js";
+import { isInteractive } from "./utils/tty.js";
+import { readJsonFile } from "./utils/fs.js";
+import { undoLatest } from "./core/undo.js";
+import { createRenderer } from "./ui/renderer.js";
+import { runShellCommand } from "./utils/process.js";
+function makeRunId() {
+    return `${new Date().toISOString().replace(/[:.]/g, "-")}-${randomBytes(3).toString("hex")}`;
+}
+function parseCsv(value) {
+    return value
+        .split(",")
+        .map((x) => x.trim())
+        .filter(Boolean);
+}
+function printHelp() {
+    console.log(`
+auto-fix — detect, diagnose, and safely fix common dev environment issues
+
+USAGE
+  auto-fix [command] [flags]
+
+COMMANDS
+  (default)    Run safe fixes (detect project, execute fix plan)
+  doctor       Diagnosis only — no changes, collects facts + recommendations
+  plan         Print the exact plan that would run (no changes)
+  report       Show the last run's report (use --json for machine-readable)
+  undo         Best-effort rollback of the last run
+  clear-npm-cache   Clear global npm package cache
+  clear-yarn-cache  Clear global yarn package cache
+  clear-pnpm-cache  Clear global pnpm package cache
+  help         Show this help message
+
+SAFETY & CONTROL
+  --dry-run                Show actions, run nothing (same as plan)
+  --deep                   Enable destructive cleanup steps (e.g. delete node_modules)
+  --approve                Skip prompts, allow destructive steps (still logs)
+  --force-fresh            Allow fresh rebuild actions (requires --deep or --approve)
+  --focus <subsystem>      Restrict to: node | python | docker | all (default: all)
+  --checks <list>          Run checks phase: lint,test,format (comma-separated)
+  --kill-ports [ports]     Enable port cleanup. Optional comma-separated ports
+
+OUTPUT & REPORTING
+  --verbose                Print executed commands + stdout/stderr
+  --quiet                  Minimal output (still prints final summary)
+  --no-color               Disable ANSI coloring
+  --json                   Print JSON report to stdout
+  --report-path <path>     Override where to write reports
+  --run                    With 'report' command: run fresh instead of reading latest
+
+EXAMPLES
+  auto-fix                 Run safe fixes for detected project
+  auto-fix doctor          Diagnose without changing anything
+  auto-fix plan            Preview what would run
+  auto-fix --deep          Run with destructive cleanup enabled
+  auto-fix --kill-ports    Kill processes on default ports first
+  auto-fix report --json   Print last run report as JSON
+  auto-fix undo            Rollback the last run (best-effort)
+  auto-fix clear-npm-cache Clear npm cache
+  auto-fix clear-yarn-cache Clear yarn cache
+  auto-fix clear-pnpm-cache Clear pnpm cache
+
+CONFIG
+  Place .autofix.yml in your project root for custom settings.
+  auto-fix works out-of-the-box without any config file.
+`.trim());
+}
+function parseArgs(argv) {
+    if (argv.length === 0)
+        return { command: "run", flags: defaultFlags(), help: false };
+    const hasHelp = argv.includes("--help") || argv.includes("-h") || argv[0] === "help";
+    if (hasHelp)
+        return { command: "run", flags: defaultFlags(), help: true };
+    const [first, ...rest] = argv;
+    const command = first === "doctor" ||
+        first === "plan" ||
+        first === "report" ||
+        first === "undo" ||
+        first === "clear-npm-cache" ||
+        first === "clear-yarn-cache" ||
+        first === "clear-pnpm-cache"
+        ? first
+        : "run";
+    const args = command === "run" ? argv : rest;
+    const flags = defaultFlags();
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--dry-run")
+            flags.dryRun = true;
+        else if (arg === "--deep")
+            flags.deep = true;
+        else if (arg === "--approve")
+            flags.approve = true;
+        else if (arg === "--force-fresh")
+            flags.forceFresh = true;
+        else if (arg === "--verbose")
+            flags.verbose = true;
+        else if (arg === "--quiet")
+            flags.quiet = true;
+        else if (arg === "--no-color")
+            flags.noColor = true;
+        else if (arg === "--json")
+            flags.json = true;
+        else if (arg === "--run")
+            flags.run = true;
+        else if (arg === "--focus" && args[i + 1]) {
+            const f = args[i + 1];
+            if (f === "node" || f === "python" || f === "docker" || f === "all")
+                flags.focus = f;
+            i += 1;
+        }
+        else if (arg === "--checks" && args[i + 1]) {
+            flags.checks = parseCsv(args[i + 1]).filter((v) => v === "lint" || v === "test" || v === "format");
+            i += 1;
+        }
+        else if (arg === "--kill-ports") {
+            if (args[i + 1] && !args[i + 1].startsWith("--")) {
+                flags.killPorts = parseCsv(args[i + 1]).map((v) => Number(v)).filter((n) => Number.isInteger(n) && n > 0);
+                i += 1;
+            }
+            else {
+                flags.killPorts = [];
+            }
+        }
+        else if (arg === "--report-path" && args[i + 1]) {
+            flags.reportPath = args[i + 1];
+            i += 1;
+        }
+    }
+    if (command === "plan")
+        flags.dryRun = true;
+    return { command, flags, help: false };
+}
+async function runCacheCommand(command, cwd) {
+    const shellCommand = command === "clear-npm-cache"
+        ? "npm cache clean --force"
+        : command === "clear-yarn-cache"
+            ? "yarn cache clean"
+            : "pnpm store prune";
+    console.log(`Running: ${shellCommand}`);
+    const result = await runShellCommand(shellCommand, cwd);
+    if (result.stdout.trim())
+        console.log(result.stdout.trim());
+    if (result.stderr.trim())
+        console.error(result.stderr.trim());
+    if (!result.success) {
+        console.error(`Command failed with exit code ${result.code}`);
+        return false;
+    }
+    console.log("Cache cleared successfully.");
+    return true;
+}
+function defaultFlags() {
+    return {
+        dryRun: false,
+        deep: false,
+        approve: false,
+        forceFresh: false,
+        focus: "all",
+        verbose: false,
+        quiet: false,
+        noColor: false,
+        json: false,
+        run: false,
+    };
+}
+async function main() {
+    const { command, flags, help } = parseArgs(process.argv.slice(2));
+    if (help) {
+        printHelp();
+        return;
+    }
+    const cwd = process.cwd();
+    const interactive = isInteractive();
+    const ui = createRenderer(flags, interactive);
+    const ctx = {
+        command,
+        cwd,
+        runId: makeRunId(),
+        flags,
+        interactive,
+    };
+    const { config } = await loadConfig(cwd);
+    const reportDir = path.resolve(cwd, flags.reportPath ?? config.output.report_dir);
+    // ── cache clear commands ──
+    if (command === "clear-npm-cache" || command === "clear-yarn-cache" || command === "clear-pnpm-cache") {
+        const ok = await runCacheCommand(command, cwd);
+        if (!ok)
+            process.exitCode = 1;
+        return;
+    }
+    // ── undo ──
+    if (command === "undo") {
+        ui.intro("undo");
+        ui.startTask("Reading latest report\u2026");
+        const { report, entries } = await undoLatest(path.join(reportDir, "latest.json"), cwd);
+        if (!report) {
+            ui.stopTask("\u2717  No previous report found");
+            if (!ui.isRich)
+                console.error("No previous report found for undo.");
+            process.exitCode = 1;
+            return;
+        }
+        ui.stopTask("\u2714  Report loaded");
+        ui.showDetection(report.detection);
+        const failed = entries.reduce((acc, e) => acc + e.failed.length, 0);
+        const restored = entries.reduce((acc, e) => acc + e.restored.length, 0);
+        const missing = entries.reduce((acc, e) => acc + e.missingSnapshot.length, 0);
+        const skipped = entries.reduce((acc, e) => acc + e.skipped.length, 0);
+        ui.showUndoResults(restored, skipped, missing, failed);
+        if (!ui.isRich) {
+            console.log(`Restored: ${restored}, Skipped: ${skipped}, Missing snapshot: ${missing}, Failed: ${failed}`);
+        }
+        const next = entries.find((e) => e.nextBestAction)?.nextBestAction ?? "Run auto-fix doctor to validate";
+        ui.outro(next);
+        if (!ui.isRich)
+            console.log(`Next: ${next}`);
+        return;
+    }
+    // ── report (read-only) ──
+    if (command === "report" && !flags.run) {
+        ui.intro("report");
+        const latest = await readJsonFile(path.join(reportDir, "latest.json"));
+        if (!latest) {
+            ui.showReportInfo("No report found at latest.json");
+            if (!ui.isRich)
+                console.error("No report found at latest.json");
+            process.exitCode = 1;
+            return;
+        }
+        if (flags.json) {
+            console.log(JSON.stringify(latest, null, 2));
+        }
+        else {
+            ui.showReportInfo("Report loaded. Use --json to print machine-readable output.");
+            if (!ui.isRich)
+                console.log("Use --json to print machine-readable report.");
+        }
+        ui.outro("auto-fix report --json");
+        return;
+    }
+    // ── run / doctor / plan ──
+    const effectiveCommand = command === "report" ? "run" : command;
+    ui.intro(effectiveCommand);
+    const callbacks = ui.isRich
+        ? {
+            onDetection: (det) => ui.showDetection(det),
+            onPlanReady: (steps) => {
+                if (effectiveCommand === "plan" || effectiveCommand === "doctor") {
+                    ui.showPlan(steps, effectiveCommand === "doctor" ? "Diagnosis" : undefined);
+                }
+            },
+            stepHooks: effectiveCommand === "run" ? ui.createStepHooks() : undefined,
+        }
+        : undefined;
+    const result = await runAutoFix({ ...ctx, command: effectiveCommand }, config, reportDir, callbacks);
+    const report = result.report;
+    await writeRunReport(report, reportDir);
+    if (ui.isRich) {
+        ui.showResults(report.summary);
+        ui.outro(report.summary.nextBestAction);
+    }
+    // Fallback text output for non-rich modes
+    if (!ui.isRich) {
+        if (flags.quiet) {
+            console.log(renderQuietSummary(report, !flags.noColor));
+        }
+        else {
+            console.log(renderSummary(report, !flags.noColor));
+        }
+    }
+    if (flags.json || command === "report") {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    if (effectiveCommand === "doctor" && report.detection.issues.length > 0) {
+        process.exitCode = 1;
+    }
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});