binary-collections 2.0.12 → 2.0.14

package/docs-src/node-cache-cleaner.md

@@ -0,0 +1,182 @@
+## Node Cache Cleaner
+
+Cleans NPM, Yarn, and NPX caches in parallel.
+
+### Usage
+
+```bash
+node-cache-cleaner [options]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-h, --help` | Show help message |
+
+### Description
+
+- Runs `npm cache clean --force` to clean the NPM cache
+- Runs `yarn cache clean` (or `yarn cache clean --all` for Yarn Berry) to clean the Yarn cache
+- Removes `_npx`, `_cacache`, and `.cache/npx` directories to clean the NPX cache
+- All cache cleaning operations run in parallel via `Promise.allSettled`
+- Exits with code 0 on success, or 1 if any cache clean operation fails
+
+### Source
+
+See [`src/node-cache-cleaner-cli.ts`](../src/node-cache-cleaner-cli.ts).
+
+---
+
+## Yarn Cache Cleaner (Python)
+
+Python-based utility to clean Yarn caches.
+
+### Usage
+
+```bash
+yarn-clean
+```
+
+### Description
+
+Runs `yarn-clean.py` which locates and cleans Yarn cache directories. Available as a shell wrapper in both bash and batch variants.
+
+### Source
+
+See [`bin/yarn-clean`](../bin/yarn-clean) & [`bin/yarn-clean.py`](../bin/yarn-clean.py)
+
+---
+
+## yc / ycw
+
+Shell scripts to clean `node_modules` directories in parallel.
+
+### Usage
+
+```bash
+yc [options]
+ycw [options]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-h, --help` | Show help message |
+| `-c, --concurrent <num>` | Maximum parallel jobs (default: 4) |
+
+### Description
+
+- **`yc`** — Cleans `node_modules` via letter-based parallel deletion of top-level entries (a-z) inside `node_modules/`
+- **`ycw`** — Yarn workspaces–aware variant. Detects monorepo root, expands workspace globs, and cleans `node_modules` across root + all workspace packages in parallel
+
+### Source
+
+See [`bin/yc`](../bin/yc) & [`bin/ycw`](../bin/ycw)
+
+---
+
+## Node Modules Cleaner
+
+Recursively finds and removes `node_modules` directories.
+
+### Aliases
+
+- `del-nodemodules` (default)
+- `del-node-modules`
+
+### Usage
+
+```bash
+del-nodemodules [options]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--force`, `-f` | Actually delete (default is dry-run mode) |
+| `-c, --concurrent N` | Set concurrent removals (default: 2, or CPU count) |
+| `-h, --help` | Show help message |
+
+### Description
+
+- Searches for all `node_modules` directories recursively
+- Also removes `package-lock.json`, `yarn.lock`, and `.yarn/cache` directories
+- By default runs in dry-run mode (shows what would be deleted)
+- Pass `--force` to actually perform deletion
+
+### Source
+
+See [`src/del-node-modules.js`](../src/del-node-modules.js)
+
+---
+
+## Yarn Cache Cleaner
+
+Deletes Yarn cache directories and cached `.gz` files.
+
+### Aliases
+
+- `del-yarncaches` (default)
+- `del-yarn-caches`
+
+### Usage
+
+```bash
+del-yarncaches
+```
+
+### Description
+
+Finds and deletes all `.yarn/cache*` directories and `.yarn/*.gz` files under the current working directory, excluding `.git` and `vendor` directories.
+
+### Source
+
+See [`src/del-yarn-caches.js`](../src/del-yarn-caches.js)
+
+---
+
+## Remove Node Modules (Fast)
+
+Alternative tool for removing `node_modules` — faster for very large projects. Removes subfolders by first-letter in parallel.
+
+### Aliases
+
+- `rm-node-modules` (default)
+- `rm-node-module`
+- `remove-node-modules`
+- `remove-node-module`
+
+### Usage
+
+```bash
+rm-node-modules [options]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--force` | Actually delete (default is dry-run mode) |
+| `-h, --help` | Show help message |
+
+### Description
+
+- Removes `node_modules` subfolders by first-letter in parallel (a-z, A-Z)
+- Writes and executes a temporary shell script (auto-removed after completion)
+- On Windows requires a Unix-compatible shell in `PATH` (e.g., Git Bash or WSL)
+
+### Examples
+
+```bash
+npx --legacy-peer-deps -y binary-collections rm-node-modules
+npx --legacy-peer-deps -y binary-collections rm-node-modules --force
+yarn run rm-node-modules
+```
+
+### Source
+
+See [`src/rm-node-module-cli.cjs`](../src/rm-node-module-cli.cjs).
+

package/docs-src/node-executor.md

@@ -0,0 +1,50 @@
+## Node Executor
+
+Execute scripts in various languages by dispatching to the appropriate runtime based on file extension.
+
+### Aliases
+
+This command is available under several aliases (all invoke the same CLI):
+
+- `node-exec` (default)
+- `exec-node`
+- `execute-node`
+- `node-executor`
+
+### Usage
+
+```bash
+node-exec [options] <file>
+```
+
+### Options
+
+| Flag | Description |
+| :--- | :--- |
+| `-h`, `--help` | Show help |
+| `--exit-code=<code>` | Exit code when file not found or invalid (default: `1`) |
+
+### Supported Extensions
+
+| Extension | Runtime |
+| :-------- | :------ |
+| `.php` | `php` |
+| `.js` | `node` |
+| `.mjs` | `node` |
+| `.cjs` | `node` |
+| `.py` | `python` |
+| `.rb` | `ruby` |
+| `.sh` | `bash` |
+| `.bat` | `cmd` |
+
+### Example
+
+```bash
+node-exec test.php
+node-exec script.js
+node-exec --exit-code=0 missing.php
+```
+
+### Source
+
+See [`src/node-executor.cjs`](../src/node-executor.cjs)

package/docs-src/node-package-packer.md

@@ -0,0 +1,48 @@
+# Node Package Packer
+
+Automated tarball (tgz) creator for release folder. It packs the current package, generates release metadata, and writes a release README alongside the produced tarballs.
+
+## Usage
+
+```bash
+tarball-packer [options]
+```
+
+### One-off Call
+
+You can run the command without installing the library:
+
+```bash
+npx --legacy-peer-deps -y binary-collections@https://raw.githubusercontent.com/dimaslanjaka/bin/master/releases/bin.tgz node-package-packer [options]
+```
+
+### Aliases
+
+This command is available under the following aliases:
+
+- `tarball-packer` (default)
+- `node-package-packer`
+- `pack-node-package`
+- `pack-tarball`
+- `build-tarball`
+- `build-package`
+- `build-package-tarball`
+
+### Options
+
+| Flag | Description |
+| :--- | :--- |
+| `-h`, `--help` | Show help message |
+| `-y`, `--yarn` | Force `yarn pack` instead of `npm pack` |
+| `-d`, `--verbose` | Enable verbose output |
+| `--fn`, `--filename` | Set output filename variant |
+
+### Description
+
+- Runs `npm pack` or `yarn pack` to create a tarball in the project root.
+- Copies the tarball into the release folder and writes `metadata.json` with integrity hashes.
+- Generates a release README that lists available tarballs and raw GitHub URLs.
+
+### Source
+
+See [`src/node-package-packer-cli.mjs`](../src/node-package-packer-cli.mjs).

package/docs-src/npm-run-series.md

@@ -0,0 +1,43 @@
+## NPM Script Runner
+
+Execute multiple npm scripts in series using pattern matching.
+
+### Aliases
+
+This command is available under several aliases (all invoke the same CLI):
+
+- `nrs` (default)
+- `run-s`
+- `run-series`
+- `npm-run-series`
+
+### Usage
+
+```bash
+nrs <glob-pattern-of-script-names> [options]
+```
+
+### Options
+
+| Flag | Description |
+| :--- | :--- |
+| `--yarn` | Use `yarn run` instead of `npm run` |
+| `--verbose`, `-v` | Enable verbose logging |
+
+### Example
+
+Define a script to run all tasks matching a pattern:
+
+```json
+{
+  "scripts": {
+    "build:app": "echo 'building app'",
+    "build:lib": "echo 'building lib'",
+    "build:all": "nrs --yarn --verbose \"build:**\""
+  }
+}
+```
+
+### Source
+
+See [`src/npm-run-series.cjs`](../src/npm-run-series.cjs)

package/docs-src/opencode-cli.md

@@ -0,0 +1,127 @@
+# OpenCode CLI
+
+CLI tool for inspecting and managing an OpenCode database. Connects to the local OpenCode SQLite database (`~/.local/share/opencode/opencode.db`) to list sessions and projects, and to delete sessions or projects. Also supports API key rotation from a local keys file.
+
+## Usage
+
+```bash
+opc <command> [subcommand] [options]
+```
+
+### Aliases
+
+This command is available under several aliases (all invoke the same CLI):
+
+- `opc` (default)
+- `opencode-cli`
+
+### Commands
+
+#### `list session`
+
+Lists all sessions in a table format showing slug, title, and version.
+
+```bash
+opc list session
+```
+
+#### `list project`
+
+Lists all projects in a table format showing truncated ID, name, and worktree path.
+
+```bash
+opc list project
+```
+
+#### `delete session <id>`
+
+Deletes a single session and all its descendant sessions by ID.
+
+```bash
+opc delete session <session-id>
+```
+
+#### `delete sessions`
+
+Deletes **all** sessions from the database (irreversible).
+
+```bash
+opc delete sessions
+```
+
+#### `delete project <id>`
+
+Deletes a project's sessions and project record from the OpenCode database (not the real project folder on disk).
+
+The `<id>` is the project UUID shown in the first column of `opc list project`. Run that command first to find the project ID you want to delete.
+
+```bash
+opc delete project <project-id>
+```
+
+#### `auth rotate`
+
+Rotates the active OpenCode API key by picking the first working key from a local keys file. Iterates through available keys (excluding the current one) and tests each against the OpenCode API, selecting the first that returns a valid response.
+
+```bash
+opc auth rotate
+```
+
+### Options
+
+| Flag | Description |
+| :--- | :--- |
+| `-h`, `--help` | Show help message |
+
+### Examples
+
+List all sessions:
+
+```bash
+opc list session
+```
+
+Delete a specific session:
+
+```bash
+opc delete session abc123
+```
+
+Delete a project's sessions and project record from the OpenCode database (ID obtained from `opc list project`):
+
+```bash
+opc delete project 9a3bb589
+```
+
+Rotate to a working API key:
+
+```bash
+opc auth rotate
+# → Rotated OpenCode API key to: my-backup-key
+```
+
+### How it works
+
+1. **Database check**: On every command except `--help`, the tool first verifies the OpenCode database is accessible via `checkDatabase()`.
+2. **List**: Queries the `session` or `project` table and displays results in formatted tables with dynamic column widths.
+3. **Delete**: Uses recursive SQL (Common Table Expressions) to delete sessions and their descendants, or cascading deletes for project sessions.
+4. **Auth rotate**: Reads `.opencode.keys.jsonc` (or `.opencode.keys.json` as fallback) from the current directory, filters out the currently active key, tests each remaining key via `checkOpenCodeApi()`, and sets the first one that responds successfully.
+
+### Requirements
+
+For `auth rotate`, create a `.opencode.keys.jsonc` file in your project root:
+
+```jsonc
+[
+  // Each key must have a unique name and the actual API key value.
+  // Add this file to .gitignore to keep it private.
+  {
+    "name": "unique name for the key, e.g. email or username",
+    "key": "the actual key, e.g. sk-xxxxxx"
+  }
+]
+```
+
+## Source
+
+See [`src/opencode-cli.ts`](../src/opencode-cli.ts).

package/docs-src/package-resolutions-updater.md

@@ -0,0 +1,22 @@
+## Package Resolutions Manager
+
+Updates GitHub raw tarball commit SHAs in `package.json` resolutions to the latest commit on each branch.
+
+### Aliases
+
+- `pkg-resolutions-updater` (default)
+- `pkg-res-updater`
+
+### Usage
+
+```bash
+pkg-resolutions-updater
+```
+
+### Description
+
+Scans `package.json` resolutions for GitHub tarball URLs (raw.githubusercontent.com) and updates the commit SHA in each URL to the latest commit on the referenced branch.
+
+### Source
+
+See [`src/package-resolutions-updater-cli.mjs`](../src/package-resolutions-updater-cli.mjs).

package/docs-src/php-cs-fixer-staged.md

@@ -0,0 +1,19 @@
+## PHP CS Fixer Staged
+
+Runs `php-cs-fixer` on staged PHP files only.
+
+### Usage
+
+```bash
+php-cs-fixer-staged
+```
+
+### Description
+
+- Gets the list of staged PHP files using `git diff --name-only --cached --diff-filter=ACM`
+- Automatically locates `php-cs-fixer` in PATH or common locations (`vendor/bin/`, `bin/`, `tools/`)
+- Runs `php-cs-fixer fix` on only the staged PHP files
+
+### Source
+
+See [`src/php-cs-fixer-staged.cjs`](../src/php-cs-fixer-staged.cjs)

package/docs-src/print-directory-tree.md

@@ -0,0 +1,35 @@
+## Directory Tree Printer
+
+Generates a directory tree structure with file SHA-256 hashes.
+
+### Aliases
+
+- `print-tree` (default)
+- `dir-tree`
+- `print-directory-tree`
+
+### Usage
+
+```bash
+print-tree [options]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-o, --output <file>` | Output file (default: `tmp/directory-structure.txt`) |
+| `--ext <exts>` | Comma-separated list of file extensions to include |
+| `--pattern <glob>` | Glob pattern to include (repeatable) |
+| `--exclude <dirs>` | Directories to exclude |
+| `--override-exclude, -we` | Override default excludes |
+| `--git-add` | Stage output file to git |
+| `-h, --help` | Show help message |
+
+### Description
+
+Scans the current directory recursively, generates a structured tree with SHA-256 hashes for each file, and writes the result to an output file.
+
+### Source
+
+See [`src/print-directory-tree.cjs`](../src/print-directory-tree.cjs)

package/docs-src/print-tarball-tree.md

@@ -0,0 +1,55 @@
+# Tarball Tree Printer
+
+Prints the directory tree structure of a `.tgz` (gzipped tarball) archive to the console.
+
+# Usage
+
+```bash
+print-tarball-tree [options]
+```
+
+### Aliases
+
+- `print-tarball-tree` (default)
+- `tarball-tree`
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-f, --file <path>` | Path to the tarball file |
+| `-h, --help` | Show help message |
+
+### Description
+
+Reads a `.tgz` file (gzipped tar archive), extracts the entry names, and prints them as a hierarchical directory tree using Unicode box-drawing characters (`├──`, `└──`, `│`).
+
+The file path can be given as an absolute path or a relative path (resolved against the current working directory).
+
+If no `--file` argument is provided, the command exits with an error.
+
+If the specified file does not exist, the command exits with an error.
+
+### Examples
+
+Print the tree of a tarball in the current directory:
+
+```bash
+print-tarball-tree --file package.tgz
+```
+
+Print the tree using an absolute path:
+
+```bash
+print-tarball-tree -f /path/to/package.tgz
+```
+
+Using the alias:
+
+```bash
+tarball-tree --file build/package.tgz
+```
+
+# Source
+
+See [`src/print-tarball-tree.mjs`](../src/print-tarball-tree.mjs)

package/docs-src/py.md

@@ -0,0 +1,19 @@
+## Python Script Runner
+
+Runs Python scripts using a managed virtual environment.
+
+### Usage
+
+```bash
+py <script.py> [args...]
+```
+
+### Description
+
+- Automatically manages a Python virtual environment
+- Installs dependencies as needed
+- Runs Python scripts in a consistent, isolated environment
+
+### Source
+
+See [`bin/py`](../bin/py)

package/docs-src/remove-module.md

@@ -0,0 +1,32 @@
+## Remove Module
+
+Removes a module from one or more dependency directories (Node.js, PHP Composer, Python venv).
+
+### Usage
+
+```bash
+remove-module <moduleName> [<moduleName> ...]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--node` | Remove from `node_modules` (default if no flag given) |
+| `--composer` | Remove from `vendor/composer` |
+| `--venv` | Remove from `venv`/`.venv` site-packages |
+| `-h, --help` | Show help message |
+
+### Examples
+
+```bash
+remove-module lodash
+remove-module lodash express --node
+remove-module phpunit --composer
+remove-module requests --venv
+remove-module lodash phpunit --node --composer
+```
+
+### Source
+
+See [`src/remove-module.mjs`](../src/remove-module.mjs)

package/docs-src/rmfind-rmx.md

@@ -0,0 +1,21 @@
+## Fast File/Folder Deleters
+
+Shell-based utilities for finding and removing files/directories by name.
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `rmfind` | Find and delete files/directories by name using `find` |
+| `rmx` | Fast parallel alphabet-based folder deleter |
+
+### Usage
+
+```bash
+rmfind <name>       # Find and delete items by name
+rmx <path>          # Fast parallel deletion of folder contents
+```
+
+### Source
+
+See [`bin/rmfind`](../bin/rmfind), [`bin/rmx`](../bin/rmx) & [`bin/rmx.cmd`](../bin/rmx.cmd)

package/docs-src/rmpath.md

@@ -0,0 +1,38 @@
+# Remove Path (rmpath)
+
+Fast huge folder deleter using a parallel alphabet-based deletion strategy. Deletes files or folders quickly by breaking down deletions alphabetically, falling back to standard `fs.rmSync` for the top-level target.
+
+## Usage
+
+```bash
+rmpath <file-or-folder-path>
+```
+
+### Aliases
+
+This command is available under the following alias:
+
+- `rmpath` (default)
+
+### Behavior
+
+- **Files**: The specified file is deleted directly.
+- **Folders**: Subentries starting with each letter (a–z, A–Z) are resolved and deleted in parallel patterns. Vowel combinations are also covered for thorough matching.
+- **Fallback**: After alphabet-based deletion, `fs.rmSync` is called on the original target path to clean up any remaining entries.
+
+### Examples
+
+```bash
+# Delete a single file
+rmpath large-file.tmp
+
+# Delete a large directory (e.g., node_modules)
+rmpath ./node_modules
+
+# Delete a directory using an absolute path
+rmpath C:\temp\huge-folder
+```
+
+## Source
+
+See [`src/rmpath-cli.mjs`](../src/rmpath-cli.mjs).