Package ref grammar

This page is the formal grammar accepted by Matrix tooling that takes a package reference (e.g. mx install <ref>, matrix run <ref>).

Grammar

PackageRef        ::= ScopedRef | PathRef

ScopedRef         ::= ScopedName ('@' VersionOrTag)?
ScopedName        ::= '@' Org '/' PackageName
Org               ::= [A-Za-z0-9][A-Za-z0-9._-]*
PackageName       ::= [A-Za-z0-9][A-Za-z0-9._-]*
VersionOrTag      ::= ExactVersion | SemverRange | DistTag
ExactVersion      ::= SemverVersion
SemverRange       ::= ('^'|'~'|'>'|'<'|'='|'>='|'<=')? SemverVersion ( ' '+ ('^'|...) SemverVersion )*
                    | SemverRange ' || ' SemverRange
SemverVersion     ::= [0-9]+ '.' [0-9]+ '.' [0-9]+ ('-' PreReleaseId)? ('+' BuildMetadata)?
PreReleaseId      ::= AlphanumericDot
BuildMetadata     ::= AlphanumericDot
DistTag           ::= [A-Za-z][A-Za-z0-9-]*

PathRef           ::= AbsolutePath | RelativePath
AbsolutePath      ::= '/' anything-the-OS-accepts
RelativePath      ::= ('./' | '../') anything-the-OS-accepts

Concrete examples

Scoped refs

Ref	Meaning
@open-matrix/chat	Latest version of @open-matrix/chat (dist-tag latest)
@open-matrix/chat@0.2.3	Exact version
@open-matrix/chat@^0.2	Semver range >=0.2.0 <0.3.0
@open-matrix/chat@beta	Whatever the beta dist-tag points at
@open-matrix/chat@>=0.2.0 <0.3.0	Explicit range

Path refs

Ref	Meaning
./packages/chat	Relative path from cwd, must contain package.json
/work/my-chat-plugin	Absolute path

What is rejected

Ref	Why rejected
chat	No scope. Matrix tooling requires @scope/name.
chat@1	Same — missing scope.
@open-matrix	Missing package name after slash.
@open-matrix/	Missing package name.
@@open-matrix/chat	Invalid scope start.
https://.../chat-0.2.3.tgz	Tarball URLs are not currently supported by Matrix tooling.
git+ssh://...	Git refs are not currently supported.

These are policy decisions, not grammatical limits — npm itself accepts tarball URLs and git refs. Matrix tooling does not pass them through today.

Where the grammar lives

The grammar is enforced by the CLI argument parser in projects/matrix-3/packages/mx-cli/src. There is no single regex or PEG grammar file; the rules above are derived from the parser's behavior. When the parser is extracted to a dedicated module, that module becomes the authoritative reference.

Relation to npm's grammar

Matrix's grammar is a strict subset of npm's. Anything Matrix accepts, npm accepts. The reverse is not true (tarball URLs, git refs, file: refs, are all valid to npm but not exposed by Matrix tooling).

See also

• Package refs — the user-facing intro
• Version ranges — semver detail

Source: Argument parsing in projects/matrix-3/packages/mx-cli/src. The grammar is the parser's behavior; this page is its summary.