{"_id":"@alanrodas/zxdo","_rev":"3-b9340d559bfdf6f301c5ffc96b4d2d66","name":"@alanrodas/zxdo","dist-tags":{"latest":"0.1.1"},"versions":{"0.0.1":{"name":"@alanrodas/zxdo","version":"0.0.1","author":{"name":"Alan Rodas Bonjour","email":"alanrodas@gmail.com"},"license":"MIT","_id":"@alanrodas/zxdo@0.0.1","maintainers":[{"name":"alanrodas","email":"alanrodas@gmail.com"}],"bin":{"zxdo":"dist/bin.js"},"dist":{"shasum":"eb1dde7dbaf9c1896172e70135c4d22a6b73600f","tarball":"https://registry.npmjs.org/@alanrodas/zxdo/-/zxdo-0.0.1.tgz","fileCount":20,"integrity":"sha512-AH+NQYuw2+IlzlMLH8197UYSW30LwClodCID1UTQ/CrM96GU/YaENcbhfFv6Q7ae7gVfYIcjz6VcnQYv/tRW6g==","signatures":[{"sig":"MEUCIBOQrlYU33zC17cIOXxG8wM3FjmykvKXLNFr1ODRYHMAAiEAi+etlBydXoLaqKXLu1X4ktoHJArjxnSy0GrIRz59zDg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":44933},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"01e6b38217e296de93b7ab81f69b259fdd7b2dec","scripts":{"dev":"vite","doc":"typedoc","lint":"biome lint .","test":"vitest run --coverage","build":"vite build","check":"biome check --unsafe --write .","format":"biome format --write .","test:watch":"vitest"},"_npmUser":{"name":"alanrodas","email":"alanrodas@gmail.com"},"_npmVersion":"11.17.0","description":"A simple task runner built around Google's ZX","directories":{},"_nodeVersion":"26.4.0","allowScripts":{"esbuild@0.21.5":true},"dependencies":{"zx":"^8.1.3","fs-extra":"^11.2.0","concurrently":"^8.2.2"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^5.3.1","vitest":"^1.6.0","typedoc":"^0.28.20","typescript":"^5.5.2","@types/node":"^20.14.9","@biomejs/biome":"^2.5.11","@types/fs-extra":"^11.0.4","vite-plugin-dts":"^3.9.1","@vitest/coverage-v8":"^1.6.1"},"_npmOperationalInternal":{"tmp":"tmp/zxdo_0.0.1_1788289591370_0.2669053479497885","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@alanrodas/zxdo","version":"0.1.0","author":{"name":"Alan Rodas Bonjour","email":"alanrodas@gmail.com"},"license":"MIT","_id":"@alanrodas/zxdo@0.1.0","maintainers":[{"name":"alanrodas","email":"alanrodas@gmail.com"}],"homepage":"https://github.com/alanrodas/zxdo#readme","bugs":{"url":"https://github.com/alanrodas/zxdo/issues"},"bin":{"zxdo":"dist/bin.js"},"dist":{"shasum":"a8aafbab7592672eb0094537b1d2e0fdb359adca","tarball":"https://registry.npmjs.org/@alanrodas/zxdo/-/zxdo-0.1.0.tgz","fileCount":20,"integrity":"sha512-Hk6Jd1J+/eW5kehs2eKU4rH2CYmrTV4nXhWmzyI/vdx4pFXhDP13i7uaeH+xkWsRMzfE8FQtQoWyTAt1O8XixA==","signatures":[{"sig":"MEYCIQC11rw37TFSJ7ZBdI7lriEtMQtlHtRqAM+CxNYBk8lMvwIhALXm9ur63IywqrjS1h3tzPW7a03tzBUSZjV6HtEYSIg5","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alanrodas%2fzxdo@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":44984},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"52b10bdbda330b543617a441c34c3a2ba830a917","scripts":{"dev":"vite","doc":"typedoc","lint":"biome lint .","test":"vitest run --coverage","build":"vite build","check":"biome check --unsafe --write .","format":"biome format --write .","test:watch":"vitest"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:0c167af8-c073-4830-8c88-98c100ecae6f"}},"repository":{"url":"git+https://github.com/alanrodas/zxdo.git","type":"git"},"_npmVersion":"11.19.0","description":"A simple task runner built around Google's ZX","directories":{},"_nodeVersion":"26.8.1","allowScripts":{"esbuild@0.21.5":true},"dependencies":{"zx":"^8.1.3","fs-extra":"^11.2.0","concurrently":"^8.2.2"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^5.3.1","vitest":"^1.6.0","typedoc":"^0.28.20","typescript":"^5.5.2","@types/node":"^20.14.9","@biomejs/biome":"^2.5.11","@types/fs-extra":"^11.0.4","vite-plugin-dts":"^3.9.1","@vitest/coverage-v8":"^1.6.1"},"_npmOperationalInternal":{"tmp":"tmp/zxdo_0.1.0_1788361416233_0.44413018015450656","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@alanrodas/zxdo","version":"0.1.1","description":"A lightweight, convention-based task runner and script orchestrator built around Google's ZX","repository":{"type":"git","url":"git+https://github.com/alanrodas/zxdo.git"},"license":"MIT","author":{"name":"Alan Rodas Bonjour","email":"alanrodas@gmail.com"},"main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","type":"module","bin":{"zxdo":"dist/bin.js"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"dev":"vite","build":"vite build","doc":"npm run doc:api && npm run doc:site","doc:api":"typedoc --options docs/typedoc.config.ts","doc:site":"docusaurus build docs --out-dir ../docs-out","doc:dev":"npm run doc:api && docusaurus start docs","test":"npm run lint && vitest run --coverage","test:watch":"vitest","lint":"biome lint .","format":"biome format --write .","check":"biome check --unsafe --write ."},"dependencies":{"concurrently":"^8.2.2","fs-extra":"^11.2.0","zx":"^8.1.3"},"devDependencies":{"@biomejs/biome":"^2.5.11","@docusaurus/core":"^3.10.2","@docusaurus/faster":"^3.10.2","@docusaurus/preset-classic":"^3.10.2","@types/fs-extra":"^11.0.4","@types/node":"^20.14.9","@types/react":"^19.2.18","@types/react-dom":"^19.2.7","@vitest/coverage-v8":"^1.6.1","react":"^19.2.8","react-dom":"^19.2.8","typedoc":"^0.28.20","typedoc-plugin-markdown":"^4.13.0","typedoc-plugin-mdn-links":"^5.1.1","typedoc-plugin-merge-modules":"^7.0.0","typedoc-plugin-missing-exports":"^4.1.4","typescript":"^5.5.2","vite":"^5.3.1","vite-plugin-dts":"^3.9.1","vitest":"^1.6.0"},"allowScripts":{"esbuild@0.21.5":true},"gitHead":"25d43a619265e659131a9848c61b3d9f854e88a1","_id":"@alanrodas/zxdo@0.1.1","bugs":{"url":"https://github.com/alanrodas/zxdo/issues"},"homepage":"https://github.com/alanrodas/zxdo#readme","_nodeVersion":"26.8.1","_npmVersion":"11.19.0","dist":{"integrity":"sha512-oG0hvka3GmLYY7iU8qys0Qy5ylfrOcSnFf1iKPC4DNEy++ROmL2LXjjmdlNhXQ8UfnXxWIEQzn3l8SxnvKHslQ==","shasum":"6f900e557cd002d3881813c476ad1e95311bc7cb","tarball":"https://registry.npmjs.org/@alanrodas/zxdo/-/zxdo-0.1.1.tgz","fileCount":20,"unpackedSize":56014,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alanrodas%2fzxdo@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCjK1XGIerAEBcXf+Mz/frNwROSKBIy6bItt7itFfe8YgIhANkfsB33aIp+W8yNru0FsfsVUQnM6WU4y+tKSO90DWsq"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:0c167af8-c073-4830-8c88-98c100ecae6f"}},"directories":{},"maintainers":[{"name":"alanrodas","email":"alanrodas@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/zxdo_0.1.1_1788916486181_0.6689784667534293"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-01T19:06:31.105Z","modified":"2026-09-09T01:14:47.263Z","0.0.1":"2026-09-01T19:06:31.516Z","0.1.0":"2026-09-02T15:03:36.363Z","0.1.1":"2026-09-09T01:14:46.297Z"},"bugs":{"url":"https://github.com/alanrodas/zxdo/issues"},"author":{"name":"Alan Rodas Bonjour","email":"alanrodas@gmail.com"},"license":"MIT","homepage":"https://github.com/alanrodas/zxdo#readme","repository":{"type":"git","url":"git+https://github.com/alanrodas/zxdo.git"},"description":"A lightweight, convention-based task runner and script orchestrator built around Google's ZX","maintainers":[{"name":"alanrodas","email":"alanrodas@gmail.com"}],"readme":"# zxdo\n\nA lightweight, convention-based task runner and script orchestrator built around [Google's zx](https://github.com/google/zx).\n\n## What is this\n\n`zxdo` is a command-line tool and library designed to streamline writing, organizing, and executing project tasks and scripts using TypeScript and JavaScript.\n\nInstead of writing complex, multi-line shell scripts embedded in `package.json`, `zxdo` discovers executable script files stored in dedicated folders (such as `scripts/` or `.scripts/`) across your project or monorepo workspace. It automatically inspects JSDoc comments to generate CLI help documentation, intelligently detects and configures the host shell (Bash, Zsh, PowerShell, pwsh, or CMD), and seamlessly forwards arguments to Google `zx`.\n\n## Why would I use this\n\n- **No More Bloated `package.json`**: Move long, brittle script strings out of `package.json` and into modular, maintainable TypeScript or JavaScript files.\n- **Simple Scripting in Your Favorite Language**: Use TypeScript and JavaScript for all your scripting needs, without having to consider shell specifics and different operating systems.\n- **Hierarchical Monorepo Discovery**: Searches up the directory tree to find project and workspace root boundaries (`package.json`). Scripts placed in root `.scripts/` folders are immediately accessible from any subpackage or subdirectory.\n- **Root-Anchored Execution (`cwd`)**: Automatically resolves and runs scripts from the closest project root containing `package.json`, ensuring `./` paths remain consistent regardless of which subfolder you run `zxdo` from.\n- **Automatic Local Bin Resolution**: Automatically prepends all parent `node_modules/.bin` directories to the environment `PATH`, allowing you to run local binaries (e.g. `tsc`, `vite`, `eslint`) directly inside scripts without needing `npx`.\n- **Smart Shell Detection & High Performance**: Detects whether you are running inside PowerShell (`pwsh` / `powershell`), Bash, Zsh, or Command Prompt, caches detection results across child processes, and runs PowerShell commands with `-NoProfile` for up to 6x faster execution on Windows.\n- **Self-Documenting Tasks**: Write JSDoc comments with `@summary`, `@description`, and `@param` in your scripts. `zxdo` reads them to dynamically produce command listings (`zxdo --help`) and detailed command manuals (`zxdo <command> --help`).\n- **Direct Passthrough to Google `zx`**: Any standard `zx` options (such as `--quiet`, `--verbose`, `--install`, or `--eval`) passed before the command name are forwarded directly to `zx`.\n- **Built-in Concurrent Execution**: Bundled with a typed `concurrently` helper that runs tasks in parallel with color-coded labels and unified process output.\n\n## How to use\n\n### Installation\n\nInstall `zxdo` globally or locally within your project:\n\n```bash\n# Globally\nnpm install -g zxdo\n\n# Or locally as a dev dependency\nnpm install --save-dev zxdo\n```\n\nYou can also run it on demand with `npx`:\n\n```bash\nnpx zxdo [options] <command> [command-options]\n```\n\n### Organizing Scripts\n\nBy default, `zxdo` looks for script files inside `.scripts` and `scripts` folders located in any parent project root (where a `package.json` exists):\n\n```text\nmy-project/\n├── package.json\n├── .scripts/\n│   ├── build.ts\n│   ├── test.mts\n│   └── deploy.mjs\n└── packages/\n    └── web/\n        └── .scripts/\n            └── preview.ts\n```\n\nSupported file extensions include: `.mts`, `.cts`, `.ts`, `.mjs`, `.cjs`, `.js`, as well as extensionless executable files.\n\n### Writing Self-Documenting Scripts\n\nScripts can leverage JSDoc annotations to automatically document their usage:\n\n```typescript\n/**\n * @summary Build the project assets\n *\n * Compiles TypeScript source files, bundles client assets, and prepares\n * the production distribution folder.\n *\n * @param -w, --watch, Run in watch mode for development\n * @param -p, --production, Enable production optimizations (minification, tree-shaking)\n */\n\nimport { $, fs } from 'zxdo';\n\nconst isProduction = process.argv.includes('--production');\n\nawait $`echo \"Building assets (production: ${isProduction})...\"`;\n```\n\n### Running Commands\n\nTo run a script, pass its name followed by any arguments intended for that script:\n\n```bash\n# Run the build script\nzxdo build --production\n\n# Run with custom arguments\nzxdo deploy --stage=staging --dry-run\n```\n\n### Built-in Help and Discovery\n\nList all available commands discovered across your project's scope:\n\n```bash\nzxdo --help\n# or\nzxdo\n```\n\nView the detailed documentation and options for a specific script:\n\n```bash\nzxdo --help build\n```\n\nDisplay version information:\n\n```bash\nzxdo --version\n# or\nzxdo -v\n```\n\n### Tool Options\n\nConfigure `zxdo` itself using the following CLI flags before the command name:\n\n| Option | Description | Default |\n| --- | --- | --- |\n| `--shell=<name>` | Sets the shell used by `zx` (`auto`, `bash`, `pwsh`, `powershell`, `zsh`, or any other shell with full path) | `auto` |\n| `--cwd=<dir>` | Sets the working directory from which commands should run | Closest `package.json` root |\n| `--folders=<list>` | Colon-separated folder names to search for scripts | `scripts:.scripts` |\n| `--extensions=<list>` | Colon-separated allowed script file extensions | `:.mts:.cts:.ts:.mjs:.cjs:.js` |\n| `-v`, `--version` | Display current `zxdo` version | `false` |\n| `-h`, `--help` | Display help or command documentation | `false` |\n\n### Passthrough to Google `zx`\n\nFlags unrecognized by `zxdo` passed before the command name are forwarded directly to `zx`:\n\n```bash\n# Run with zx quiet output\nzxdo --quiet build\n\n# Execute code directly using zx --eval\nzxdo --eval 'await $`ls -la`'\n```\n\n### Usage as a Library\n\n`zxdo` can also be imported programmatically inside your scripts and tools. It provides pre-configured shell settings, Google's `zx` utilities, `fs-extra`, and a typed `concurrently` wrapper:\n\n```typescript\nimport { $, fs, concurrently } from 'zxdo';\n\n// 1. Execute commands via zx:\n//    - Automatically uses detected host shell with PowerShell profile bypass\n//    - Working directory anchored to closest project root\n//    - Local node_modules/.bin tools (tsc, vite, etc.) available directly\n//    - Output streamed in real-time (stdio: 'inherit')\nawait $`tsc --noEmit`;\n\n// 2. Inspect active execution properties on $\nconsole.log($.shell); // e.g., 'pwsh'\nconsole.log($.cwd);   // e.g., 'C:\\projects\\my-repo'\n\n// 3. Use enhanced file system operations from fs-extra\nawait fs.ensureDir('./dist/temp');\n\n// 4. Run multiple commands in parallel with colored labels\nawait concurrently({\n  client: 'vite dev',\n  server: {\n    script: 'nodemon server.ts',\n    color: 'blue.bold'\n  }\n});\n```\n\nThe active configuration resolved by `zxdo` is also exposed via environment variables (`process.env.ZXDO_SHELL`, `process.env.ZXDO_CWD`, `process.env.ZXDO_ROOTS`).\n\n## Contributing\n\nContributions to `zxdo` are welcome! To set up the repository for development:\n\n1. **Clone the repository**:\n   ```bash\n   git clone https://github.com/gobstones/zxdo.git\n   cd zxdo\n   ```\n\n2. **Install dependencies**:\n   ```bash\n   npm install\n   ```\n\n3. **Run tests**:\n   ```bash\n   npm test\n   ```\n\n4. **Lint and format code**:\n   The project uses [Biome](https://biomejs.dev/) for code formatting and linting:\n   ```bash\n   # Check linting and formatting\n   npm run check\n\n   # Automatically format files\n   npm run format\n   ```\n\n5. **Build the project**:\n   ```bash\n   npm run build\n   ```\n\nPlease make sure all unit tests pass and code adheres to the project's formatting rules before opening a pull request.\n\n## License\n\n[MIT](LICENSE) © 2026 Alan Rodas Bonjour\n","readmeFilename":"README.md"}