binary-collections 2.0.12 → 2.0.14

package/docs-src/run-by-checksum.md

@@ -0,0 +1,87 @@
+# Run by Checksum
+
+Run a command only when the checksum of matched files changes. Computes SHA-256 hashes of all matching files, stores them in a cache under `tmp/.checksum/`, and compares on subsequent runs to determine if the command should execute again.
+
+## Usage
+
+```bash
+run-by-checksum -p "<glob>" -e "<command>"
+```
+
+### Aliases
+
+This command is available under several aliases (all invoke the same CLI):
+
+- `run-by-checksum` (default)
+- `run-checksum`
+- `run-c`
+
+### Options
+
+| Flag | Type | Description |
+| :--- | :--- | :--- |
+| `-p`, `--pattern` | `string[]` | Glob pattern(s) to include (can be repeated) |
+| `-i`, `--ignore` | `string[]` | Glob pattern(s) to exclude (can be repeated) |
+| `-e`, `--exec` | `string` | Command to execute when checksum changes |
+| `-c`, `--cwd` | `string` | Working directory for glob scanning and spawn (default: `INIT_CWD` or current directory) |
+| `-h`, `--help` | `boolean` | Show help message |
+
+### Examples
+
+Run a build script when any `.js` or `.ts` file changes:
+
+```bash
+run-by-checksum -p "src/**/*.js" -p "src/**/*.ts" -e "npm run build"
+```
+
+Ignore node_modules and run tests when source files change:
+
+```bash
+run-by-checksum -p "src/**/*.js" -i "**/node_modules/**" -e "npm test"
+```
+
+Override the working directory (both glob scanning and spawned command run relative to the given directory):
+
+```bash
+run-by-checksum -p "*.js" -e "npm test" --cwd /path/to/project
+```
+
+### How it works
+
+1. **Scan**: All files matching the given glob patterns are collected.
+2. **Hash**: SHA-256 checksums are computed for each matched file's content and combined into a single hash.
+3. **Compare**: The combined hash is compared against a previously cached hash stored in `tmp/.checksum/<md5-key>.json`.
+4. **Execute**: If the hash differs (files have changed), the specified command is executed.
+5. **Cache**: Only if the command exits successfully (exit code 0) is the new checksum persisted to the cache. On failure, the old checksum is retained so the command will re-run on the next invocation.
+6. **Skip**: If the hash matches (no changes), the command is skipped.
+
+### Programmatic API
+
+The core logic can also be imported directly:
+
+```js
+import { runChecksum } from './src/run-by-checksum/run.js';
+
+await runChecksum({
+  patterns: ['src/**/*.js'],
+  ignore: ['**/node_modules/**'],
+  exec: 'npm run build',
+  cwd: process.cwd(),
+  dryRun: false  // set to true to detect changes without executing
+});
+```
+
+The function returns:
+
+```ts
+{
+  changed: boolean,     // whether files changed since last run
+  cacheFile: string,    // path to the cache file
+  files: string[],      // list of matched files
+  skipped?: boolean     // only present when dryRun=true and changes detected
+}
+```
+
+## Source
+
+See [`src/run-by-checksum-cli.js`](../src/run-by-checksum-cli.js).

package/docs-src/submodule-install.md

@@ -0,0 +1,31 @@
+## Submodule Install
+
+Installs and updates git submodules recursively, applying access tokens for private repos.
+
+### Usage
+
+```bash
+submodule-install [options] [repo-path]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--cwd <path>` | Set working directory |
+| `-h, --help` | Show help message |
+
+### Description
+
+- Installs and updates git submodules recursively
+- Applies access tokens (`GITHUB_TOKEN` or `ACCESS_TOKEN` from `.env`) for private repositories
+- Prevents infinite recursion loops by tracking visited submodules
+
+### Environment Setup
+
+1. Add `GITHUB_TOKEN` or `ACCESS_TOKEN` to your `.env` file
+2. Ensure your tokens have access to the required repositories
+
+### Source
+
+See [`src/submodule-install.cjs`](../src/submodule-install.cjs)

package/docs-src/submodule-remove.md

@@ -0,0 +1,22 @@
+## Submodule Remove
+
+Completely removes a git submodule from the repository.
+
+### Usage
+
+```bash
+submodule-remove <submodule-path>
+```
+
+### Description
+
+Performs a complete removal of a git submodule:
+- De-initializes the submodule (`git submodule deinit`)
+- Removes the submodule from `.gitmodules`
+- Removes the submodule from `.git/config`
+- Removes the submodule directory
+- Commits the changes
+
+### Source
+
+See [`src/submodule-remove-cli.js`](../src/submodule-remove-cli.js).

package/docs-src/submodule-token.md

@@ -0,0 +1,17 @@
+## Submodule Token Manager
+
+Removes access tokens from git submodule URLs.
+
+### Usage
+
+```bash
+submodule-token
+```
+
+### Description
+
+Scans submodule URLs in `.gitmodules` and removes any embedded access tokens, leaving clean HTTPS URLs.
+
+### Source
+
+See [`bin/submodule-token`](../bin/submodule-token)

package/docs-src/test-runners.md

@@ -0,0 +1,21 @@
+## Jest Test Runners
+
+Run Jest tests for CommonJS or ESM modules.
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `test-cjs` | Run Jest for CommonJS tests |
+| `test-esm` | Run Jest for ESM tests (with `--experimental-vm-modules`) |
+
+### Usage
+
+```bash
+test-cjs [jest-options...]
+test-esm [jest-options...]
+```
+
+### Source
+
+See [`bin/test-cjs`](../bin/test-cjs) & [`bin/test-esm`](../bin/test-esm)

package/docs-src/upload-backend.md

@@ -0,0 +1,29 @@
+# Upload Backend
+
+Uploads PHP files from the `backend/` directory to a remote server via SFTP. Reads the connection configuration from `.vscode/sftp.json` and deploys all `.php` files into `{remotePath}/php_backend` on the target server.
+
+## Usage
+
+```bash
+node scripts/upload-backend.mjs
+```
+
+### Prerequisites
+
+- An SFTP server configured in `.vscode/sftp.json`
+- PHP files present in the `backend/` directory
+
+### Behavior
+
+1. Reads `.vscode/sftp.json` for host, port, username, and password
+2. Scans `backend/` for all `*.php` files
+3. Connects to the remote server via SFTP
+4. Creates the `php_backend` subdirectory under the configured `remotePath`
+5. Uploads each PHP file into that directory
+6. Prints a confirmation per uploaded file
+
+If no PHP files are found, the script exits with a notice.
+
+## Source
+
+See [`scripts/upload-backend.mjs`](../scripts/upload-backend.mjs).

package/docs-src/vscode-cli.md

@@ -0,0 +1,84 @@
+# VSCode CLI
+
+CLI tool for inspecting VS Code workspace storage directories. Scans the `workspaceStorage` folder under the VS Code user data directory, reads each subdirectory's `workspace.json`, and lists workspace projects with their storage identifiers. Optionally filters to workspaces that have a Copilot memory tool directory.
+
+## Usage
+
+```bash
+vscode-cli <command> [subcommand] [options]
+```
+
+### Aliases
+
+This command is available under the following alias:
+
+- `vscode-cli` (default)
+
+### Commands
+
+#### `list project`
+
+Lists all workspace projects in a table format showing truncated storage ID, folder path, and whether Copilot memory tool data exists.
+
+```bash
+vscode-cli list project
+```
+
+#### `list project --copilot-memory`
+
+Lists only projects that have a Copilot memory tool directory (i.e., those where `GitHub.copilot-chat/memory-tool/memories` exists under the workspace storage directory).
+
+```bash
+vscode-cli list project --copilot-memory
+```
+
+Short aliases: `--copilotMemory`, `--cm`
+
+### Options
+
+| Flag | Description |
+| :--- | :--- |
+| `-h`, `--help` | Show help message |
+| `--copilot-memory` | Filter to projects with Copilot memory tool |
+
+### Examples
+
+List all workspace projects:
+
+```bash
+vscode-cli list project
+```
+
+List only projects with Copilot memory tool data:
+
+```bash
+vscode-cli list project --copilot-memory
+```
+
+### How it works
+
+1. **Scan**: Lists all subdirectories under the VS Code `workspaceStorage` folder (e.g., `%APPDATA%/Code/User/workspaceStorage` on Windows).
+2. **Parse**: Reads `workspace.json` from each subdirectory to extract the workspace `folder` URI.
+3. **Decode**: Converts `file:///` URIs to absolute filesystem paths (e.g., `file:///d%3A/Repositories/project` → `d:/Repositories/project`).
+4. **Filter** (optional): When `--copilot-memory` is specified, only includes entries where `GitHub.copilot-chat/memory-tool/memories` exists on disk.
+5. **Display**: Renders results in a formatted table with dynamic column widths.
+
+### Programmatic API
+
+The workspace scanning logic can also be imported directly:
+
+```ts
+import { listWorkspaceProjects } from './src/vscode/storage.js';
+
+const projects = await listWorkspaceProjects();
+
+// projects is WorkspaceEntry[] with:
+//   storageId: string  — hash-based subdirectory name
+//   folder: string     — absolute filesystem path (decoded URI)
+//   storagePath: string — full path to the workspace storage subdirectory
+//   copilotMemoryDir?: string — path to Copilot memory tool directory (if it exists)
+```
+
+## Source
+
+See [`src/vscode-cli.ts`](../src/vscode-cli.ts).

package/docs-src/workflow-badge.md

@@ -0,0 +1,120 @@
+# Workflow Badge
+
+Generates a detailed SVG badge showing the status of the latest GitHub Actions workflow run. Displays workflow metadata, per-job step breakdown, and aggregated status counts — all in a polished card-style SVG suitable for embedding in READMEs, dashboards, or CI summary pages.
+
+## Usage
+
+```bash
+workflow-badge [options]
+```
+
+### Aliases
+
+This command is available under several aliases (all invoke the same CLI):
+
+- `workflow-badge` (default)
+- `wf-badge`
+- `gh-status-badge`
+- `actions-badge`
+
+### Options
+
+| Flag | Type | Description |
+| :--- | :--- | :--- |
+| `-o`, `--output` | `string` | Write SVG to file instead of stdout |
+| `--owner` | `string` | GitHub repository owner (default: auto-detect from git remote) |
+| `--repo` | `string` | GitHub repository name (default: auto-detect from git remote) |
+| `--workflow` | `string` | Filter by workflow filename (e.g. `"test.yml"`) or numeric workflow ID |
+| `--token` | `string` | GitHub access token (overrides `ACCESS_TOKEN` / `GITHUB_TOKEN` / `GH_TOKEN` env vars) |
+| `--width` | `number` | SVG width in pixels (default: `520`) |
+| `--max-steps` | `number` | Max steps to show per job (default: all). Use to keep badge compact |
+| `-h`, `--help` | `boolean` | Show help message |
+
+### Environment Variables
+
+| Variable | Description |
+| :------- | :---------- |
+| `ACCESS_TOKEN` / `GITHUB_TOKEN` / `GH_TOKEN` | GitHub personal access token (required for API calls) |
+| `GH_OWNER` | Override repository owner (optional) |
+| `GH_REPO` | Override repository name (optional) |
+
+### Examples
+
+Preview badge in terminal (SVG printed to stdout):
+
+```bash
+workflow-badge
+```
+
+Save badge to file:
+
+```bash
+workflow-badge --output badge.svg
+```
+
+Save for a specific repository with custom width:
+
+```bash
+workflow-badge --owner dimaslanjaka --repo bin --output docs/workflow-status.svg --width 600
+```
+
+Keep the badge compact by limiting visible steps per job:
+
+```bash
+workflow-badge --max-steps 5 --output compact-badge.svg
+```
+
+Generate a badge for a specific workflow YAML file:
+
+```bash
+workflow-badge --workflow test.yml
+workflow-badge --owner dimaslanjaka --repo bin --workflow deploy.yml --output deploy-badge.svg
+```
+
+### Output
+
+The generated SVG is a card-style badge with:
+
+- **Accent bar** — color-coded based on overall status (green = passing, red = failing, amber = in progress, grey = cancelled/pending)
+- **Title section** — "Workflow Status" label with status pill
+- **Metadata rows** — workflow name, status, branch, run ID
+- **Jobs breakdown** — each job with its status, plus individual step rows with icons (✓ = passed, ✗ = failed, ◌ = pending, – = skipped)
+- **Footer summary** — aggregated step counts
+
+### PHP Backend
+
+A PHP script is available at [`backend/workflow-badge.php`](../backend/workflow-badge.php) that serves the badge as a live image via HTTP. It spawns the Node CLI, captures the SVG output, and serves it with the correct `image/svg+xml` content type. The PHP backend requires the full project (with the CLI script under `src/` or `lib/`) to be deployed on the server — it does not fall back to a remote tarball.
+
+**Query parameters:**
+
+| Parameter | Required | Description |
+| :-------- | :------- | :---------- |
+| `owner` | yes | GitHub repository owner |
+| `repo` | yes | GitHub repository name |
+| `workflow` | no | Filter by workflow filename (e.g. `test.yml`) or workflow ID |
+| `width` | no | SVG width in pixels (200–2000, default: 520) |
+| `max-steps` | no | Max steps to show per job (1–200, default: all) |
+| `token` | no | GitHub access token (overrides server env) |
+
+**Requirements:**
+- PHP 7.4+ with `proc_open` enabled
+- The project's Node CLI script deployed on the server (`src/github-workflows/workflow-badge-cli.mjs` or `lib/github-workflows/workflow-badge-cli.cjs`)
+- `ACCESS_TOKEN` (or `GITHUB_TOKEN` / `GH_TOKEN`) environment variable set on the server, or pass `&token=...` per request
+
+**Usage as `<img>` tag:**
+
+```html
+<img src="https://your-domain.com/backend/workflow-badge.php?owner=dimaslanjaka&repo=bin" />
+<!-- or using our server -->
+<img src="http://sh.webmanajemen.com/php_backend/workflow-badge.php?owner=dimaslanjaka&repo=bin" />
+```
+
+![badge sample](http://sh.webmanajemen.com/php_backend/workflow-badge.php?owner=dimaslanjaka&repo=bin)
+
+You can optionally add `&width=600`, `&max-steps=5`, `&workflow=test.yml`, or `&token=ghp_xxx` to customize the badge appearance or override the server's GitHub token for a single request.
+
+The script validates all parameters before passing them to the Node CLI, separates `stdout` (SVG) from `stderr` (diagnostics) via `proc_open`, and returns appropriate HTTP error codes for invalid inputs or CLI failures.
+
+## Source
+
+See [`src/github-workflows/workflow-badge-cli.mjs`](../src/github-workflows/workflow-badge-cli.mjs).

package/docs-src/yarn-install.md

@@ -0,0 +1,31 @@
+## Per-Branch Yarn Lock Installer
+
+Manages per-branch `yarn.lock` files — saves and restores branch-specific lockfiles.
+
+### Aliases
+
+- `yarn-install` (default)
+- `y-install`
+- `yarn-per-branch-lock-installer`
+
+### Usage
+
+```bash
+yarn-install [packages...]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-h, --help` | Show help message |
+
+### Description
+
+- Saves the current `yarn.lock` to a branch-specific file before switching branches
+- Restores the branch-specific `yarn.lock` when returning to a branch
+- Runs `yarn install` or `yarn up` to sync dependencies
+
+### Source
+
+See [`src/yarn-per-branch-lock-installer.cjs`](../src/yarn-per-branch-lock-installer.cjs)

package/docs-src/yarn-reinstall.md

@@ -0,0 +1,27 @@
+## Yarn Package Reinstaller
+
+Reinstalls a yarn package by removing and re-adding it.
+
+### Usage
+
+```bash
+yarn-reinstall <packageName> [--dev|-D|--peer|-P|--optional|-O]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--dev`, `-D` | Add as dev dependency |
+| `--peer`, `-P` | Add as peer dependency |
+| `--optional`, `-O` | Add as optional dependency |
+
+### Description
+
+- Checks if the package is currently installed before removing
+- Runs `yarn remove <packageName>` then `yarn add <packageName> [flags]`
+- Skips removal if the package is not installed
+
+### Source
+
+See [`src/yarn-reinstall.cjs`](../src/yarn-reinstall.cjs)

package/lib/binary-collections/config.cjs

@@ -90,6 +90,9 @@ var require_findEnvFiles = __commonJS({
       return envFiles.find((file) => {
         try {
           const content = fs.readFileSync(file, "utf-8");
+          if (tokenName instanceof RegExp) {
+            return tokenName.test(content);
+          }
           const regex = new RegExp(`^\\s*${tokenName}\\s*=`, "m");
           return regex.test(content);
         } catch (err) {
@@ -109,9 +112,16 @@ var require_findEnvFiles = __commonJS({
 
 // src/binary-collections/config.cjs
 init_cjs_shims();
-var path = require("path");
+var path = require("upath");
+var minimistLib = require("minimist");
 var { findEnvWithToken } = require_findEnvFiles();
-require("dotenv").config({ path: findEnvWithToken(), quiet: true, overwrite: true });
+var dotenv = require("dotenv");
+var loadDotenv = (tokenKey = /ACCESS_TOKEN|GITHUB_TOKEN/) => dotenv.config({ path: findEnvWithToken(void 0, tokenKey), quiet: true, overwrite: true });
+loadDotenv();
+var cliArgv = minimistLib(process.argv.slice(2), {
+  string: ["token"]
+});
+var GITHUB_ACCESS_TOKEN = cliArgv.token || process.env.ACCESS_TOKEN || process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
 function getTempDir() {
   return process.env.TEMP_DIR || path.join(process.cwd(), "tmp");
 }
@@ -122,5 +132,7 @@ var TEMP_BASE_DIR = getTempDir();
 module.exports = {
   getTempDir,
   getTempPath,
-  TEMP_BASE_DIR
+  TEMP_BASE_DIR,
+  GITHUB_ACCESS_TOKEN,
+  loadDotenv
 };

package/lib/binary-collections/config.d.cts

@@ -14,3 +14,13 @@ export function getTempPath(...segments: string[]): string;
  * Legacy aliases for backward compatibility
  */
 export const TEMP_BASE_DIR: string;
+export const GITHUB_ACCESS_TOKEN: any;
+/**
+ * Load .env file containing a token variable.
+ * Searches for `.env*` files and picks the first one matching the given token key.
+ *
+ * @param {string|RegExp} [tokenKey=/ACCESS_TOKEN|GITHUB_TOKEN/] - Token name or regex to search for.
+ *   Passed as second argument to `findEnvWithToken()`.
+ * @returns {void}
+ */
+export function loadDotenv(tokenKey?: string | RegExp): void;

package/lib/binary-collections/config.mjs

@@ -1,7 +1,7 @@
 import { createRequire } from 'module'; const require = createRequire(import.meta.url);
 import {
   require_config
-} from "../chunk-G5UUEWUO.mjs";
-import "../chunk-H44UWUFY.mjs";
+} from "../chunk-SARIXFHP.mjs";
+import "../chunk-J4M5EL5P.mjs";
 import "../chunk-QQ4A6DLD.mjs";
 export default require_config();