npm package: @omnihash/rollup-plugin-remove-files
Description: A safe Rollup plugin to remove files and directories using glob patterns and regex with built-in security features
Author: Your Name
Latest version: 1.0.0

# @omnihash/rollup-plugin-remove-files

A secure Rollup plugin that safely removes files and directories using regex patterns and explicit file paths. Built with security-first design to prevent accidental deletion of source files.

## Features

- 🛡️ **Security First**: Only allows deletion from build/dist directories by default
- 🎯 **Regex Support**: Use powerful regex patterns to match files
- 🚫 **Path Traversal Protection**: Prevents `../` attacks and escaping to parent directories
- 🧪 **Test Mode**: Preview what files would be deleted without actually removing them
- 📝 **Detailed Logging**: See exactly what's being removed and why operations are blocked
- ⚡ **Perfect Timing**: Runs after build completion when files actually exist
- 🔧 **Flexible Configuration**: Customize allowed directories and safety settings

## Installation

```bash
npm install @omnihash/rollup-plugin-remove-files --save-dev
```

## Quick Start

```javascript
import { defineConfig } from "rollup";
import remove from "@omnihash/rollup-plugin-remove-files";

export default defineConfig({
  input: "src/index.js",
  output: {
    file: "dist/bundle.js",
    format: "es",
  },
  plugins: [
    remove({
      patterns: [/\.map$/, /\.temp$/],
      logging: true,
    }),
  ],
});
```

## API Reference

### Options

| Option        | Type                                       | Default                                    | Description                               |
| ------------- | ------------------------------------------ | ------------------------------------------ | ----------------------------------------- |
| `filePaths`   | `string \| string[]`                       | `[]`                                       | Explicit file paths to remove             |
| `patterns`    | `RegExp \| RegExp[] \| string \| string[]` | `[]`                                       | Regex patterns to match files             |
| `allowedDirs` | `string[]`                                 | `['dist', 'build', 'out', '.next/static']` | Directories where deletion is allowed     |
| `baseDir`     | `string`                                   | `process.cwd()`                            | Base directory for relative paths         |
| `strictMode`  | `boolean`                                  | `true`                                     | Only allow deletion in `allowedDirs`      |
| `testRun`     | `boolean`                                  | `false`                                    | Preview mode - show what would be deleted |
| `logging`     | `boolean`                                  | `false`                                    | Enable detailed logging                   |

## Usage Examples

### Remove Source Maps

```javascript
remove({
  patterns: [/\.map$/],
  logging: true,
});
```

### Clean Up Temp Files

```javascript
remove({
  patterns: [/\.temp$/, /cache.*\.json$/],
  filePaths: ["dist/debug.log"],
  logging: true,
});
```

### Test Mode (Safe Preview)

```javascript
remove({
  patterns: [/\.test\./],
  testRun: true,
  logging: true,
});
// Output: [remove-files] Would remove: dist/app.test.js
```

### Custom Allowed Directories

```javascript
remove({
  patterns: [/\.log$/],
  allowedDirs: ["dist", "logs", "temp"],
  logging: true,
});
```

### Development vs Production

```javascript
const isProduction = process.env.NODE_ENV === "production";

remove({
  patterns: isProduction ? [/\.map$/, /\.test\./] : [],
  logging: !isProduction,
});
```

## Security Features

### Automatic Safety

- **Build Directory Detection**: Automatically allows deletion from Rollup's output directory
- **Path Traversal Protection**: Blocks `../` and absolute paths that could escape allowed directories
- **Whitelist Approach**: Only specified directories are allowed for deletion

### Safety Examples

```javascript
// ✅ SAFE - Within allowed directory
remove({
  filePaths: ["dist/temp.js"],
});

// ❌ BLOCKED - Outside allowed directory
remove({
  filePaths: ["../secret-file.txt"], // Path traversal blocked
});

// ❌ BLOCKED - Absolute path
remove({
  filePaths: ["/etc/passwd"], // Absolute path blocked
});
```

## Advanced Configuration

### Disable Strict Mode (Use with Caution)

```javascript
remove({
  filePaths: ["src/temp.js"], // Normally blocked
  strictMode: false, // Allows deletion outside allowedDirs
  logging: true, // Will show warnings
});
```

### Multiple Pattern Types

```javascript
remove({
  patterns: [
    /\.map$/, // RegExp
    ".*\\.temp", // String (converted to RegExp)
    /node_modules.*\\.log$/, // Complex pattern
  ],
});
```

## Integration Examples

### With TypeScript

```javascript
import { defineConfig } from "rollup";
import typescript from "@rollup/plugin-typescript";
import remove from "@omnihash/rollup-plugin-remove-files";

export default defineConfig({
  input: "src/index.ts",
  output: { dir: "dist", format: "es" },
  plugins: [
    typescript(),
    remove({
      patterns: [/\.tsbuildinfo$/, /\.d\.ts\.map$/],
      logging: true,
    }),
  ],
});
```

### With Vite (Rollup-based)

```javascript
import { defineConfig } from "vite";
import remove from "@omnihash/rollup-plugin-remove-files";

export default defineConfig({
  build: {
    rollupOptions: {
      plugins: [
        remove({
          patterns: [/\.map$/],
          testRun: process.env.NODE_ENV !== "production",
        }),
      ],
    },
  },
});
```

## Error Handling

The plugin gracefully handles errors and provides clear feedback:

```javascript
removeFiles({
  filePaths: ["nonexistent.js"],
  logging: true,
});
// Output: [remove-files] File not found: /path/to/nonexistent.js
```

## Contributing

1. Fork the repository
2. Create your feature branch: `git checkout -b feat/amazing-feature`
3. Commit your changes: `git commit -m 'Add amazing feature'`
4. Push to the branch: `git push origin feat/amazing-feature`
5. Open a Pull Request

## License

MIT © [Your Name]

## Changelog

### 1.0.0

- Initial release
- Regex pattern support
- Security-first design
- Test mode
- Comprehensive logging