fix(cli): run when reached through a symlinked entry path

[altaywtf]

Closes #21

Summary

vref's CLI guarded its entry point with:

if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href)

Node canonicalises import.meta.url through symlinks but leaves process.argv[1] exactly as the caller wrote it. So the comparison fails whenever the CLI is reached via a symlink — which is the normal case under pnpm, where node_modules/<pkg> links into node_modules/.pnpm/….

Whether the CLI worked came down to which path the generated bin shim used:

shim target	guard	result
…/.bin/../.pnpm/@putdotio+vref@1.1.0/…/dist/cli.mjs	passes	CLI runs
…/.bin/../@putdotio/vref/dist/cli.mjs	fails	exits 0, does nothing

Both occur in practice. putio-roku got the first. A fresh pnpm add -D @putdotio/vref in putio-ios got the second, where vref describe, vref build and vref validate all silently no-op — same pnpm 11.2.2, same Node 24.18.0, same package checksum.

The silence is the dangerous part: a CI step running vref build --check passes while validating nothing.

Changed

• New exported isDirectInvocation(moduleUrl, entryPath) canonicalises both sides before comparing, so the behaviour is testable without spawning a process
• A missing or non-existent argv[1] falls through to the plain comparison instead of throwing during startup

Review aids

Built dist/cli.mjs, symlinked it, and invoked through the link — the case that produced no output before:

$ node "$TMP/linked-vref.mjs" describe --output json --fields name
{ "ok": true, "result": { "name": "vref" } }

$ node dist/cli.mjs describe --output json --fields name
{ "ok": true, "result": { "name": "vref" } }

Verification

pnpm run verify green — format, lint, typecheck, 22 tests (3 new), npm pack --dry-run.

New tests cover a symlinked entry path (direct invocation), the real path (still direct), an unrelated path and undefined (both not direct), and a non-existent path (returns false rather than throwing).

Complexity

Low. One guard, one exported helper.

[Copilot]

Pull request overview

This PR fixes a long-standing CLI entry-point guard bug where vref could silently no-op when invoked through a symlinked path (commonly produced by pnpm’s node_modules/@scope/pkg symlink layout). It introduces a small, testable helper that canonicalizes the entry path before comparing it to import.meta.url, preventing false negatives and ensuring vref build/validate/describe actually run in CI.

Changes:

• Added isDirectInvocation(moduleUrl, entryPath) to canonicalize the entry path via realpathSync() before comparing URLs.
• Updated the CLI entry guard to use isDirectInvocation(import.meta.url, process.argv[1]).
• Added regression tests covering symlinked entry paths, unrelated paths, undefined, and non-existent paths.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
src/cli.ts	Adds isDirectInvocation and updates the CLI entry-point guard to handle symlinked invocation paths reliably.
test/vref.test.ts	Adds tests validating direct-invocation detection for symlinked paths and error-tolerant behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[putio-releaser]

🎉 This PR is included in version 1.1.1 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀