binary-collections 2.0.11 → 2.0.13

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) (CLI) and [`src/run-by-checksum/`](../src/run-by-checksum/) (core logic).

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.cjs`](../src/submodule-remove.cjs) & [`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/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

@@ -0,0 +1,126 @@
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+
+// node_modules/tsup/assets/cjs_shims.js
+var init_cjs_shims = __esm({
+  "node_modules/tsup/assets/cjs_shims.js"() {
+  }
+});
+
+// src/utils/findEnvFiles.cjs
+var require_findEnvFiles = __commonJS({
+  "src/utils/findEnvFiles.cjs"(exports2, module2) {
+    init_cjs_shims();
+    var fs = require("fs");
+    var path2 = require("path");
+    var glob = require("glob");
+    var DEFAULT_IGNORES = [
+      "**/node_modules/**",
+      "**/.git/**",
+      "**/.yarn/**",
+      "**/.pnpm/**",
+      "**/dist/**",
+      "**/build/**",
+      "**/coverage/**",
+      "**/vendor/**",
+      "**/tmp/**",
+      "**/.cache/**",
+      "**/assets/**",
+      "**/logs/**",
+      "**/output/**",
+      "**/public/**",
+      "**/static/**",
+      "**/temp/**",
+      "**/backup/**",
+      "**/backups/**",
+      "**/examples/**",
+      "**/docs/**",
+      "**/tests/**",
+      "**/__tests__/**",
+      "**/spec/**",
+      "**/__specs__/**",
+      "**/scripts/**",
+      "**/bin/**",
+      "**/hooks/**",
+      "**/config/**",
+      "**/configs/**",
+      "**/settings/**",
+      "**/.vscode/**",
+      "**/.idea/**"
+    ];
+    function findEnvFiles(startDir = process.cwd(), filter) {
+      const found = /* @__PURE__ */ new Set();
+      function addFile(file) {
+        const normalized = path2.normalize(file);
+        if (typeof filter === "function" && !filter(normalized)) {
+          return;
+        }
+        found.add(normalized);
+      }
+      let current = path2.resolve(startDir);
+      while (true) {
+        const envPath = path2.join(current, ".env");
+        if (fs.existsSync(envPath)) {
+          addFile(envPath);
+        }
+        const parent = path2.dirname(current);
+        if (parent === current) {
+          break;
+        }
+        current = parent;
+      }
+      const files = glob.globSync("**/.env*", {
+        cwd: startDir,
+        absolute: true,
+        nodir: true,
+        ignore: DEFAULT_IGNORES
+      });
+      for (const file of files) {
+        addFile(file);
+      }
+      return [...found];
+    }
+    function findEnvWithToken2(startDir = process.cwd(), tokenName = "GITHUB_TOKEN") {
+      const envFiles = findEnvFiles(startDir);
+      return envFiles.find((file) => {
+        try {
+          const content = fs.readFileSync(file, "utf-8");
+          const regex = new RegExp(`^\\s*${tokenName}\\s*=`, "m");
+          return regex.test(content);
+        } catch (err) {
+          console.warn(`Failed to read ${file}: ${err instanceof Error ? err.message : String(err)}`);
+          return false;
+        }
+      });
+    }
+    module2.exports = {
+      DEFAULT_IGNORES,
+      findEnvFiles,
+      findEnvWithToken: findEnvWithToken2,
+      default: findEnvFiles
+    };
+  }
+});
+
+// src/binary-collections/config.cjs
+init_cjs_shims();
+var path = require("upath");
+var { findEnvWithToken } = require_findEnvFiles();
+require("dotenv").config({ path: findEnvWithToken(), quiet: true, overwrite: true });
+function getTempDir() {
+  return process.env.TEMP_DIR || path.join(process.cwd(), "tmp");
+}
+function getTempPath(...segments) {
+  return path.join(getTempDir(), ...segments);
+}
+var TEMP_BASE_DIR = getTempDir();
+module.exports = {
+  getTempDir,
+  getTempPath,
+  TEMP_BASE_DIR
+};

package/lib/binary-collections/config.mjs

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

package/lib/binary-collections/executeScript.cjs

@@ -0,0 +1,19 @@
+// src/binary-collections/executeScript.cjs
+var { spawn } = require("child_process");
+function executeScript(scriptPath, args) {
+  console.log(`\u{1F527} Executing script: ${scriptPath} args: ${args.join(" ")}
+`);
+  const child = spawn("node", [scriptPath, ...args], {
+    stdio: "inherit",
+    shell: true
+  });
+  child.on("error", (error) => {
+    console.error(`\u274C Error executing script: ${error.message}`);
+    process.exit(1);
+  });
+  child.on("close", (code) => {
+    process.exit(code);
+  });
+}
+module.exports = executeScript;
+module.exports.default = executeScript;

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

@@ -0,0 +1,12 @@
+export = executeScript;
+/**
+ * Executes a script file using Node.js with the provided arguments
+ * @function executeScript
+ * @param {string} scriptPath - The absolute path to the script file to execute
+ * @param {string[]} args - Array of arguments to pass to the script
+ * @returns {void} Exits the process when the script execution completes
+ */
+declare function executeScript(scriptPath: string, args: string[]): void;
+declare namespace executeScript {
+    export { executeScript as default };
+}

package/lib/binary-collections/executeScript.mjs

@@ -0,0 +1,6 @@
+import { createRequire } from 'module'; const require = createRequire(import.meta.url);
+import {
+  require_executeScript
+} from "../chunk-PXBMHE7O.mjs";
+import "../chunk-QQ4A6DLD.mjs";
+export default require_executeScript();