synced-folder-guard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdelrahman Farag
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# synced-folder-guard
+
+> Stop wasting an hour on `EPERM` / `EBADF` / `TAR_BAD_ARCHIVE` errors. This tool warns you **before** you install packages inside a cloud-synced folder.
+
+Running `npm install` (or `pip`, `cargo`, `yarn`, `pnpm`) inside **Google Drive**, **OneDrive**, **Dropbox**, or **iCloud Drive** is one of the most confusing failures in dev tooling. The sync client fights the package manager for the same files mid-write, and you get a wall of errors like:
+
+```
+npm warn tar TAR_BAD_ARCHIVE: Unrecognized archive format
+npm warn tar TAR_ENTRY_ERROR EBADF: bad file descriptor, write
+npm warn tar TAR_ENTRY_ERROR EPERM: operation not permitted, write
+Error: Cannot find module 'ajv'
+```
+
+Every guide tells you the same thing — *after* you've already lost the time: "clear your cache, delete `node_modules`, move the project." `synced-folder-guard` flips that: it tells you **before** the install, in one second.
+
+## Install
+
+```bash
+npm install -g synced-folder-guard
+```
+
+Or run it once with no install:
+
+```bash
+npx synced-folder-guard
+```
+
+## Usage
+
+Check the current folder:
+
+```bash
+synced-folder-guard          # or the short alias: sfg
+```
+
+If you're safe:
+
+```
+OK  not in a cloud-synced folder: C:\Users\you\repos\my-app
+```
+
+If you're not:
+
+```
+WARNING  this folder is inside a cloud-synced location.
+
+  Path:     G:\My Drive\repos\my-app
+  Provider: Google Drive
+    - Google Drive (folder name "My Drive")
+
+  Installing packages here often fails or silently corrupts, with errors like:
+    EPERM, EBADF, ENOENT, TAR_BAD_ARCHIVE, "Unrecognized archive format"
+
+  Fix: move this project to a non-synced folder (e.g. a local repos dir),
+       or pause syncing for the duration of the install.
+```
+
+Check a specific path:
+
+```bash
+synced-folder-guard "G:\My Drive\repos\my-app"
+```
+
+## Guard your installs automatically
+
+Add it as a `preinstall` script so a bad location can never bite you again:
+
+```json
+{
+  "scripts": {
+    "preinstall": "synced-folder-guard --fail"
+  }
+}
+```
+
+With `--fail`, the install aborts (exit code `1`) when the project lives in a synced folder.
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `-f`, `--fail` | Exit with code `1` if the folder is synced (use in `preinstall`) |
+| `--json` | Machine-readable JSON output |
+| `-q`, `--quiet` | Print nothing when the folder is safe |
+| `--no-color` | Disable colored output |
+| `-h`, `--help` | Show help |
+| `-v`, `--version` | Show version |
+
+## Use as a library
+
+```js
+const { detect } = require('synced-folder-guard');
+
+const result = detect(process.cwd());
+// {
+//   path: 'G:\\My Drive\\repos\\my-app',
+//   synced: true,
+//   matches: [{ provider: 'Google Drive', via: 'folder name "My Drive"' }]
+// }
+
+if (result.synced) {
+  console.warn(`Heads up: ${result.matches[0].provider} folder detected.`);
+}
+```
+
+## What it detects
+
+| Provider | How |
+|----------|-----|
+| **Google Drive** | `My Drive`, `Shared drives`, `Google Drive`, `GoogleDrive-*` (macOS CloudStorage) folder names |
+| **OneDrive** | `$OneDrive` / `$OneDriveCommercial` / `$OneDriveConsumer` env vars, and `OneDrive` / `OneDrive - Company` folder names |
+| **Dropbox** | Real folder location read from Dropbox's own `info.json`, plus the `Dropbox` folder name |
+| **iCloud Drive** | `Mobile Documents` / `com~apple~CloudDocs` folder names |
+
+Detection is segment-boundary aware, so a folder like `MyDropboxNotes` is **not** a false positive.
+
+## Why this happens
+
+Cloud sync clients use placeholder/virtual files and aggressively lock files to upload them. Package managers extract thousands of small files and rename them rapidly. When both touch the same file at the same moment, the write fails — sometimes loudly (`EPERM`), sometimes silently (a half-extracted tarball that breaks `require` later). The only reliable fix is to keep `node_modules` out of the synced folder entirely.
+
+## Zero dependencies
+
+Pure Node, no runtime dependencies. Works on Windows, macOS, and Linux. Node `>=16`.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+'use strict';
+
+const { detect } = require('../src/detect');
+const pkg = require('../package.json');
+
+const ESC = String.fromCharCode(27);
+
+// ASCII-only output: Windows terminals (the main audience here) mangle emoji
+// and box-drawing glyphs, so we deliberately avoid them.
+function makeColor(enabled) {
+  const wrap = (code) => (s) => (enabled ? `${ESC}[${code}m${s}${ESC}[0m` : s);
+  return {
+    bold: wrap('1'),
+    red: wrap('31'),
+    yellow: wrap('33'),
+    green: wrap('32'),
+    dim: wrap('2'),
+  };
+}
+
+function parseArgs(argv) {
+  const opts = { fail: false, json: false, quiet: false, color: null, path: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === 'check') continue;
+    else if (a === '--fail' || a === '-f') opts.fail = true;
+    else if (a === '--json') opts.json = true;
+    else if (a === '--quiet' || a === '-q') opts.quiet = true;
+    else if (a === '--no-color') opts.color = false;
+    else if (a === '--color') opts.color = true;
+    else if (a === '--help' || a === '-h') opts.help = true;
+    else if (a === '--version' || a === '-v') opts.version = true;
+    else if (a.startsWith('-')) {
+      process.stderr.write(`Unknown option: ${a}\n`);
+      opts.help = true;
+    } else if (opts.path === null) {
+      opts.path = a;
+    }
+  }
+  return opts;
+}
+
+const HELP = `synced-folder-guard v${pkg.version}
+
+Warns BEFORE a package install corrupts inside a cloud-synced folder
+(Google Drive, OneDrive, Dropbox, iCloud).
+
+Usage:
+  synced-folder-guard [check] [path]   Check a path (default: current folder)
+  sfg [check] [path]                   Short alias
+
+Options:
+  -f, --fail      Exit with code 1 if the folder is synced (use in preinstall)
+      --json      Output machine-readable JSON
+  -q, --quiet     Print nothing when the folder is safe
+      --no-color  Disable colored output
+  -h, --help      Show this help
+  -v, --version   Show version
+
+Use as a guard in package.json:
+  "scripts": { "preinstall": "synced-folder-guard --fail" }
+`;
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  if (opts.help) {
+    process.stdout.write(HELP);
+    process.exit(0);
+  }
+  if (opts.version) {
+    process.stdout.write(`${pkg.version}\n`);
+    process.exit(0);
+  }
+
+  const colorEnabled =
+    opts.color !== null ? opts.color : Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+  const c = makeColor(colorEnabled);
+
+  const result = detect(opts.path || process.cwd());
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    process.exit(opts.fail && result.synced ? 1 : 0);
+  }
+
+  if (!result.synced) {
+    if (!opts.quiet) {
+      process.stdout.write(`${c.green('OK')}  not in a cloud-synced folder: ${result.path}\n`);
+    }
+    process.exit(0);
+  }
+
+  const providers = result.matches.map((m) => m.provider).join(', ');
+  const lines = [];
+  lines.push('');
+  lines.push(`${c.bold(c.yellow('WARNING'))}  this folder is inside a cloud-synced location.`);
+  lines.push('');
+  lines.push(`  ${c.bold('Path:')}     ${result.path}`);
+  lines.push(`  ${c.bold('Provider:')} ${providers}`);
+  for (const m of result.matches) {
+    const root = m.root ? `, root: ${m.root}` : '';
+    lines.push(`    ${c.dim(`- ${m.provider} (${m.via}${root})`)}`);
+  }
+  lines.push('');
+  lines.push('  Installing packages here often fails or silently corrupts, with errors like:');
+  lines.push(`    ${c.dim('EPERM, EBADF, ENOENT, TAR_BAD_ARCHIVE, "Unrecognized archive format"')}`);
+  lines.push('');
+  lines.push(`  ${c.bold('Fix:')} move this project to a non-synced folder (e.g. a local repos dir),`);
+  lines.push('       or pause syncing for the duration of the install.');
+  lines.push('');
+
+  process.stdout.write(lines.join('\n') + '\n');
+
+  process.exit(opts.fail ? 1 : 0);
+}
+
+main();

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "synced-folder-guard",
+  "version": "0.1.0",
+  "description": "Warns you BEFORE npm/pip/cargo installs corrupt inside a cloud-synced folder (Google Drive, OneDrive, Dropbox, iCloud). Stops EPERM/EBADF/TAR_BAD_ARCHIVE errors before they cost you an hour.",
+  "type": "commonjs",
+  "main": "src/detect.js",
+  "bin": {
+    "synced-folder-guard": "bin/cli.js",
+    "sfg": "bin/cli.js"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "npm",
+    "onedrive",
+    "google-drive",
+    "dropbox",
+    "icloud",
+    "cloud-sync",
+    "synced-folder",
+    "eperm",
+    "ebadf",
+    "tar_bad_archive",
+    "preinstall",
+    "node_modules",
+    "guard",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "author": "Abdelrahman Farag",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ahafarag/synced-folder-guard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ahafarag/synced-folder-guard/issues"
+  },
+  "homepage": "https://github.com/ahafarag/synced-folder-guard#readme"
+}

package/src/detect.js

@@ -0,0 +1,122 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+// Split a path into segments, tolerant of both / and \ separators so the
+// same logic works regardless of host platform.
+function segs(p) {
+  return String(p).split(/[\\/]+/).filter(Boolean);
+}
+
+// True when childSegs is contained within parentSegs (segment-boundary safe,
+// so "C:\\MyDropboxNotes" is NOT treated as inside "C:\\...\\Dropbox").
+function isInsideSegs(childSegs, parentSegs, caseInsensitive) {
+  if (parentSegs.length === 0 || childSegs.length < parentSegs.length) return false;
+  for (let i = 0; i < parentSegs.length; i++) {
+    const a = caseInsensitive ? childSegs[i].toLowerCase() : childSegs[i];
+    const b = caseInsensitive ? parentSegs[i].toLowerCase() : parentSegs[i];
+    if (a !== b) return false;
+  }
+  return true;
+}
+
+// Detection based purely on folder names that cloud providers use. This is the
+// catch-all that works cross-platform without needing the provider installed.
+function heuristicMatches(segments) {
+  const matches = [];
+  for (const seg of segments) {
+    const low = seg.toLowerCase();
+    if (low === 'my drive' || low === 'shared drives' || low === 'google drive' || low.startsWith('googledrive-')) {
+      matches.push({ provider: 'Google Drive', via: `folder name "${seg}"` });
+    } else if (low === 'onedrive' || low.startsWith('onedrive -') || low.startsWith('onedrive-')) {
+      matches.push({ provider: 'OneDrive', via: `folder name "${seg}"` });
+    } else if (low === 'dropbox') {
+      matches.push({ provider: 'Dropbox', via: `folder name "${seg}"` });
+    } else if (low === 'mobile documents' || low.startsWith('com~apple~clouddocs')) {
+      matches.push({ provider: 'iCloud Drive', via: `folder name "${seg}"` });
+    }
+  }
+  return matches;
+}
+
+// OneDrive exports its synced root(s) as environment variables on Windows.
+function envRoots(env) {
+  const roots = [];
+  for (const key of ['OneDrive', 'OneDriveConsumer', 'OneDriveCommercial']) {
+    if (env[key]) roots.push({ provider: 'OneDrive', root: env[key], via: `env $${key}` });
+  }
+  return roots;
+}
+
+// Dropbox records its real folder location(s) in info.json. Reading it is the
+// most accurate way to detect a Dropbox folder regardless of where it lives.
+function dropboxRoots(env, home, readFile) {
+  const candidates = [];
+  if (env.APPDATA) candidates.push(path.join(env.APPDATA, 'Dropbox', 'info.json'));
+  if (env.LOCALAPPDATA) candidates.push(path.join(env.LOCALAPPDATA, 'Dropbox', 'info.json'));
+  candidates.push(path.join(home, '.dropbox', 'info.json'));
+
+  const roots = [];
+  for (const file of candidates) {
+    let raw;
+    try {
+      raw = readFile(file);
+    } catch {
+      continue;
+    }
+    if (!raw) continue;
+    let json;
+    try {
+      json = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    for (const account of Object.keys(json)) {
+      const root = json[account] && json[account].path;
+      if (root) roots.push({ provider: 'Dropbox', root, via: `Dropbox config (${account})` });
+    }
+  }
+  return roots;
+}
+
+// Inspect a path and report whether it sits inside a known cloud-synced folder.
+// Dependencies (env, home, platform, file reader) are injectable for testing.
+function detect(targetPath, opts = {}) {
+  const platform = opts.platform || process.platform;
+  const env = opts.env || process.env;
+  const home = opts.home || os.homedir();
+  const readFile = opts.readFile || ((f) => fs.readFileSync(f, 'utf8'));
+  const caseInsensitive = platform === 'win32';
+
+  const resolved = path.resolve(targetPath || opts.cwd || process.cwd());
+  const targetSegs = segs(resolved);
+
+  const matches = [];
+
+  const concreteRoots = [...envRoots(env), ...dropboxRoots(env, home, readFile)];
+  for (const r of concreteRoots) {
+    if (isInsideSegs(targetSegs, segs(path.resolve(r.root)), caseInsensitive)) {
+      matches.push({ provider: r.provider, root: path.resolve(r.root), via: r.via });
+    }
+  }
+
+  for (const m of heuristicMatches(targetSegs)) matches.push(m);
+
+  const seen = new Set();
+  const deduped = [];
+  for (const m of matches) {
+    if (seen.has(m.provider)) continue;
+    seen.add(m.provider);
+    deduped.push(m);
+  }
+
+  return {
+    path: resolved,
+    synced: deduped.length > 0,
+    matches: deduped,
+  };
+}
+
+module.exports = { detect, segs, isInsideSegs, heuristicMatches, envRoots, dropboxRoots };