A package manager for KerML / SysML v2 project-interchange packages: a package is any git
repository with .project.json at a tag (Subversion and Mercurial too). Binary: syspi.
SysPI fetches, verifies, installs and locks packages. It is independent of
OpenSysML, whose sysml and sysml-lsp only read
what package managers install.
- Identity — an ECMA-427 Package-URL of type
genericwith the Annex B.3.5vcs_urlqualifier for a repository (ordownload_urlfor a hosted.kpar, under "Other sources"): qualifier:pkg:generic/<name>?vcs_url=<vcs>+<transport>://[<user>@]<host>/<path>[@<version>][#<subpath>], the qualifier percent-encoded (+→%2B,/→%2F,@→%40,#→%23,:kept), e.g.pkg:generic/OpenSysML-Extensions-Library?vcs_url=git%2Bhttps:%2F%2Fgithub.com%2FOpen-MBEE%2FOpenSysML-Extensions-Library%401.0.0.<vcs>isgit,svnorhg,<transport>one of Annex B.3.5's (git,https,http,sshfor git;http,https,static-http,sshfor hg;svn,http,https,sshfor svn) plusfilefor a repository on this machine;<name>is the repository's last path segment.<user>@is the SSH login and is accepted on<vcs>+sshonly (git+ssh://git@github.com/owner/repo@1.2.0); it is part of the identity, so it is written to.project.jsonand the lock as…git%2Bssh:%2F%2Fgit%40github.com%2F…, and the same location without it is another identity. A password, or a user name on any other transport, is refused. Two shorter spellings are accepted as input and normalised to it:pkg:git/<host>/<path>[@<version>][#<subpath>](git over https) and the bare notationgit+https://host/path@1.2.0,git+ssh://git@host/path@1.2.0,svn://host/repo@1.2.0,hg+https://…,git+file:///srv/repo@1.2.0(git+file:///C:/repo@1.2.0on Windows). Refused with a message naming those three:pkg:svn/…,pkg:hg/…,pkg:github/…, plain clone URLs (https://host/path.git,ssh://…,git@host:path,file:///path@1.2.0) and a commit id as version. SysPI hand-parses this one purl shape and uses no purl library. A plainhttp(s)IRI is only ever read as a project interchange file (KerML 1.1 §10.3 Table 12), never cloned. - Package — the tagged tree (or
#<subpath>within it) is the project directory:.project.json(KerML 1.1 §10.3, Table 12) at the tag is mandatory and itsversionmust equal the tag,v<semver>preferred, bare<semver>accepted. No.project.jsonis an error; nothing is ever synthesised. For svn, tags are the directories undertags/. - Resolution — pure version control through the user's own
git,svnorhgexecutable, so credential helpers, SSH and proxy configuration apply: list tags, export the tagged tree, record the revision. No index is needed. - Install layout —
lib/<publisher>-<name>_<version>/(a tree) orlib/<publisher>-<name>_<version>.kpar(an archive) beside the consuming.project.json. - Lock —
.project.lock.jsonbeside.project.json: one entry per package of the transitive closure withresource,kind,vcs,source,tag,revision,sha256and the usages it declares; deterministic bytes, so a fresh clone reproduces it exactly. A lock entry wins over a constraint everywhere but inupdate, the one command that moves an entry the graph can keep (outdatedshows what it would move); an entry whose version conflicts with another usage is re-resolved to another matching tag. - Constraints —
versionConstraintin.project.json: exact (1.2.0), caret (^1.2.0), tilde (~1.2.0) and comparison ranges (>=1.2.0 <2.0.0).@<version>in the resource with noversionConstraintis an exact constraint. - Verification before use —
.meta.jsonchecksums of every member (regenerated for the installed copy, and said so, when a tag tree has none), the recorded revision, the tree or.kparSHA-256, and path-traversal, symlink and size bounds on every archive and export. - Other sources — a local directory (editable, read in place), a local
.kpar, a remote.kparURL, OMG standard-library IRIs (https://www.omg.org/spec/{KerML,SysML}/…/*.kpar, recorded but never installed: every reader bundles them). A.kparhosted at any http(s) URL — a release asset, a repository manager's export — is also a Package-URL with the Annex B.3.5download_urlqualifier and an optionalchecksum:pkg:generic/<name>[@<version>]?download_url=<url>[&checksum=<algorithm>:<hex>[,…]], both percent-encoded (pkg:generic/tools?checksum=sha256:9f86…&download_url=https:%2F%2Fdist.example.org%2Ftools.kpar). The archive is fetched as a plain.kparURL is (netrc, redirects, size bound), the declared checksums are verified before it is opened (a mismatch installs nothing),<version>is the archive's own and is held to@<version>/versionConstraint, and the lock'ssha256is the archive digest.
Details — the grammar, the svn tags/ convention, the tree-hash algorithm and the lock format —
are in docs/packages.md.
syspi init [-C dir] [-publisher P] [-name N] [-version V] write .project.json and .meta.json
syspi add <resource>[@<version>] [<constraint>] add a usage, resolve, install, lock
syspi remove <resource>... drop a usage, re-lock, remove what nothing else needs from lib/
syspi update [<resource>...] move the named (or all) usages to the highest version allowed, install, re-lock
syspi outdated [-json] [<resource>...] report what update would move; write nothing
syspi install | sync resolve .project.json + lock, install what is missing or changed
syspi lock write .project.lock.json without installing
syspi verify check lib/ against the lock, offline; exit 1 on any discrepancy, write nothing
syspi list [-json] the locked packages, where each is in lib/ and whether it is present
syspi bundle [-o out.kpar] [-tag T] [-index index.json] <dir>
syspi publish <archive.kpar> <https-url.kpar> verify and upload to a conditional PUT artifact host
Every project command takes -C <dir> and -offline. Every command works offline when the lock
and lib/ already satisfy the project.
$ syspi init -publisher acme -name rover
initialised acme-rover_0.1.0 in . (.project.json, .meta.json)
$ syspi add pkg:git/github.com/MBSE4U/sysmod-sysmlv2@5.1.5
pkg:generic/sysmod-sysmlv2?vcs_url=git%2Bhttps:%2F%2Fgithub.com%2FMBSE4U%2Fsysmod-sysmlv2: tag 5.1.5: .meta.json records no checksum for 48 of 52 files; their integrity rests on the tree hash
installed sysmod 5.1.5 (git 5.1.5 07286ecd2128b64f53fc3d05aee811e98b991a85) -> lib/mbse4u-sysmod_5.1.5
1 package(s) locked: 1 installed, 0 already present, 0 not installed (standard libraries and local directories); .project.lock.json updated
$ sysml -validate Rover.sysml # OpenSysML reads lib/ on its own; no flagsbundle takes its created timestamp from SOURCE_DATE_EPOCH, else from the checked-out git or
hg commit, so two builds of the same tree are byte-identical.
For a release that needs a complete KPAR model index, pass
syspi bundle -index index.json a JSON object mapping each top-level name
and short name to its archive-relative model file. SysPI checks the file
paths. See model indexes for
how to supply a map.
syspi dependency-sources exports verified textual dependencies as JSON for
editors. It includes both .sysml and .kerml members, follows dependencies
declared by metadata-only packages, and emits a shared installed copy once.
Consumers can analyze these sources with their chosen model tools.
Linux and macOS:
curl -fsSL https://raw.githubusercontent.com/Open-MBEE/SysPI/main/install.sh | shWindows (PowerShell):
irm https://raw.githubusercontent.com/Open-MBEE/SysPI/main/install.ps1 | iexBoth install the latest release's syspi for this machine (/usr/local/bin or ~/.local/bin;
%LOCALAPPDATA%\Programs\SysPI on Windows) after checking the archive against the release's
SHA256SUMS.txt, and run it once to confirm it reports the release. install.sh --help lists
the options (--version v0.1.0, --prefix, --bin-dir, --verify-signature for the cosign
check of the manifest, --dry-run); install.ps1 takes the same as -Version, -InstallDir,
-VerifySignature, -DryRun, and the environment variables SYSPI_VERSION, SYSPI_PREFIX /
SYSPI_INSTALL_DIR and SYSPI_DOWNLOAD_BASE configure a piped run. The checksum guards against a
corrupt or partial download; it comes from the same place as the archive, so against a replaced
release only the signature check helps — pass --verify-signature / -VerifySignature (needs
cosign) or verify by hand as below.
Each release attaches syspi-<os>-<arch>.tar.gz (.zip on Windows) for Linux, macOS and
Windows on amd64 and arm64, SHA256SUMS.txt, and its keyless cosign signature
SHA256SUMS.txt.bundle, verifiable with
cosign verify-blob SHA256SUMS.txt --bundle SHA256SUMS.txt.bundle \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
--certificate-identity https://github.com/Open-MBEE/SysPI/.github/workflows/release.yml@refs/tags/v0.1.0From source, with Go 1.25 or later:
go install github.com/Open-MBEE/SysPI/cmd/syspi@latestRequires git (and svn / hg for packages hosted there) on PATH.
- OpenSysML reads
lib/next to.project.jsonand honours@<version>in a usage IRI as an exact constraint; that is the whole contract between the tools.
SysPI never prompts and keeps no credential store of its own; each backend uses the user's own
configuration, and credentials never enter .project.json, the lock or a log (URLs with
user:password@ are refused).
- git — the user's
gitruns withGIT_TERMINAL_PROMPT=0; configure a credential helper (git config --global credential.helper …) or use an SSH remote. - hg — the user's
hgruns withHGPLAIN=1, which keeps[auth]: addprefix,username,passwordfor the host to your hgrc. - svn — the user's
svnruns--non-interactive. A netrc entry for the repository host ($NETRC, else~/.netrc) is passed as--username <login> --password-from-stdin --no-auth-cache(svn 1.14+; the password travels on stdin, never in argv, the environment or the auth cache), so CI boxes and containers without a keyring work. Otherwise svn's own cached credentials apply (svn ls <url>once interactively), or usesvn+ssh://. - HTTP (
.kparURLs) — HTTP Basic from your netrc:$NETRCif set, else~/.netrc(%USERPROFILE%\_netrcon Windows), matched by host and never sent to another host on a redirect (a redirect target gets only its ownmachineentry, neverdefault). Proxy settings come from the environment (HTTPS_PROXY,NO_PROXY).
An authentication failure is reported with one hint naming the fix for that backend.
Design only, not built here: a SysML-rendered index; LSP integration; any server.
Licensed under the Apache License, Version 2.0 (see LICENSE).