@somewhatabstract/x 0.0.1 → 0.1.0

package/.github/dependabot.yml

@@ -0,0 +1,28 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: saturday
+      time: "09:00"
+      timezone: America/Chicago
+    open-pull-requests-limit: 10
+    reviewers:
+      - somewhatabstract
+  
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: saturday
+      time: "09:00"
+      timezone: America/Chicago
+    open-pull-requests-limit: 10
+    reviewers:
+      - somewhatabstract

package/.github/workflows/codeql-analysis.yml

@@ -13,12 +13,12 @@ name: "CodeQL"
 
 on:
   push:
-    branches: [ main ]
+    branches: [main]
   pull_request:
     # The branches below must be a subset of the branches above
-    branches: [ main ]
+    branches: [main]
   schedule:
-    - cron: '16 7 * * 2'
+    - cron: "16 7 * * 2"
 
 jobs:
   analyze:
@@ -32,40 +32,40 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        language: [ 'javascript' ]
+        language: ["javascript"]
         # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python' ]
         # Learn more:
         # https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#changing-the-languages-that-are-analyzed
 
     steps:
-    - name: Checkout repository
-      uses: actions/checkout@v5
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
 
-    # Initializes the CodeQL tools for scanning.
-    - name: Initialize CodeQL
-      uses: github/codeql-action/init@v4
-      with:
-        languages: ${{ matrix.language }}
-        # If you wish to specify custom queries, you can do so here or in a config file.
-        # By default, queries listed here will override any specified in a config file.
-        # Prefix the list here with "+" to use these queries and those in the config file.
-        # queries: ./path/to/local/query, your-org/your-repo/queries@main
+      # Initializes the CodeQL tools for scanning.
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@710e2945787622b429f8982cacb154faa182de18
+        with:
+          languages: ${{ matrix.language }}
+          # If you wish to specify custom queries, you can do so here or in a config file.
+          # By default, queries listed here will override any specified in a config file.
+          # Prefix the list here with "+" to use these queries and those in the config file.
+          # queries: ./path/to/local/query, your-org/your-repo/queries@main
 
-    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
-    # If this step fails, then you should remove it and run the build manually (see below)
-    - name: Autobuild
-      uses: github/codeql-action/autobuild@v4
+      # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
+      # If this step fails, then you should remove it and run the build manually (see below)
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@710e2945787622b429f8982cacb154faa182de18
 
-    # ℹ️ Command-line programs to run using the OS shell.
-    # 📚 https://git.io/JvXDl
+      # ℹ️ Command-line programs to run using the OS shell.
+      # 📚 https://git.io/JvXDl
 
-    # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
-    #    and modify them (or add more) to build your code if your project
-    #    uses a compiled language
+      # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
+      #    and modify them (or add more) to build your code if your project
+      #    uses a compiled language
 
-    #- run: |
-    #   make bootstrap
-    #   make release
+      #- run: |
+      #   make bootstrap
+      #   make release
 
-    - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v4
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@710e2945787622b429f8982cacb154faa182de18

package/.github/workflows/dependabot-pr-approval.yml

@@ -0,0 +1,36 @@
+name: Dependabot Pull Request Approve and Merge
+
+on: pull_request_target
+
+permissions:
+    pull-requests: write
+    contents: write
+
+jobs:
+    dependabot:
+        runs-on: ubuntu-latest
+        # Checking the actor will prevent your Action run failing on non-Dependabot
+        # PRs but also ensures that it only does work for Dependabot PRs.
+        if: ${{ github.actor == 'dependabot[bot]' }}
+        steps:
+            # This first step will fail if there's no metadata and so the approval
+            # will not occur.
+            - name: Dependabot metadata
+              id: dependabot-metadata
+              uses: dependabot/fetch-metadata@21025c705c08248db411dc16f3619e6b5f9ea21a
+              with:
+                  github-token: "${{ secrets.GITHUB_TOKEN }}"
+            # Here the PR gets approved.
+            - name: Approve a PR
+              run: gh pr review --approve "$PR_URL"
+              env:
+                  PR_URL: ${{ github.event.pull_request.html_url }}
+                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+            # Finally, this sets the PR to allow auto-merging for patch and minor
+            # updates if all checks pass
+            - name: Enable auto-merge for Dependabot PRs
+              if: ${{ steps.dependabot-metadata.outputs.update-type != 'version-update:semver-major' }}
+              run: gh pr merge --auto --squash "$PR_URL"
+              env:
+                  PR_URL: ${{ github.event.pull_request.html_url }}
+                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/nodejs.yml

@@ -8,7 +8,7 @@ on:
 
   push:
     branches:
-    - main
+      - main
 
 jobs:
   lint:
@@ -21,40 +21,39 @@ jobs:
         os: [ubuntu-latest]
         node-version: [20.x]
     steps:
-    - uses: actions/checkout@v4
-
-    - uses: pnpm/action-setup@v4
-      name: Install pnpm
-      with:
-        run_install: false
-        package_json_file: 'package.json'
-
-    - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v4
-      with:
-        node-version: ${{ matrix.node-version }}
-        cache: 'pnpm'
-        cache-dependency-path: 'pnpm-lock.yaml'
-
-    - name: Install Dependencies
-      shell: bash
-      run: pnpm install --frozen-lockfile
-
-    - name: Lint
-      run: pnpm lint
-
-    - name: Static Types
-      run: pnpm typecheck
-
-    - name: Changesets check
-      uses: Khan/actions@check-for-changeset-v1
-      if: |
-        github.actor != 'dependabot[bot]' &&
-        github.actor != 'dependabot-preview[bot]' &&
-        github.event_name == 'pull_request'
-      with:
-        exclude: .github/,.storybook/
-
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+
+      - uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061
+        name: Install pnpm
+        with:
+          run_install: false
+          package_json_file: "package.json"
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "pnpm"
+          cache-dependency-path: "pnpm-lock.yaml"
+
+      - name: Install Dependencies
+        shell: bash
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Static Types
+        run: pnpm typecheck
+
+      - name: Changesets check
+        uses: Khan/actions@973e081efd07f23c4e521e7f4c6b15c9257ee924
+        if: |
+          github.actor != 'dependabot[bot]' &&
+          github.actor != 'dependabot-preview[bot]' &&
+          github.event_name == 'pull_request'
+        with:
+          exclude: .github/,.storybook/
 
   coverage:
     name: Update test coverage
@@ -66,32 +65,31 @@ jobs:
         os: [ubuntu-latest]
         node-version: [20.x]
     steps:
-    - uses: actions/checkout@v4
-
-    - uses: pnpm/action-setup@v4
-      name: Install pnpm
-      with:
-        run_install: false
-        package_json_file: 'package.json'
-
-    - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v4
-      with:
-        node-version: ${{ matrix.node-version }}
-        cache: 'pnpm'
-        cache-dependency-path: 'pnpm-lock.yaml'
-
-    - name: Install Dependencies
-      shell: bash
-      run: pnpm install --frozen-lockfile
-
-    - name: Run tests with coverage
-      run: pnpm coverage
-    - name: Upload coverage
-      uses: codecov/codecov-action@v5
-      env:
-        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
-
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+
+      - uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061
+        name: Install pnpm
+        with:
+          run_install: false
+          package_json_file: "package.json"
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "pnpm"
+          cache-dependency-path: "pnpm-lock.yaml"
+
+      - name: Install Dependencies
+        shell: bash
+        run: pnpm install --frozen-lockfile
+
+      - name: Run tests with coverage
+        run: pnpm coverage
+      - name: Upload coverage
+        uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
   build:
     needs: [coverage, lint]
@@ -104,28 +102,28 @@ jobs:
         os: [ubuntu-latest]
         node-version: [20.x]
     steps:
-    - uses: actions/checkout@v4
-
-    - uses: pnpm/action-setup@v4
-      name: Install pnpm
-      with:
-        run_install: false
-        package_json_file: 'package.json'
-
-    - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v4
-      with:
-        node-version: ${{ matrix.node-version }}
-        cache: 'pnpm'
-        cache-dependency-path: 'pnpm-lock.yaml'
-
-    - name: Install Dependencies
-      shell: bash
-      run: pnpm install --frozen-lockfile
-
-    - name: Run build
-      env:
-        # We only want to upload bundle analysis for a PR once,
-        # so we only provide a token for the ubuntu-latest job.
-        CODECOV_TOKEN: ${{ matrix.os == 'ubuntu-latest' && secrets.CODECOV_TOKEN || '' }}
-      run: pnpm build
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+
+      - uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061
+        name: Install pnpm
+        with:
+          run_install: false
+          package_json_file: "package.json"
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "pnpm"
+          cache-dependency-path: "pnpm-lock.yaml"
+
+      - name: Install Dependencies
+        shell: bash
+        run: pnpm install --frozen-lockfile
+
+      - name: Run build
+        env:
+          # We only want to upload bundle analysis for a PR once,
+          # so we only provide a token for the ubuntu-latest job.
+          CODECOV_TOKEN: ${{ matrix.os == 'ubuntu-latest' && secrets.CODECOV_TOKEN || '' }}
+        run: pnpm build

package/.github/workflows/release.yml

@@ -35,19 +35,19 @@ jobs:
       contents: write # For creating release PRs
       pull-requests: write # For creating release PRs
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
         with:
           fetch-depth: 0
           persist-credentials: false
 
-      - uses: pnpm/action-setup@v4
+      - uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061
         name: Install pnpm
         with:
           run_install: false
           package_json_file: package.json
 
       - name: Use Node.js 20.x
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238
         with:
           node-version: 20.x
           cache: pnpm
@@ -82,7 +82,7 @@ jobs:
 
       - name: Create Release Pull Request or Publish to npm
         id: changesets
-        uses: changesets/action@v1
+        uses: changesets/action@6a0a831ff30acef54f2c6aa1cbbc1096b066edaf
         with:
           publish: pnpm publish:ci
         env:
@@ -91,8 +91,5 @@ jobs:
           # the account of someone with appropriate access levels and given the
           # repo scope.
           GITHUB_TOKEN: ${{ secrets.BOT_PA_TOKEN }}
-          # This is the token used to publish to npm when OIDC trusted
-          # publishing isn't yet setup
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
           # This is used for the bundle analysis
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

package/.vscode/settings.json

@@ -0,0 +1,19 @@
+{
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "biomejs.biome",
+    "editor.codeActionsOnSave": {
+        "source.fixAll.biome": "explicit"
+    },
+    "[javascript]": {
+        "editor.defaultFormatter": "biomejs.biome"
+    },
+    "[typescript]": {
+        "editor.defaultFormatter": "biomejs.biome"
+    },
+    "[typescriptreact]": {
+        "editor.defaultFormatter": "biomejs.biome"
+    },
+    "[json]": {
+        "editor.defaultFormatter": "biomejs.biome"
+    }
+}

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# @somewhatabstract/x
+
+## 0.1.0
+
+### Minor Changes
+
+- 2f64864: Implement monorepo script execution tool with multi-package-manager support
+
+  - Add support for npm, Yarn, pnpm, Lerna, Bun, and Rush workspaces
+  - Implement direct script execution without interpreter detection
+  - Add dry-run mode for previewing execution
+  - Comprehensive test coverage
+
+- 2f64864: Support Node-executable script files (.js, .mjs, .cjs)
+
+  Bin scripts with `.js`, `.mjs`, or `.cjs` extensions are now automatically
+  invoked via the Node executable, matching npm/pnpm behavior. Previously, only
+  files with a shebang and executable permissions were supported.
+
+### Patch Changes
+
+- 2f64864: Add test coverage for all source files including the CLI entry point
+- 2f64864: Add Biome for linting and code formatting.

package/CONTRIBUTING.md

@@ -27,7 +27,7 @@ To work in the `x` repository, follow these steps:
 2. Install `pnpm`
    - `corepack enable pnpm`
    - `corepack prepare pnpm --activate`
-3. Run `pnpm install` to install the dependencies
+3. Run `pnpm install` (or `pnpm i`) to install the dependencies
 
 You can now work on `x`. We prefer [🔗Visual Studio Code](https://code.visualstudio.com/) as our development environment (it's cross-platform and awesome), but please use what you feel comfortable with (we'll even forgive you for using vim).
 
@@ -65,6 +65,6 @@ Running the build will execute tests first.
 
 ### Publishing
 
-Publishing is automated through our use of [changesets][1]. When a PR is merged, a release PR is created that bundles all the changes since the last release. This PR is then merged and the changeset is published to npm.
+Publishing is automated through our use of [changesets][1]. When a PR is merged to `main`, a release PR is created that bundles all the changes since the last release. When we are ready to release, this bundled PR is merged to `main` which triggers changesets to publish to npm via trusted publishing.
 
-[1]:https://github.com/changesets/changesets/blob/main/README.md#documentation
+[1]:https://github.com/changesets/changesets/blob/main/README.md#documentation

package/README.md

@@ -1,2 +1,133 @@
 # x
- Execute any bin defined by any package in a monorepo without needing to install that package
+
+Execute any bin defined by any package in a monorepo without needing to install that package.
+
+## Overview
+
+`x` is a tool for monorepos that allows you to execute binary scripts from any package in your workspace without installing them globally or in your current package. It automatically discovers all packages in your workspace and finds the matching bin script.
+
+**Supports multiple package managers:**
+- 📦 npm workspaces
+- 🧶 Yarn (classic and modern)
+- 📌 pnpm workspaces
+- 🎯 Lerna
+- 🍞 Bun workspaces
+- 🚀 Rush
+
+## Installation
+
+```bash
+npm install -g @somewhatabstract/x
+# or
+pnpm add -g @somewhatabstract/x
+# or
+yarn global add @somewhatabstract/x
+```
+
+## Usage
+
+```bash
+# Execute a bin script from any package in the workspace
+x <script-name> [...args]
+
+# Preview what would be executed (dry-run mode)
+x --dry-run <script-name>
+
+# Pass arguments to the script
+x tsc --noEmit
+x eslint src/ --fix
+x jest --watch
+```
+
+### Examples
+
+```bash
+# Run TypeScript compiler from any package that provides it
+x tsc --noEmit
+
+# Run ESLint from any package in the workspace
+x eslint src/
+
+# Preview which jest binary would be executed
+x --dry-run jest
+
+# Run a custom script with arguments
+x my-custom-script arg1 arg2
+```
+
+## Features
+
+- 🔍 **Automatic Discovery**: Finds all packages in your monorepo workspace
+- 🎯 **Smart Matching**: Locates the bin script you want to run
+- 🚀 **No Installation Needed**: Execute bins without installing packages
+- 👁️ **Dry-Run Mode**: Preview what would be executed with `--dry-run`
+- 🔧 **Multi-Language Support**: Works with any executable script (Node.js, Bash, Python, etc.)
+- 📦 **Multi-Package-Manager**: Works with npm, Yarn, pnpm, Lerna, Bun, and Rush
+- ⚡ **Fast**: Efficient package discovery using @manypkg
+- 🛡️ **Type-Safe**: Written in TypeScript with full type safety
+
+## How It Works
+
+1. **Workspace Detection**: Uses `@manypkg/find-root` to find the workspace root (supports npm, Yarn, pnpm, Lerna, Bun, Rush)
+2. **Package Discovery**: Uses `@manypkg/get-packages` to discover all packages in the workspace
+3. **Bin Matching**: Searches through package.json files to find bins matching your requested script name
+4. **Execution**: Executes the matched script directly via the OS (on Unix-like systems this requires an executable file with a shebang; on Windows the bin must be a directly runnable file such as a `.exe`, `.cmd`, or `.bat`)
+
+## Requirements
+
+- Node.js >= 20
+- A monorepo workspace (npm, Yarn, pnpm, Lerna, Bun, or Rush)
+
+## CLI Options
+
+- `<script-name>` - Name of the bin script to execute (required)
+- `[args...]` - Arguments to pass to the script (optional)
+- `-d, --dry-run` - Show what would be executed without running it
+- `-h, --help` - Show help
+- `-v, --version` - Show version
+
+## Error Handling
+
+The tool provides clear, user-friendly error messages:
+
+- **Not in a workspace**: "Could not find workspace root. Make sure you're in a monorepo workspace."
+- **Script not found**: "No bin script named '<name>' found in any workspace package."
+- **Ambiguous match**: Lists all packages that provide the bin and asks you to be more specific
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run tests
+pnpm test
+
+# Type check
+pnpm typecheck
+
+# Build
+pnpm build
+
+# Run locally
+./dist/x.mjs <script-name>
+```
+
+## Architecture
+
+The implementation follows a modular design with separate concerns:
+
+- `errors.ts` - Custom error types for user-friendly messages
+- `find-workspace-root.ts` - Workspace root detection using @manypkg/find-root
+- `discover-packages.ts` - Package discovery via @manypkg/get-packages
+- `find-matching-bins.ts` - Bin script matching logic
+- `execute-script.ts` - Direct script execution
+- `build-environment.ts` - npm/pnpm environment variable construction
+- `resolve-bin-path.ts` - Bin path resolution with security validation (path traversal protection)
+- `x-impl.ts` - Main orchestration logic
+- `bin/x.ts` - CLI entry point with yargs
+
+## License
+
+MIT
+

package/biome.json

@@ -0,0 +1,39 @@
+{
+    "$schema": "https://biomejs.dev/schemas/2.4.3/schema.json",
+    "formatter": {
+        "enabled": true,
+        "indentStyle": "space",
+        "indentWidth": 4,
+        "bracketSpacing": false,
+        "includes": ["**", "!dist/**", "!coverage/**"]
+    },
+    "linter": {
+        "enabled": true,
+        "includes": ["**", "!dist/**", "!coverage/**"]
+    },
+    "assist": {
+        "enabled": true,
+        "includes": ["**", "!dist/**", "!coverage/**"]
+    },
+    "overrides": [
+        {
+            "includes": ["**/*.test.*"],
+            "linter": {
+                "rules": {
+                    "suspicious": {
+                        "noExplicitAny": "off"
+                    }
+                }
+            }
+        },
+        {
+            "includes": ["*.json", "*.jsonc"],
+            "json": {
+                "parser": {
+                    "allowComments": true,
+                    "allowTrailingCommas": true
+                }
+            }
+        }
+    ]
+}