@technicalshree/auto-fix 1.2.1 → 1.2.4

package/README.md

@@ -166,6 +166,56 @@ 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.
+
+```bash
+# 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.
+
+```bash
+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]`

package/dist/cli.js

@@ -78,15 +78,20 @@ function parseArgs(argv) {
     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 knownCommands = ["doctor", "plan", "report", "undo", "clear-npm-cache", "clear-yarn-cache", "clear-pnpm-cache", "run"];
+    let command;
+    if (first === "doctor" || first === "plan" || first === "report" || first === "undo" ||
+        first === "clear-npm-cache" || first === "clear-yarn-cache" || first === "clear-pnpm-cache") {
+        command = first;
+    }
+    else if (first === "run" || first.startsWith("-")) {
+        command = "run";
+    }
+    else {
+        // REL-001: Unknown command — fail explicitly instead of silent fallback to `run`
+        console.error(`Unknown command: "${first}"\nAvailable commands: ${knownCommands.join(", ")}\nRun 'auto-fix --help' for usage information.`);
+        process.exit(1);
+    }
     const args = command === "run" ? argv : rest;
     const flags = defaultFlags();
     for (let i = 0; i < args.length; i += 1) {

package/dist/config/loadConfig.js

@@ -34,11 +34,49 @@ async function findConfigPath(cwd) {
         current = parent;
     }
 }
+/** Allowlist pattern for safe characters in config command/path strings */
+const SAFE_CHARS_RE = /^[a-zA-Z0-9._\-/@:=*\s]+$/;
+/** Known dev tool binaries that are safe to auto-execute */
+const KNOWN_TOOL_BINARIES = new Set([
+    "ruff", "black", "autopep8", "yapf", "isort", "pyink",
+    "flake8", "pylint", "pyflakes", "pydocstyle", "pycodestyle", "bandit", "vulture",
+    "mypy", "pyright", "pytype", "pyre",
+    "pytest", "unittest", "nose2", "tox", "nox", "coverage",
+    "pip", "uv", "poetry", "pipenv", "pdm",
+    "python", "python3", "pre-commit", "sphinx-build",
+    "npm", "npx", "pnpm", "yarn",
+]);
+function isSafeConfigCommand(cmd) {
+    if (!SAFE_CHARS_RE.test(cmd))
+        return false;
+    const binary = cmd.trim().split(/\s+/)[0].replace(/^.*\//, "");
+    return KNOWN_TOOL_BINARIES.has(binary);
+}
+/**
+ * REL-004: Defense-in-depth — strip unsafe values from config at load time.
+ * Uses character allowlist + known binary allowlist to prevent arbitrary command execution.
+ */
+function sanitizeConfig(config) {
+    // Sanitize python tool command arrays
+    if (config.python?.tools) {
+        config.python.tools.format = config.python.tools.format.filter(isSafeConfigCommand);
+        config.python.tools.lint = config.python.tools.lint.filter(isSafeConfigCommand);
+        config.python.tools.test = config.python.tools.test.filter(isSafeConfigCommand);
+    }
+    // Sanitize node cache directory names (path-only, no binary check needed)
+    if (config.node?.caches?.directories) {
+        config.node.caches.directories = config.node.caches.directories.filter((d) => SAFE_CHARS_RE.test(d) && !d.includes(".."));
+    }
+    return config;
+}
 export async function loadConfig(cwd) {
     const cfgPath = await findConfigPath(cwd);
     if (!cfgPath)
         return { config: defaultConfig, path: null };
     const raw = await readFile(cfgPath, "utf8");
     const user = parse(raw);
-    return { config: mergeDeep(defaultConfig, user), path: cfgPath };
+    if (!user || typeof user !== "object")
+        return { config: defaultConfig, path: cfgPath };
+    const merged = mergeDeep(defaultConfig, user);
+    return { config: sanitizeConfig(merged), path: cfgPath };
 }

package/dist/core/run.js

@@ -94,7 +94,7 @@ 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")) {
+    if (detection.docker.detected && 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 = {

package/dist/core/undo.js

@@ -33,7 +33,13 @@ export async function undoLatest(reportPath, cwd) {
             // Extract just the filename portion (after the stepId directory) and reverse the encoding.
             const base = path.basename(snap);
             const relativePath = base.replace(/_/g, path.sep);
-            const target = path.join(cwd, relativePath);
+            const target = path.resolve(cwd, relativePath);
+            // SEC-002: Containment check — reject any path that escapes project root
+            const normalizedCwd = path.resolve(cwd) + path.sep;
+            if (!target.startsWith(normalizedCwd) && target !== path.resolve(cwd)) {
+                failed.push(`${target} (blocked: path traversal outside project root)`);
+                continue;
+            }
             try {
                 const targetDir = path.dirname(target);
                 await mkdir(targetDir, { recursive: true });

package/dist/subsystems/checks.js

@@ -50,12 +50,71 @@ function nodeChecks(detection, selected) {
     }
     return steps;
 }
+/**
+ * REL-004: Known tool binary allowlist.
+ * Only commands starting with a recognized dev tool will be auto-executed.
+ * Unrecognized binaries (touch, rm, curl, wget, etc.) are rejected.
+ */
+const KNOWN_TOOL_BINARIES = new Set([
+    // Python formatters
+    "ruff", "black", "autopep8", "yapf", "isort", "pyink",
+    // Python linters
+    "flake8", "pylint", "pyflakes", "pydocstyle", "pycodestyle", "bandit", "vulture",
+    // Python type checkers
+    "mypy", "pyright", "pytype", "pyre",
+    // Python test runners
+    "pytest", "unittest", "nose2", "tox", "nox", "coverage",
+    // Python package managers (used as runner)
+    "pip", "uv", "poetry", "pipenv", "pdm",
+    // Python misc
+    "python", "python3", "pre-commit", "sphinx-build",
+    // Node tools (in case used in python context)
+    "npm", "npx", "pnpm", "yarn",
+]);
+/**
+ * REL-004: Validate a config-sourced command string.
+ * Two checks:
+ * 1. Character allowlist — rejects shell metacharacters
+ * 2. Binary allowlist — first token must be a known dev tool
+ */
+function isSafeCommand(cmd) {
+    if (!cmd || cmd.trim().length === 0)
+        return { safe: false, reason: "Empty command" };
+    // Check 1: Character-level safety (no shell metacharacters)
+    if (!/^[a-zA-Z0-9._\-/@:=*\s]+$/.test(cmd)) {
+        return { safe: false, reason: `contains shell metacharacters` };
+    }
+    // Check 2: First token must be a known tool binary
+    const binary = cmd.trim().split(/\s+/)[0].replace(/^.*\//, ""); // strip leading path
+    if (!KNOWN_TOOL_BINARIES.has(binary)) {
+        return { safe: false, reason: `unrecognized tool '${binary}'` };
+    }
+    return { safe: true, reason: "" };
+}
 function pythonChecks(detection, config, selected) {
     if (!detection.python.detected)
         return [];
     const steps = [];
     if (selected.includes("format")) {
         for (const cmd of config.python.tools.format) {
+            const validation = isSafeCommand(cmd);
+            if (!validation.safe) {
+                steps.push({
+                    id: `check-python-format-${cmd.replace(/[^a-z0-9]/gi, "-")}`,
+                    title: `SKIPPED: Rejected format command: ${cmd}`,
+                    subsystem: "checks",
+                    phase: "checks",
+                    checkKind: "format",
+                    rationale: `Config command rejected: ${validation.reason}.`,
+                    commands: [],
+                    destructive: false,
+                    irreversible: false,
+                    undoable: false,
+                    status: "proposed",
+                    proposedReason: `Command '${cmd}' was rejected (${validation.reason}). Only known dev tools are auto-executed. Run manually if needed.`,
+                });
+                continue;
+            }
             steps.push({
                 id: `check-python-format-${cmd.replace(/[^a-z0-9]/gi, "-")}`,
                 title: `Run Python format: ${cmd}`,
@@ -73,6 +132,24 @@ function pythonChecks(detection, config, selected) {
     }
     if (selected.includes("lint")) {
         for (const cmd of config.python.tools.lint) {
+            const validation = isSafeCommand(cmd);
+            if (!validation.safe) {
+                steps.push({
+                    id: `check-python-lint-${cmd.replace(/[^a-z0-9]/gi, "-")}`,
+                    title: `SKIPPED: Rejected lint command: ${cmd}`,
+                    subsystem: "checks",
+                    phase: "checks",
+                    checkKind: "lint",
+                    rationale: `Config command rejected: ${validation.reason}.`,
+                    commands: [],
+                    destructive: false,
+                    irreversible: false,
+                    undoable: false,
+                    status: "proposed",
+                    proposedReason: `Command '${cmd}' was rejected (${validation.reason}). Only known dev tools are auto-executed. Run manually if needed.`,
+                });
+                continue;
+            }
             steps.push({
                 id: `check-python-lint-${cmd.replace(/[^a-z0-9]/gi, "-")}`,
                 title: `Run Python lint: ${cmd}`,
@@ -90,6 +167,24 @@ function pythonChecks(detection, config, selected) {
     }
     if (selected.includes("test")) {
         for (const cmd of config.python.tools.test) {
+            const validation = isSafeCommand(cmd);
+            if (!validation.safe) {
+                steps.push({
+                    id: `check-python-test-${cmd.replace(/[^a-z0-9]/gi, "-")}`,
+                    title: `SKIPPED: Rejected test command: ${cmd}`,
+                    subsystem: "checks",
+                    phase: "checks",
+                    checkKind: "test",
+                    rationale: `Config command rejected: ${validation.reason}.`,
+                    commands: [],
+                    destructive: false,
+                    irreversible: false,
+                    undoable: false,
+                    status: "proposed",
+                    proposedReason: `Command '${cmd}' was rejected (${validation.reason}). Only known dev tools are auto-executed. Run manually if needed.`,
+                });
+                continue;
+            }
             steps.push({
                 id: `check-python-test-${cmd.replace(/[^a-z0-9]/gi, "-")}`,
                 title: `Run Python tests: ${cmd}`,

package/dist/subsystems/environment.js

@@ -1,5 +1,10 @@
 import path from "node:path";
 import { readFile } from "node:fs/promises";
+import { shellQuote } from "../utils/process.js";
+/** Strict env key sanitizer: only allow [A-Z0-9_] */
+function sanitizeEnvKey(key) {
+    return key.replace(/[^A-Z0-9_]/gi, "");
+}
 async function parseEnvKeys(filePath) {
     try {
         const raw = await readFile(filePath, "utf8");
@@ -10,7 +15,9 @@ async function parseEnvKeys(filePath) {
                 continue;
             const idx = trimmed.indexOf("=");
             if (idx > 0) {
-                keys.push(trimmed.substring(0, idx).trim());
+                const key = sanitizeEnvKey(trimmed.substring(0, idx).trim());
+                if (key)
+                    keys.push(key);
             }
         }
         return keys;
@@ -37,20 +44,20 @@ export async function buildEnvSteps(cwd, detection, config, flags) {
             subsystem: "environment",
             phase: "environment",
             rationale: ".env is missing but .env.example exists.",
-            commands: [`cp ${envExamplePath} ${envPath}`],
+            commands: [`cp ${shellQuote(envExamplePath)} ${shellQuote(envPath)}`],
             destructive: false,
             irreversible: false,
             undoable: true,
-            snapshotPaths: [".env.example"], // Snapshot the example file as breadcrumb
-            undoHints: [{ action: "Delete .env", command: `rm -f ${envPath}` }],
+            snapshotPaths: [".env.example"],
+            undoHints: [{ action: "Delete .env", command: `rm -f ${shellQuote(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(" && ");
+            // Keys are already sanitized to [A-Z0-9_] only — safe for shell interpolation
+            const appends = missingKeys.map((k) => `echo ${shellQuote(`${k}=`)} >> ${shellQuote(envPath)}`).join(" && ");
             steps.push({
                 id: "env-sync-append-missing",
                 title: `Append ${missingKeys.length} missing key(s) to .env`,

package/dist/subsystems/node.js

@@ -1,6 +1,10 @@
+import { isSafePath, shellQuote } from "../utils/process.js";
+const ALLOWED_PMS = new Set(["npm", "pnpm", "yarn"]);
 function choosePm(detected, configured) {
-    if (configured !== "auto")
-        return configured;
+    if (configured !== "auto") {
+        // SEC-001: Validate package_manager from config against strict allowlist
+        return ALLOWED_PMS.has(configured) ? configured : "npm";
+    }
     if (detected === "unknown")
         return "npm";
     return detected;
@@ -91,13 +95,29 @@ export function buildNodeSteps(detection, config, flags) {
         });
     }
     for (const cacheDir of config.node.caches.directories) {
+        if (!isSafePath(cacheDir)) {
+            steps.push({
+                id: `node-clean-cache-${cacheDir.replace(/[^a-z0-9]/gi, "-")}`,
+                title: `SKIPPED: Unsafe cache directory name: ${cacheDir}`,
+                subsystem: "node",
+                phase: "node",
+                rationale: "Cache directory name contains suspicious characters and was rejected for safety.",
+                commands: [],
+                destructive: false,
+                irreversible: false,
+                undoable: false,
+                status: "proposed",
+                proposedReason: `Directory name '${cacheDir}' contains shell metacharacters. Rename it or clean manually.`,
+            });
+            continue;
+        }
         steps.push({
             id: `node-clean-cache-${cacheDir.replace(/[^a-z0-9]/gi, "-")}`,
             title: `Clean cache directory ${cacheDir}`,
             subsystem: "node",
             phase: "node",
             rationale: "Configured cache directory cleanup.",
-            commands: [`rm -rf ${cacheDir}`],
+            commands: [`rm -rf ${shellQuote(cacheDir)}`],
             destructive: false,
             irreversible: false,
             undoable: false,

package/dist/subsystems/python.js

@@ -1,3 +1,4 @@
+import { shellQuote } from "../utils/process.js";
 function installCommand(prefer) {
     switch (prefer) {
         case "uv":
@@ -16,6 +17,7 @@ export function buildPythonSteps(detection, config, flags) {
     if (!detection.python.detected)
         return [];
     const steps = [];
+    const quotedVenv = shellQuote(config.python.venv_path);
     if (!detection.python.venvExists) {
         steps.push({
             id: "python-create-venv",
@@ -23,7 +25,7 @@ export function buildPythonSteps(detection, config, flags) {
             subsystem: "python",
             phase: "python",
             rationale: "Python project detected without configured virtual environment.",
-            commands: [`python3 -m venv ${config.python.venv_path}`],
+            commands: [`python3 -m venv ${quotedVenv}`],
             destructive: false,
             irreversible: false,
             undoable: false,
@@ -51,7 +53,7 @@ export function buildPythonSteps(detection, config, flags) {
             subsystem: "python",
             phase: "python",
             rationale: "Deep cleanup for persistent Python environment drift.",
-            commands: [`rm -rf ${config.python.venv_path}`, `python3 -m venv ${config.python.venv_path}`],
+            commands: [`rm -rf ${quotedVenv}`, `python3 -m venv ${quotedVenv}`],
             destructive: true,
             irreversible: true,
             irreversibleReason: "cannot restore environment state fully",
@@ -62,8 +64,10 @@ export function buildPythonSteps(detection, config, flags) {
     }
     // PRD v1.2: IDE Integration Auto-Configuration for VS Code
     // Only sync when .venv exists or is being created by a preceding step
+    // REL-002: Skip write if existing settings.json can't be parsed (JSONC) to avoid clobbering
     const venvWillExist = detection.python.venvExists || steps.some((s) => s.id === "python-create-venv");
     if (venvWillExist) {
+        const escapedVenv = config.python.venv_path.replace(/'/g, "\\'");
         steps.push({
             id: "python-vscode-sync",
             title: "Sync Python virtual environment with VS Code",
@@ -71,7 +75,7 @@ export function buildPythonSteps(detection, config, flags) {
             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))"`
+                `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){if(fs.existsSync(p)){console.log('SKIP: settings.json exists but is not valid JSON (may contain comments). Skipping to preserve your config.');process.exit(0)}s={}}s['python.defaultInterpreterPath']='${escapedVenv}';fs.writeFileSync(p,JSON.stringify(s,null,2))"`
             ],
             destructive: false,
             irreversible: false,

package/dist/utils/process.js

@@ -1,7 +1,14 @@
-import { exec } from "node:child_process";
+import { execFile } from "node:child_process";
+/**
+ * Run a command safely through the system shell.
+ * Uses execFile with explicit ["-c", command] to avoid direct shell string injection
+ * while still supporting piped/chained commands that subsystems require.
+ */
 export function runShellCommand(command, cwd) {
+    const shell = process.platform === "win32" ? "cmd.exe" : "/bin/sh";
+    const shellArgs = process.platform === "win32" ? ["/c", command] : ["-c", command];
     return new Promise((resolve) => {
-        exec(command, { cwd, maxBuffer: 1024 * 1024 * 4 }, (error, stdout, stderr) => {
+        execFile(shell, shellArgs, { cwd, maxBuffer: 1024 * 1024 * 4, encoding: "utf8" }, (error, stdout, stderr) => {
             if (error) {
                 resolve({
                     success: false,
@@ -15,3 +22,18 @@ export function runShellCommand(command, cwd) {
         });
     });
 }
+/**
+ * Shell-quote a string value for safe interpolation into shell commands.
+ * Wraps in single quotes and escapes embedded single quotes.
+ */
+export function shellQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * Validate a string against a strict safe-path pattern.
+ * Only allows alphanumeric, dots, dashes, underscores, and forward slashes.
+ * Rejects shell metacharacters like ;|&`$(){}
+ */
+export function isSafePath(value) {
+    return /^[a-zA-Z0-9._\-/]+$/.test(value) && !value.includes("..");
+}

package/package.json

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