Merge branch 'main' of git-caid:aa-caid/caid-tools

# Developers

These are the instructions for developers maintaining this repository.

## Creating a release

1. update the dependenies edit the `versions` file and run the `./update-sub-modules.sh`.

2. `git commit -am "Release x.x.x"`

3. `git push origin main`

4. `git tag vx.x.x`

5. `git push origin vx.x.x`

## Publishing a release

To be on the safe side, this requires you to clone a fresh copy of the repository. Use the `black_list_files.txt` to exclude files. It's a good idea to take a quick look at `./publish.sh` to get an idea of what's going on. 

1. `git clone git@git.isis.vanderbilt.edu:aa-caid/caid-tools.git`

2. `cd caid-tools`

3. `./publish x.x.x`

 No newline at end of file

# CAID-tools

Depi is a suite of tools for tracking dependencies across different types of resources stored in different ways. At the core is the depi-server which provides a protocol over gRPC. For the supported tools there are user-interfaces implemented as vscode-extensions and adapter/monitors that report in updates to the stored resources. The currently supported tools are `git`, `git-gsn` and `webgme`.

Depi is a software-suite for tracking dependencies from across different types of tools and storages. At the core is the depi-server which provides a protocol for viewing and, adding and linking resources, reporting in updates in resources, etc. For the different supported tools there are user-interfaces (here implemented as vscode-extensions) and adapter/monitors that report in updates to the resources. The currently supported tools are `git`, `git-gsn` and `webgme`.

TODO: Reword this.

In Depi, these different types of artifacts or _Resources_ are referred to as _Tools_, here `webgme`, `git` and `git-gsn`. A _Tool_ needs to the very least provide an interface for adding new _Resources_ (linking them can be done via the Depi Blackboard UI) and a mechanism for reporting in updates in the _Resources_. An actual collection of _Resources_ from a _Tool_ is referred to as _Resource-Group_. In the case of `git` a _Resource-Group_ is a specific repository and the _Resources_ are either files or directories within that repository. 

| Tool | Resource-Group | Resource | Monitor | GUI / vscode-extension |

| --- | --- | --- | --- | --- |

| git | Git repository | File, Directory | git-monitor (git webhooks)| [Depi Browser](vscode:extension/vu-isis.depi) |

| git-gsn | GSN model directory inside a git repository | Solution nodes | git-gsn-monitor (git webhooks) | [GSN Editor](vscode:extension/vu-isis.gsn-assurance) |

| webgme | A WebGME project at a specific WebGME server instance | Model | webgme-monitor (webgme storage events) | [WebGME Client](vscode:extension/vu-isis.webgme-depi) |

## Repository structure

- `depi-impl` contains the source code for the depi-server, git-monitor, git-gsn-monitor, depi-cli and the depi vscode extension

- `webgme-depi` contains a vscode extension wrapping a webgme instance (and webgme components providing the interface between these two)

## Getting started

For running the back-end services we recommend using docker. For the user interface you can either [install vscode](https://code.visualstudio.com/download) and then install the vscode extensions (search for the extensions from within vscode or simply click on the links in the table above), or use the `caid-front-end` docker image below that is based on [theia](https://theia-ide.org/) and already prepared with the extensions. 

[Install docker](https://docs.docker.com/engine/install/ubuntu/) - this has been tested with `Docker version 25.0.3, build 4debf41` on `Ubuntu 22.04`.

### Back-end Services

Start the back-end services first.

Start the back-end services first

```

docker run --rm --name caid -p 3000:3000 -p 8888:8888 -p 5150:5150 git.isis.vanderbilt.edu:5050/aa-caid/caid-tools/caid-tools:latest

```

- **gitea** TODO:

### Front-end/User Interface

TODO: Brief intro about why we use vscode and GUIs

- [Depi Browser](depi-impl/vscode-depi/README.md)

- [WebGME Client](webgme-depi/vscode-webgme-depi/README.md)

- [GSN Editor](gsn-domain/gsn-vscode-xtext/vscode-extension-self-contained/README.md)

- [Depi Browser](vscode:extension/vu-isis.depi)

- [WebGME Client](vscode:extension/vu-isis.webgme-depi)

- [GSN Editor](vscode:extension/vu-isis.gsn-assurance)

  - This extension requires java 8+

Then the theia IDE with the extensions.

![Clone Repositories](examples/images/01-clone-repos.png)

This system consists of a system-model modelled in webgme (where models are stored in a mongo-database), source code used by the blocks in the system-model, a few git-repositories with either test-scripts or generated data. Finally there is an assurance model modelled in GSN Assurance that is also stored under git (in the `ansr` folder in the `gsn` repository). However from a perspective of Depi, those files are managed slightly different than regular git files where instead of being treated as regular files - the models are interpreted as Abstract Semantic Graphs.

In Depi, these different types of artifacts or _Resources_ are referred to as _Tools_, here `webgme`, `git` and `git-gsn`. A _Tool_ needs to the very least provide an interface for adding new _Resources_ (linking them can be done via the Depi Blackboard UI) and a mechanism for reporting in updates in the _Resources_. An actual collection of _Resources_ from a _Tool_ is referred to as _Resource-Group_. In the case of `git` a _Resource-Group_ is a specific repository and the _Resources_ are either files or directories within that repository. To view the current state of the example system press `Ctrl/Cmd + Shift + P` and start typing `Depi: Blackboard` and select the command. This will prompt you for a password to log into depi - the password for the `demo`-user is `123456`.

To view the current state of the example system press `Ctrl/Cmd + Shift + P` and start typing `Depi: Blackboard` and select the command. This will prompt you for a password to log into depi - the password for the `demo`-user is `123456`.

![Blackboard Command](examples/images/depi-blackboard-cmd.png)

 In the picture below the different _Resource-Groups_ with their _Resources_ and _Links_ between them all expanded and displayed. The _Links_ are directionaly relationships are interpreted as "depends-on" (for example all resources of the `git-gsn` _Resource-Group_ `ansr` depends-on other _Resources_.)

.gitlab-ci.yml

Dockerfile.with-front-end

depi-impl/depi/dolt/doltamd

DEVELOPERS.md

version=$1

# Start out by creating a branch at the currently checked out commit (typically HEAD of main)

git checkout -b "release-tmp-$version"

git remote set-url origin git@github.com:vu-isis/CAID-tools.git

git fetch --all

# Convert sub-modules to regular git folders

submodules=(

git commit -m "converted commit"

# Create a diff from the release state with the already released main

# Then set the remote to the public github repo and fetch the last published version (main)

git remote set-url origin git@github.com:vu-isis/CAID-tools.git

git fetch --all

# Create a diff from the new release state with the last published version (main in github)

git diff -R --binary "release-tmp-$version" origin/main > release.diff

# Create temporary branch from main 

# Create temporary branch from that main and apply that diff

git checkout -b "new-release-$version" origin/main

git apply release.diff

git add .

git commit -am "Release ${version}"

# Finally push that new version to the remote

git push -u origin "new-release-$version":main

 No newline at end of file