@technicalshree/auto-fix 1.1.4 → 1.2.0

package/dist/core/detectEnvironment.js

@@ -42,7 +42,7 @@ export async function detectEnvironment(cwd, config) {
         try {
             const parsed = JSON.parse(await readFile(packageJsonPath, "utf8"));
             scripts = Object.keys(parsed.scripts ?? {});
-            const deps = { ...(parsed.dependencies ?? {}), ...(parsed.devDependencies ?? {}) };
+            const deps = { ...parsed.dependencies, ...parsed.devDependencies };
             hasNext = Boolean(deps.next) || scripts.some((s) => s.toLowerCase().includes("next"));
             hasVite = Boolean(deps.vite) || scripts.some((s) => s.toLowerCase().includes("vite"));
         }
@@ -60,6 +60,11 @@ export async function detectEnvironment(cwd, config) {
     const lockfileCandidates = ["package-lock.json", "pnpm-lock.yaml", "yarn.lock"];
     const lockfiles = (await Promise.all(lockfileCandidates.map(async (name) => ((await fileExists(path.join(cwd, name))) ? name : null)))).filter((v) => Boolean(v));
     const lockfileCorrupted = await detectLockfileCorruption(cwd);
+    const hasEnv = await fileExists(path.join(cwd, ".env"));
+    const hasEnvExample = await fileExists(path.join(cwd, ".env.example"));
+    const nodeVersionCandidates = [".nvmrc", ".node-version"];
+    const nodeVersionFile = (await Promise.all(nodeVersionCandidates.map(async (name) => ((await fileExists(path.join(cwd, name))) ? name : null)))).find((v) => Boolean(v)) ?? undefined;
+    const pythonVersionFile = (await fileExists(path.join(cwd, ".python-version"))) ? ".python-version" : undefined;
     const issues = [];
     if (hasPackage && !(await fileExists(path.join(cwd, "node_modules"))))
         issues.push("node_modules directory missing");
@@ -69,6 +74,8 @@ export async function detectEnvironment(cwd, config) {
         issues.push("docker compose project detected (state may require refresh)");
     if (lockfileCorrupted)
         issues.push("lockfile appears corrupted; frozen installs likely to fail");
+    if (hasEnvExample && !hasEnv)
+        issues.push(".env file missing but .env.example exists");
     return {
         node: {
             detected: hasPackage,
@@ -88,6 +95,8 @@ export async function detectEnvironment(cwd, config) {
             venvExists,
         },
         docker: { detected: Boolean(composeFile), composeFile },
+        environment: { hasEnv, hasEnvExample },
+        engines: { nodeVersionFile, pythonVersionFile },
         issues,
     };
 }

package/dist/core/executor.js

@@ -75,8 +75,9 @@ export async function executeSteps(ctx, steps, snapshotDir, hooks) {
         }
         current.status = "running";
         hooks?.onStepStart(current);
-        if (step.destructive) {
-            const snaps = await snapshotPathsForStep(ctx.cwd, path.join(snapshotDir, ctx.runId), step.id, snapshotCandidates(step));
+        if (step.destructive || (step.snapshotPaths && step.snapshotPaths.length > 0)) {
+            const candidates = step.destructive ? snapshotCandidates(step) : step.snapshotPaths ?? [];
+            const snaps = await snapshotPathsForStep(ctx.cwd, path.join(snapshotDir, ctx.runId), step.id, candidates);
             current.snapshotPaths = snaps;
         }
         let failed = false;
@@ -112,7 +113,13 @@ export async function executeSteps(ctx, steps, snapshotDir, hooks) {
         current.output = commandOutputs.join("\n\n");
         if (failed) {
             current.status = "failed";
-            current.error = "One or more commands failed";
+            const combinedOutput = commandOutputs.join(" ");
+            if (/EPERM|EBUSY|EACCES/.test(combinedOutput) && (step.subsystem === "node" || step.phase === "node")) {
+                current.error = "Permission/lock error (EPERM/EBUSY). Close your IDE, dev servers, or file watchers and retry.";
+            }
+            else {
+                current.error = "One or more commands failed";
+            }
         }
         else {
             current.status = "success";

package/dist/core/planBuilder.js

@@ -2,6 +2,8 @@ import { buildNodeSteps } from "../subsystems/node.js";
 import { buildPythonSteps } from "../subsystems/python.js";
 import { buildDockerSteps } from "../subsystems/docker.js";
 import { buildCheckSteps } from "../subsystems/checks.js";
+import { buildEnvSteps } from "../subsystems/environment.js";
+import { buildEngineSteps } from "../subsystems/engines.js";
 export function buildPortSteps(flags, config) {
     if (!flags.killPorts)
         return [];
@@ -23,9 +25,11 @@ export function buildPortSteps(flags, config) {
         },
     ];
 }
-export function buildPlan(detection, config, flags) {
+export async function buildPlan(cwd, detection, config, flags) {
     const steps = [];
-    // strict order: ports -> docker -> node -> python -> checks(format, lint, test)
+    // strict order: env -> engines -> ports -> docker -> node -> python -> checks(format, lint, test)
+    steps.push(...await buildEnvSteps(cwd, detection, config, flags));
+    steps.push(...await buildEngineSteps(cwd, detection, config, flags));
     steps.push(...buildPortSteps(flags, config));
     if (flags.focus === "all" || flags.focus === "docker")
         steps.push(...buildDockerSteps(detection, config, flags));

package/dist/core/run.js

@@ -80,7 +80,7 @@ export async function runAutoFix(ctx, config, reportDir, callbacks) {
     if (!runAll) {
         ctx.flags.focus = "node";
     }
-    const plan = buildPlan(detection, config, ctx.flags);
+    const plan = await buildPlan(ctx.cwd, detection, config, ctx.flags);
     const guarded = applyPolyglotGuard(ctx, detection, plan);
     callbacks?.onPlanReady?.(guarded.steps);
     const desiredSnapshotDir = path.resolve(ctx.cwd, config.output.snapshot_dir);
@@ -94,6 +94,9 @@ export async function runAutoFix(ctx, config, reportDir, callbacks) {
         guarded.warnings.push("Added .autofix/ to .gitignore");
     if (!writable)
         guarded.warnings.push(`.autofix not writable; using temp snapshot dir: ${snapshotDir}`);
+    if (config.docker.safe_down && guarded.steps.some((s) => s.checkKind === "test")) {
+        guarded.warnings.push("Tests may require services; run `docker compose up -d` and re-run tests.");
+    }
     const report = {
         runId: ctx.runId,
         command: ctx.command,

package/dist/core/undo.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { cp } from "node:fs/promises";
+import { cp, mkdir } from "node:fs/promises";
 import { fileExists, readJsonFile } from "../utils/fs.js";
 export async function undoLatest(reportPath, cwd) {
     const report = await readJsonFile(reportPath);
@@ -29,9 +29,14 @@ export async function undoLatest(reportPath, cwd) {
                 missingSnapshot.push(snap);
                 continue;
             }
+            // The snapshot filename encodes the original relative path with separators replaced by `_`.
+            // Extract just the filename portion (after the stepId directory) and reverse the encoding.
             const base = path.basename(snap);
-            const target = path.join(cwd, base.replace(/_/g, "/"));
+            const relativePath = base.replace(/_/g, path.sep);
+            const target = path.join(cwd, relativePath);
             try {
+                const targetDir = path.dirname(target);
+                await mkdir(targetDir, { recursive: true });
                 await cp(snap, target, { recursive: true, force: true });
                 restored.push(target);
             }

package/dist/subsystems/engines.js

@@ -0,0 +1,55 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+async function readVersionFile(cwd, fileName) {
+    try {
+        const raw = await readFile(path.join(cwd, fileName), "utf8");
+        return raw.trim();
+    }
+    catch {
+        return null;
+    }
+}
+export async function buildEngineSteps(cwd, detection, config, flags) {
+    const steps = [];
+    if (detection.engines.nodeVersionFile) {
+        const desired = await readVersionFile(cwd, detection.engines.nodeVersionFile);
+        if (desired) {
+            const matchMajor = desired.replace(/^v/, "").split(".")[0];
+            const actualMajor = process.version.replace(/^v/, "").split(".")[0];
+            if (matchMajor !== actualMajor && matchMajor !== "") {
+                steps.push({
+                    id: "engines-node-version-mismatch",
+                    title: `Node version drift detected: expected ~${matchMajor}, running ${process.version}`,
+                    subsystem: "engines",
+                    phase: "engines",
+                    rationale: `Host Node.js version drifts from ${detection.engines.nodeVersionFile} definition.`,
+                    commands: [],
+                    destructive: false,
+                    irreversible: false,
+                    undoable: false,
+                    status: "proposed",
+                    proposedReason: `Run nvm use or switch Node versions to v${matchMajor}.x`,
+                });
+            }
+        }
+    }
+    if (detection.engines.pythonVersionFile) {
+        const desired = await readVersionFile(cwd, detection.engines.pythonVersionFile);
+        if (desired) {
+            steps.push({
+                id: "engines-python-version-mismatch",
+                title: `Python version drift: project expects ${desired}`,
+                subsystem: "engines",
+                phase: "engines",
+                rationale: `Host Python version should align with ${detection.engines.pythonVersionFile}.`,
+                commands: [],
+                destructive: false,
+                irreversible: false,
+                undoable: false,
+                status: "proposed",
+                proposedReason: `Verify your Python version matches ${desired}. Run: python3 --version`,
+            });
+        }
+    }
+    return steps;
+}

package/dist/subsystems/environment.js

@@ -0,0 +1,71 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+async function parseEnvKeys(filePath) {
+    try {
+        const raw = await readFile(filePath, "utf8");
+        const keys = [];
+        for (const line of raw.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#"))
+                continue;
+            const idx = trimmed.indexOf("=");
+            if (idx > 0) {
+                keys.push(trimmed.substring(0, idx).trim());
+            }
+        }
+        return keys;
+    }
+    catch {
+        return [];
+    }
+}
+async function findMissingKeys(envPath, envExamplePath) {
+    const envKeys = new Set(await parseEnvKeys(envPath));
+    const exampleKeys = await parseEnvKeys(envExamplePath);
+    return exampleKeys.filter((k) => !envKeys.has(k));
+}
+export async function buildEnvSteps(cwd, detection, config, flags) {
+    if (!detection.environment.hasEnvExample)
+        return [];
+    const steps = [];
+    const envPath = path.join(cwd, ".env");
+    const envExamplePath = path.join(cwd, ".env.example");
+    if (!detection.environment.hasEnv) {
+        steps.push({
+            id: "env-sync-copy-example",
+            title: "Copy .env.example to .env",
+            subsystem: "environment",
+            phase: "environment",
+            rationale: ".env is missing but .env.example exists.",
+            commands: [`cp ${envExamplePath} ${envPath}`],
+            destructive: false,
+            irreversible: false,
+            undoable: true,
+            snapshotPaths: [".env.example"], // Snapshot the example file as breadcrumb
+            undoHints: [{ action: "Delete .env", command: `rm -f ${envPath}` }],
+            status: "planned",
+        });
+    }
+    else {
+        const missingKeys = await findMissingKeys(envPath, envExamplePath);
+        if (missingKeys.length > 0) {
+            // Create a small shell script command to append missing keys safely
+            const appends = missingKeys.map((k) => `echo "${k}=" >> ${envPath}`).join(" && ");
+            steps.push({
+                id: "env-sync-append-missing",
+                title: `Append ${missingKeys.length} missing key(s) to .env`,
+                subsystem: "environment",
+                phase: "environment",
+                rationale: `.env is out of sync with .env.example (missing keys: ${missingKeys.join(", ")}).`,
+                commands: [appends],
+                destructive: false,
+                irreversible: false,
+                undoable: true,
+                snapshotPaths: [".env"],
+                undoHints: [{ action: "Restore original .env" }],
+                status: "planned",
+            });
+        }
+    }
+    return steps;
+}

package/dist/subsystems/node.js

@@ -110,7 +110,7 @@ export function buildNodeSteps(detection, config, flags) {
             title: "IRREVERSIBLE: Remove node_modules for clean reinstall",
             subsystem: "node",
             phase: "node",
-            rationale: "Deep cleanup requested to resolve dependency drift.",
+            rationale: "Deep cleanup requested. If this fails with EPERM, close your IDE or dev servers to release file locks.",
             commands: ["rm -rf node_modules", `${pm} install`],
             destructive: true,
             irreversible: true,

package/dist/subsystems/python.js

@@ -60,5 +60,26 @@ export function buildPythonSteps(detection, config, flags) {
             status: "planned",
         });
     }
+    // PRD v1.2: IDE Integration Auto-Configuration for VS Code
+    // Only sync when .venv exists or is being created by a preceding step
+    const venvWillExist = detection.python.venvExists || steps.some((s) => s.id === "python-create-venv");
+    if (venvWillExist) {
+        steps.push({
+            id: "python-vscode-sync",
+            title: "Sync Python virtual environment with VS Code",
+            subsystem: "python",
+            phase: "python",
+            rationale: "VS Code needs to know the correct virtual environment path to prevent linting errors.",
+            commands: [
+                `mkdir -p .vscode && node -e "const fs=require('fs');const p='.vscode/settings.json';let s={};try{s=JSON.parse(fs.readFileSync(p,'utf8'))}catch(e){}s['python.defaultInterpreterPath']='${config.python.venv_path}';fs.writeFileSync(p,JSON.stringify(s,null,2))"`
+            ],
+            destructive: false,
+            irreversible: false,
+            undoable: true,
+            snapshotPaths: [".vscode/settings.json"],
+            undoHints: [{ action: "Restore .vscode/settings.json" }],
+            status: "planned",
+        });
+    }
     return steps;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@technicalshree/auto-fix",
-  "version": "1.1.4",
+  "version": "1.2.0",
   "description": "Detect, diagnose, and safely fix common local dev environment issues",
   "main": "dist/cli.js",
   "repository": {