fix: support command metadata validation on Node.js 24.20+

[0xtlt]

Description

Fixes #169.

Starting with Node.js 24.20.0, command metadata validation can fail with an Invalid URL error.

The command metadata schema uses local fragment references, but does not define a base URI. jsonschema therefore attempts to resolve these references against its anonymous base, which is rejected by newer Node.js URL parsing behavior.

This change defines a stable, non-HTTP schema identifier:

adonisjs://ace/command-metadata

It is used only as an in-memory base URI when resolving references such as #/definitions/CommandMetaData. It is never fetched over the network.

Compatibility

Verified with:

• Node.js 24.19.0: 10/10 targeted tests passing
• Node.js 24.20.0: 10/10 targeted tests passing
• Node.js 26.7.0: 10/10 targeted tests passing
• Node.js 26.7.0: 256/256 full test suite passing

Changes

Adds a $id to the command metadata JSON schema:

 export const schema = {
+  $id: "adonisjs://ace/command-metadata",
   $ref: "#/definitions/CommandMetaData",

Summary by CodeRabbit

• Enhancements
  • Added a unique identifier to the command metadata schema for improved schema recognition and tooling compatibility.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: bd5472fa-574d-470e-9884-49d661629675

📥 Commits

Reviewing files that changed from the base of the PR and between 407ddae and 5fe1e0c.

📒 Files selected for processing (1)

• schemas/main.ts

Included review availability: Your plan provides up to 2 included reviews per hour; 1 remains after this review.

---

📝 Walkthrough

Walkthrough

The exported command metadata JSON schema now includes the $id value adonisjs://ace/command-metadata. No other schema definitions changed.

Changes

Command metadata schema

Layer / File(s)	Summary
Add schema identifier schemas/main.ts	The exported schema now declares $id as adonisjs://ace/command-metadata.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Merge Risk: ⚪ Minimal · up to 5fe1e

This localized schema change provides a stable identifier for command metadata reference resolution on newer Node.js versions; no actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the fix for command metadata validation on newer Node.js versions. It matches the primary change.
Linked Issues check	✅ Passed	The change adds the stable schema base URI required to resolve local references and prevent the Invalid URL error reported in issue #169. This supports successful custom command discovery on Node.js 2…
Out of Scope Changes check	✅ Passed	The pull request changes only the command metadata schema identifier. This change directly supports issue #169 and introduces no unrelated code changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1…

Full details: Linked Issues check

Explanation

The change adds the stable schema base URI required to resolve local references and prevent the Invalid URL error reported in issue #169. This supports successful custom command discovery on Node.js 24.20.0 and newer.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1 files.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

Some tools did not complete. Review the errors below.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

schemas/main.ts

ESLint skipped: missing config or dependency (missing-dependency). The ESLint configuration references a package that is not available in the sandbox.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[RomainLanz]

Thanks! 💜