GeniusLoci.EmissaryTool 0.1.0

emissary-tool

Emissary-Tool is a NuGet 'tool', which permits you to Build-Push, Test, and Download Emissaries.

Develop on latest VS 2026-Insider. It's using .net 10 (preview version).

emissary-tool build profile-type project-directory publish-directory

This is usually attached as a post-publish step. It bundles up the publish directory, creates the manfiest, and pushes the files to your local IPFS server. If properly configured it will then digitically sign everything. It then returns the CID of the bundle and the CID of the manifest and signature file. It will also post a message to the IPFS pubsub channel, and post a copy of the manifest to the Entity Server for your project. The Entity Server should manage your Pins.

There are ultimatley a couple of different types of emissaries.

• Primary emissary type is the WASM type, which has very limited WASI support and a fixed set of APIs that must integrate with. These are used as smart objects inside the Genius Loci ecosystem.
• You can also generate emissaries that are WASM, but have normal WASI capabililties. These are used to write the main parts of all of the tools.
• There is a mode where you can generate an emissary with the normal output from the .net build (with dlls and exe files and other content). These are used for dynamic code extensions, generally for building the extended loaders. The base loader can then load up tools that are running newer versions of the frameworks.
• Last variation is simply a IPFS version of a docker container (or podman). Hopefully we can integrate this into the normal docker build sequence for Visual Studio, though it might need to be pushed to a conventional repository as well. This will also return the CID of your container (the CID must be pinned or this form of container won't be reliable--the entity server will also handle this).

profile-type

This is a set of yaml configuration files which come with the tool, and that you can extend and build for your own use-cases. It's mostly to filter what files go into the emissary, and how things are handles, and possibily extra transformations that occur. Emissaries can generally be made from any language that supports both ability to compile to wasm, and supports component model wasm and protobuf. This also includes what kind of emissary you are building, such as a WASM emissary, a dynamic code extension, or a docker container.

project-directory

This is generally where your git working directory is for this project. It will crawl up the directories to find the .git directory, and it will extract metadata from the git repository (repo, build and history info). Also, it will look for the Emissary.yaml file, which contains the metadata for the project, such as the name, description, and other information. This is also where it will look for the .gitignore file, which will be used to filter out files that should not be included in the emissary. It will also look for the .emissaryignore file, which is used to filter out files that should not be included in the emissary, but are not in the .gitignore file.

publish-directory

This is generally your projects publish directory. Some operations like generating the wasm files, or docker, may need publish to happen, otherwise this can just the normal bin output directory.

emissary-tool set-configure

This will add the configuration steps to the project (the .csproj, for example). If you started your project with an emissary template, this will already be done for you. If you are adding emissaries to an existing project, you will need to run this command to add the necessary configuration steps. You can also repair the config if you have special variations.

emissary-tool check signature-file-CID

Checks for the existence of all files in IPFS. Also checks the validity of your signatures. If unpinned files have fallen off the network, it will fail. It will also check the manifest file, and report any errors in the manifest file. This is useful for verifying that your emissary is valid and can be used.

emissary-tool download signature-file-CID output-directory

Downloads the files from IPFS, and verifies the signatures. It will also check the manifest file, and report any errors in the manifest file. This is useful for downloading emissaries that you have previously built, or for downloading emissaries that you have found on the network.

TODO List

• Set up nuget@genius-loci.org email and then set up GeniusLoci organization on nuget.org.
• Set up the nuget package for the emissary-tool - this will be a 'tool', not a package, it can be installed independently of any project. It gets installed into the PATH and then can be simply used as 'emissary-tool' from the command line.
• Build out 'build', we can start on 'download' when the cache library is fully baked out.
• Get persisted config working. At least we want to be able to override the default for the IPFS server. Done/Testing.
• Eventually we want to be able to send information to your Entity Server so it can be added to the build catalogs. It will also manage your pins.
• Start to build out the templates. Initially need at least a wasm template, and the assembly emissary (just a dll class assembly).
• Start on other languages:
  • .NET assembly (panopticon and the main servicecore will be this)
  • .NET Console
  • GO (mostly for kubo initially)
  • Python
  • TypeScript
  • C
• We may merge the test tool into this. We might have a unit test entrypoint in our framework?

 run 'build.ps1' to build and make the nuget package, it will also deinstall and install --global
 For help, run 'emissary-tool --help' or 'emissary-tool build --help'.