Installation

Installation

Requirements

Node.js 24. The engines field pins >=24 <25, so npm will warn or refuse on another major depending on your configuration.

There are no runtime dependencies. npm ci installs nothing except what the lockfile needs for the toolchain, and the lockfile is deliberately empty of production packages. If npm ls --prod ever prints a dependency tree, something went wrong.

From the repository

git clone https://github.com/thiagocorreanet/mestre-yoda.git
cd mestre-yoda
npm ci
npm run verify

npm run verify runs the test suite and then the catalog integrity check. A healthy run ends like this:

ℹ tests 12
ℹ pass 12
ℹ fail 0

Verification complete: 44 files, 1 profile, zero generated artifacts.

If the tests pass but check fails, the problem is in the catalog rather than in the code. See Authoring a profile.

Running it

Three ways, in increasing order of convenience.

Straight from the clone, with no install step at all:

node bin/mestre-yoda.mjs handshake

Through the npm script, which is handy inside the repository:

npm run mestre-yoda -- check dotnet-modular-react-postgresql --root /path/to/project

Note the -- before the arguments. Without it, npm swallows the flags.

Globally, so the command works from any directory:

npm install --global .
mestre-yoda handshake

To remove the global install later:

npm uninstall --global mestre-yoda

What gets installed where

The files field publishes bin/, catalog/, docs/, schemas/, src/, LICENSE, and README.md. The catalog travels with the package, which is why mestre-yoda profiles works immediately after a global install without any configuration file or network call.

Nothing is installed into the project you analyze. Mestre Yoda reads that project and writes nothing back. See the security model for the exact boundaries.

Verifying the install

mestre-yoda version
mestre-yoda handshake
mestre-yoda validate

Expected output:

Mestre Yoda 0.1.0

Provider: mestre-yoda@0.1.0
Protocol: 1.0.0
Mode: read-only
Capabilities: profiles.list, profiles.describe, project.inspect, project.recommend, project.check, project.plan, catalog.validate

Catalog is valid: 1 profile(s).

If handshake reports Mode: read-only and validate reports a valid catalog, the install is good.

Pinning a version

For anything automated, install from a tag rather than from main:

npm install --global github:thiagocorreanet/mestre-yoda#v0.1.0

Pipelines should also pin the profile digest they approved, not just the tool version. A profile can change inside a compatible tool release, and the digest is what tells you that it did. See CI integration.

Troubleshooting

Unsupported engine during install means you are not on Node 24. Check with node --version.

Cannot find module when running node bin/mestre-yoda.mjs usually means you are outside the clone. The binary resolves the catalog relative to its own location, so run it by full path or install it globally.

Error: The --root option requires a directory. means --root was the last argument or was followed by another flag. It needs a path right after it.

Exit code 2 with no visible output means you passed --json and the failure envelope went to stderr. Redirect with 2>&1 to see it.