@somewhatabstract/x 0.1.0 → 0.2.0

package/README.md

@@ -1,12 +1,13 @@
 # x
 
-Execute any bin defined by any package in a monorepo without needing to install that package.
+Execute any bin defined by any package within a monorepo without needing to install that package at the root.
 
 ## 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
@@ -28,32 +29,16 @@ yarn global add @somewhatabstract/x
 
 ```bash
 # Execute a bin script from any package in the workspace
-x <script-name> [...args]
+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
+# Pass arguments to the script (use `--` when args might look like x's own options)
+x my-script -- --flag value
 ```
 
-### 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
-```
+This only executes bin scripts defined by packages in your workspace, not their dependencies. The bin must be an executable file with a shebang (on Unix-like systems) or a directly runnable file (on Windows), or a JS script that can be executed with Node.js.
 
 ## Features
 
@@ -71,7 +56,9 @@ x my-custom-script arg1 arg2
 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`)
+4. **Execution**: Executes the matched script either directly via the OS or via Node.js:
+   - **Direct OS execution**: 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`.
+   - **Node.js execution**: If the bin is a JS file, it is executed with Node.js.
 
 ## Requirements
 
@@ -113,21 +100,6 @@ pnpm build
 ./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/dist/x.mjs

@@ -7,7 +7,6 @@ import * as fs from "node:fs/promises";
 import * as path$1 from "node:path";
 import path from "node:path";
 import { findRoot } from "@manypkg/find-root";
-
 //#region src/errors.ts
 /**
 * Error class for known/expected errors that should be displayed to the user
@@ -19,7 +18,6 @@ var HandledError = class extends Error {
 		this.name = "HandledError";
 	}
 };
-
 //#endregion
 //#region src/discover-packages.ts
 /**
@@ -42,7 +40,6 @@ async function discoverPackages(workspaceRoot) {
 		throw new HandledError(`Failed to discover packages`, { cause: error });
 	}
 }
-
 //#endregion
 //#region src/build-environment.ts
 /**
@@ -93,7 +90,6 @@ async function buildEnvironment(workspaceRoot, currentEnv) {
 	}
 	return env;
 }
-
 //#endregion
 //#region src/is-node-executable.ts
 /**
@@ -108,7 +104,6 @@ function isNodeExecutable(binPath) {
 	const lower = binPath.toLowerCase();
 	return lower.endsWith(".js") || lower.endsWith(".mjs") || lower.endsWith(".cjs");
 }
-
 //#endregion
 //#region src/execute-script.ts
 /**
@@ -138,7 +133,6 @@ async function executeScript(bin, args, workspaceRoot) {
 		});
 	});
 }
-
 //#endregion
 //#region src/resolve-bin-path.ts
 /**
@@ -162,7 +156,6 @@ function resolveBinPath(pkg, bin, binName) {
 	if (resolvedBinPath !== packageDir && !resolvedBinPath.startsWith(packageDir + path.sep)) return null;
 	return resolvedBinPath;
 }
-
 //#endregion
 //#region src/find-matching-bins.ts
 /**
@@ -192,7 +185,6 @@ async function findMatchingBins(packages, binName) {
 	}
 	return matches;
 }
-
 //#endregion
 //#region src/find-workspace-root.ts
 /**
@@ -210,7 +202,6 @@ async function findWorkspaceRoot(startDir = process.cwd()) {
 		throw new HandledError("Could not find workspace root. Make sure you're in a monorepo workspace.", { cause: error });
 	}
 }
-
 //#endregion
 //#region src/x-impl.ts
 /**
@@ -255,33 +246,35 @@ async function xImpl(scriptName, args = [], options = {}) {
 		throw error;
 	}
 }
-
 //#endregion
 //#region src/bin/x.ts
-const argv = yargs(hideBin(process.argv)).usage("Usage: $0 <script-name> [...args]").command("$0 <script-name> [args..]", "Execute a bin script from any package in the workspace", (yargs) => {
+const rawArgs = hideBin(process.argv);
+const argv = yargs(rawArgs).usage("Usage: $0 <script-name> [...args]").command("$0 <script-name>", "Execute a bin script from any package in the workspace", (yargs) => {
 	return yargs.positional("script-name", {
 		describe: "Name of the bin script to execute",
 		type: "string",
 		demandOption: true
-	}).positional("args", {
-		describe: "Arguments to pass to the script",
-		type: "string",
-		array: true,
-		default: []
 	});
 }).option("dry-run", {
 	alias: "d",
 	describe: "Show what would be executed without running it",
 	type: "boolean",
 	default: false
-}).help().alias("help", "h").version().alias("version", "v").example("$0 tsc --noEmit", "Run TypeScript compiler from any package").example("$0 eslint src/", "Run ESLint from any package that provides it").example("$0 --dry-run jest", "Preview which jest would be executed").strict().parseSync();
+}).help().alias("help", "h").version().alias("version", "v").example("$0 tsc --noEmit", "Run TypeScript compiler from any package").example("$0 eslint src/", "Run ESLint from any package that provides it").example("$0 --dry-run jest", "Preview which jest would be executed").parserConfiguration({ "unknown-options-as-args": true }).parseSync();
 const scriptName = argv["script-name"];
-xImpl(scriptName, argv._ || [], { dryRun: argv["dry-run"] }).then((result) => {
+const args = argv._ || [];
+const options = { dryRun: argv["dry-run"] };
+if (!rawArgs.includes("--")) {
+	if (args.filter((arg) => typeof arg === "string" && arg.startsWith("-")).length > 0) {
+		console.warn(`Tip: To pass flags to "${scriptName}", use '--' to separate them:`);
+		console.warn(`  x ${scriptName} -- ${args.join(" ")}`);
+	}
+}
+xImpl(scriptName, args, options).then((result) => {
 	process.exit(result.exitCode);
 }).catch((error) => {
 	console.error("Unexpected error:", error);
 	process.exit(1);
 });
-
 //#endregion
-export {  };
+export {};

package/package.json

@@ -8,8 +8,11 @@
   "bin": {
     "x": "./dist/x.mjs"
   },
+  "files": [
+    "dist"
+  ],
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Execute any bin defined by any package in a monorepo without needing to install that package",
   "bugs": {
     "url": "https://github.com/somewhatabstract/x/issues"
@@ -24,13 +27,13 @@
     "yarn": "please-use-pnpm"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.3",
+    "@biomejs/biome": "^2.4.6",
     "@changesets/cli": "^2.29.8",
     "@codecov/rollup-plugin": "^1.9.1",
     "@types/node": "^20.19.29",
     "@types/yargs": "^17.0.35",
     "@vitest/coverage-v8": "^4.0.17",
-    "tsdown": "0.20.3",
+    "tsdown": "0.21.6",
     "typescript": "^5.9.3",
     "vitest": "^4.0.17"
   },

package/.changeset/README.md

@@ -1,8 +0,0 @@
-# Changesets
-
-Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
-with multi-package repos, or single-package repos to help you version and publish your code. You can
-find the full documentation for it [in our repository](https://github.com/changesets/changesets)
-
-We have a quick list of common questions to get you started engaging with this project in
-[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

package/.changeset/config.json

@@ -1,11 +0,0 @@
-{
-    "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
-    "changelog": "@changesets/cli/changelog",
-    "commit": false,
-    "fixed": [],
-    "linked": [],
-    "access": "restricted",
-    "baseBranch": "main",
-    "updateInternalDependencies": "patch",
-    "ignore": []
-}

package/.github/codeql/codeql-config.yml

@@ -1,5 +0,0 @@
-name: X CodeQL config
-paths:
-  - "src"
-paths-ignore:
-  - src/__tests__

package/.github/dependabot.yml

@@ -1,28 +0,0 @@
-# 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

@@ -1,71 +0,0 @@
-# For most projects, this workflow file will not need changing; you simply need
-# to commit it to your repository.
-#
-# You may wish to alter this file to override the set of languages analyzed,
-# or to provide custom queries or build logic.
-#
-# ******** NOTE ********
-# We have attempted to detect the languages in your repository. Please check
-# the `language` matrix defined below to confirm you have the correct set of
-# supported CodeQL languages.
-#
-name: "CodeQL"
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    # The branches below must be a subset of the branches above
-    branches: [main]
-  schedule:
-    - cron: "16 7 * * 2"
-
-jobs:
-  analyze:
-    name: Analyze
-    runs-on: ubuntu-latest
-    permissions:
-      actions: read
-      contents: read
-      security-events: write
-
-    strategy:
-      fail-fast: false
-      matrix:
-        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@de0fac2e4500dabe0009e67214ff5f5447ce83dd
-
-      # 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@710e2945787622b429f8982cacb154faa182de18
-
-      # ℹ️ 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
-
-      #- run: |
-      #   make bootstrap
-      #   make release
-
-      - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@710e2945787622b429f8982cacb154faa182de18

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

@@ -1,36 +0,0 @@
-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

@@ -1,129 +0,0 @@
-name: Node CI
-
-on:
-  pull_request:
-    # ready_for_review is useful for when a PR is converted from "draft" to "not
-    # draft".
-    types: [edited, opened, synchronize, ready_for_review, reopened]
-
-  push:
-    branches:
-      - main
-
-jobs:
-  lint:
-    name: Lint and static types check
-    env:
-      CI: true
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        os: [ubuntu-latest]
-        node-version: [20.x]
-    steps:
-      - 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
-    env:
-      CI: true
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        os: [ubuntu-latest]
-        node-version: [20.x]
-    steps:
-      - 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]
-    name: Build
-    env:
-      CI: true
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        os: [ubuntu-latest]
-        node-version: [20.x]
-    steps:
-      - 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

@@ -1,95 +0,0 @@
-name: Release
-
-on:
-  push:
-    branches:
-      - main
-
-# This workflow will run changesets depending on two different scenarios:
-#
-# 1. If we are landing a specific commit into main (Author PR), then
-#    changesets will check if there are changes verifying the Markdown files
-#    generated automatically:
-#
-#    a) There are new versions and there's NO Release PR, then the changesets
-#    action will create a new Release PR.
-#
-#    b) There's a Release PR, then the changesets action will update the
-#    existing Release PR with the new commit.
-#
-#    NOTE: (in both cases, changesets will modify the new version in
-#    package.json for each package, and will remove the MD files as part of the
-#    Release PR).
-#
-# 2. If we are landing the Release PR into main, then the changesets action
-#    will publish the changes to npm.
-#
-# For more info about this workflow, see:
-# https://github.com/changesets/action#usage
-jobs:
-  release:
-    name: Release
-    runs-on: ubuntu-latest
-    permissions:
-      id-token: write # For provenance and trusted publishing
-      contents: write # For creating release PRs
-      pull-requests: write # For creating release PRs
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
-        with:
-          fetch-depth: 0
-          persist-credentials: false
-
-      - 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@6044e13b5dc448c55e2357c09f80417699197238
-        with:
-          node-version: 20.x
-          cache: pnpm
-          cache-dependency-path: pnpm-lock.yaml
-
-      - name: Install Dependencies
-        shell: bash
-        run: pnpm install --frozen-lockfile
-
-      - name: ⬆️ Upgrade npm for OIDC support
-        shell: bash
-        run: |
-          # npm trusted publishing requires npm CLI v11.5.1+
-          # Node.js 20 shipped with npm 9.x, so we likely need to upgrade
-
-          # First, let's check the current npm version, and if it's already
-          # sufficient, we can skip the upgrade step.
-          CURRENT_NPM_VERSION=$(npm --version)
-          REQUIRED_NPM_VERSION="11.5.1"
-
-          # This sorts the version numbers using `sort -V` and then takes
-          # the lowest version.
-          LOWEST_NPM_VERSION=$(printf '%s\n' "$REQUIRED_NPM_VERSION" "$CURRENT_NPM_VERSION" | sort -V | head -n1)
-
-          # If the lowest version is the same as the required version, then we
-          # don't need to upgrade as that means our current version is newer.
-          if [ "$LOWEST_NPM_VERSION" = "$REQUIRED_NPM_VERSION" ]; then
-            echo "✅ npm is already at version $CURRENT_NPM_VERSION"
-          else
-            npm install -g npm@latest && echo "✅ npm upgraded to $(npm --version)"
-          fi
-
-      - name: Create Release Pull Request or Publish to npm
-        id: changesets
-        uses: changesets/action@6a0a831ff30acef54f2c6aa1cbbc1096b066edaf
-        with:
-          publish: pnpm publish:ci
-        env:
-          # We use a Personal Access Token here rather than the GITHUB_TOKEN
-          # so that it will trigger our other actions. The token has to be on
-          # the account of someone with appropriate access levels and given the
-          # repo scope.
-          GITHUB_TOKEN: ${{ secrets.BOT_PA_TOKEN }}
-          # This is used for the bundle analysis
-          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

package/.vscode/settings.json

@@ -1,19 +0,0 @@
-{
-    "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

@@ -1,23 +0,0 @@
-# @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.