feat: allow adding/removing usages by path

[andrius-puksta-sensmetry]

Users want to do this anyway (at least for experimenting), so might as well accomodate them.

Changes

• Add --path argument to add and remove that allows adding/removing path usages by converting them to file:// URL. Recommend using workspaces instead of paths.
• Guide users to use path usage (both for add and remove) if IRI parsing fails
• Fail when building a kpar if path usages are present, unless --allow-path-usage is passed (in that case a warning is still produced)
• Guide users to use init instead of new (sysand new was mentioned in AoSysML, so this at least gives users something actionable)
• Add docs about supported IRIs
• (unrelated) Add workspace docs

Fixes

• closes sysand add urn:kpar:sysmod broken #206; added an integration test for it

[victor-linroth-sensmetry]

So while using file urls for quick experimentation is fine, it's non-portable so generally bad practise and should not be encouraged. As such I would prefer not to have a nice and simple flag like --path for this, and instead have something with a bit more friction to it.

If we are to use a --path flag it should be part of the more general configuration of sources I've been working on (I've not committed to a UI for that though and will want some feedback before finalising).

[tilowiklundSensmetry]

So while using file urls for quick experimentation is fine, it's non-portable so generally bad practise and should not be encouraged. As such I would prefer not to have a nice and simple flag like --path for this, and instead have something with a bit more friction to it.

If we are to use a --path flag it should be part of the more general configuration of sources I've been working on (I've not committed to a UI for that though and will want some feedback before finalising).

I do think we need something that is (equivalently) easy to use for learning purposes, and --path is sort of the only thing I can think of.

A complex alternative option would be to have the Sysand client maintain some sort of "local index" that the user can either install, or register projects to. This is sort of doable already (using env install), but would need to be made a bit more ergonomic.

[vytautas-astrauskas-sensmetry]

warn when building a kpar if path usages are present

I strongly believe that if we allow adding usages with path argument, this should be a hard error because URIs are global, so such kpar is (almost surely) unusable outside of the computer on which it was created.

Also, in the documentation we probably should recommend using workspaces instead.

[andrius-puksta-sensmetry]

If we are to use a --path flag it should be part of the more general configuration of sources

But these accomplish different things: this PR simplifies creating a file:// URL, and that PR involves another configuration file (and this should be indicated, preferably in the CLI invocation itself, maybe something like --map-from and --map-to).

[tilowiklundSensmetry]

Could we add some integration level (i.e. sysand/tests) for this?

[victor-linroth-sensmetry]

But these accomplish different things: this PR simplifies creating a file:// URL, and that PR involves another configuration file (and this should be indicated, preferably in the CLI invocation itself, maybe something like --map-from and --map-to).

Then call it --file-url? I have no idea what --map-from or --map-to are supposed to mean.

[andrius-puksta-sensmetry]

Then call it --file-url? I have no idea what --map-from or --map-to are supposed to mean.

Agreed that it's not obvious what "map" means. Here it refers to "mapping" (in functional programming sense) "actual" IRIs to "pseudo" IRIs.
Anyway, discussion on exact flag naming for that should go to #130.

[andrius-puksta-sensmetry]

Could we add some integration level (i.e. sysand/tests) for this?

Done

[victor-linroth-sensmetry]

Opps, wrong PR.

[consideRatio]

There was a mistaken "request changes here", so i dismissed it by re-requesting review from @victor-linroth-sensmetry.

@andrius-puksta-sensmetry let me know if you need help getting this to land in one way or another. It would be great to reduce the open PRs further!

Outdated, and by mistake