@mawesome/npm-vm 0.0.0-alpha.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manzoor Ahmad Wani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,52 @@
 # @mawesome/npm-vm
 
-Placeholder release reserving the name. The first implementation ships in 0.1.0 from https://github.com/mawesomedev/mawesome/tree/main/packages/npm-vm.
+> Run the npm version a project declares in `devEngines`, whatever Node is active.
+
+A new npm ships, your projects want it, and no Node release bundles it yet. Or an old branch still needs the npm it was built with. `npm-vm` puts an `npm` shim first on `PATH` that reads `devEngines.packageManager` from the project npm itself would use. When Node's own npm satisfies the range, it runs unchanged. Otherwise the newest matching release that supports the active Node is downloaded once through Node's own npm, verified, cached per machine and run from there. It works with nvm, fnm and nvm-windows, and a project that declares nothing sees no difference.
+
+📚 Full documentation lives in [`docs/`](./docs/): [get started](./docs/get-started.md), [how it works](./docs/how-it-works.md), [CLI](./docs/cli.md), [shells and Node managers](./docs/shells.md), [security](./docs/security.md), [GitHub Action](./docs/action.md).
+
+## Install
+
+```sh
+npx --prefix ~ -y @mawesome/npm-vm setup
+```
+
+Then open a new terminal and run `npm-vm doctor`.
+
+## Declare
+
+```sh
+npm-vm pin ^12.0.0
+```
+
+```json
+{
+	"devEngines": {
+		"packageManager": { "name": "npm", "version": "^12.0.0", "onFail": "error" }
+	}
+}
+```
+
+## Use
+
+```sh
+npm ci    # npm ^12 in this project
+npm -v    # Node's own npm in a project that declares nothing
+```
+
+Global installs (`npm i -g`) always use Node's own npm.
+
+## In CI
+
+```yaml
+- uses: mawesomedev/npm-vm-action@v1
+```
+
+## Requirements
+
+Node 22.9 or newer runs the tool; below that the launcher falls back to Node's own npm and says so. Node's own npm must be 8 or newer to act as the download transport.
+
+## License
+
+[MIT](../../LICENSE)