Crate cotis_cli 

cotis-cli — plugin host for Cotis routines

cotis-cli is a plugin host for Cotis build/check/run routines: dynamic libraries (.dll / .so / .dylib) that export a small C ABI. The CLI installs routines into a cache directory and executes them with passthrough arguments.

This crate is not the Cotis UI library itself; it manages routine plugins that drive Cotis-related workflows (web builds, Android packaging, and similar tasks).

Audiences

• CLI users install, list, run, and remove routines via the cotis-cli binary.
• Routine authors ship a cdylib exporting cotis_plugin_* symbols; see Plugin ABI below and the plugin module.

CLI commands

Command	Purpose
install	Install from path:, crate:, or gh: spec
update / reinstall	Same as install, always overwrites
run	Load plugin and forward args after --
build	Hidden alias of run (kept for compatibility)
list	Installed routine names
remove	Delete routine cache directory
info	Print plugin descriptor JSON
help-routine / routine-help	Print plugin help text
completions	Shell completion script to stdout

Global flags: -v / --verbose (debug logging), -f / --overwrite / --fo (replace existing install).

Install sources

• path:<dir> — build local Cargo project (cargo build --lib --release); version stored as "dev"; optional alias; --cdylib-name override supported.
• crate:<name>@<version> — download from crates.io, build; routine name = cdylib stem; alias ignored.
• gh:<owner>/<repo>@<tag|latest> — download GitHub release asset matching host triple; --cdylib-name not supported.

Interactive mode

When required arguments are omitted, the CLI prompts interactively. This requires a TTY on both stdin and stdout. Interactive install also forces overwrite. See the binary’s interactive module (not part of the library API).

Quick start (CLI user)

cotis-cli install path:C:\path\to\cotis-web-builder
cotis-cli list
cotis-cli help-routine cotis_web_builder
cotis-cli run cotis_web_builder -- --output .\dist\web

cargo doc documents this library surface; CLI behavior is summarized here for discoverability.

Install → cache → run lifecycle

1. Install — build or download a cdylib, validate ABI, write descriptor.json, optionally call cotis_plugin_finish_installation.
2. Cache — files live under routines::cache_root (see Cache layout).
3. Run — load library, set COTIS_CLI_CACHE_DIR, call cotis_plugin_run with argv[0] = routine name.

Cache layout

cache/routines/<routine_name>/<version>/<target_triple>/plugin/<library>
cache/routines/<routine_name>/<version>/<target_triple>/descriptor.json

ProjectDirs qualifier: "Cotis Layout", application name: "cotis-cli".

Platform library filenames (see cdylib_filename):

• Windows: <name>.dll
• Linux: lib<name>.so
• macOS: lib<name>.dylib

When run <name> is used without @version, the host picks the lexicographically last installed version directory (not semver-aware). Pin with run <name>@<version>.

Environment variables

Set by the host during plugin execution:

Variable	When set
COTIS_CLI_CACHE_DIR	run; finish_installation hook
COTIS_CLI_INSTALL_PROJECT_DIR	finish_installation for path: installs only

Plugin ABI

A routine dynamic library must export the following C symbols. This is the primary reference for routine authors (you may not read the README).

Symbol	Required	Contract
cotis_plugin_api_version()	Yes	Must return 1 (plugin::COTIS_PLUGIN_API_VERSION)
cotis_plugin_descriptor_json()	Yes	UTF-8 JSON → plugin::PluginDescriptor
cotis_plugin_help()	Yes	UTF-8 help text
cotis_plugin_run(argc, argv)	Yes	0 = success; argv[0] is routine name on run
cotis_plugin_free_string(ptr)	Yes	Host frees strings returned by the plugin
cotis_plugin_finish_installation()	Optional	Required when descriptor sets "finish_installation": true

PluginDescriptor JSON

{"name":"my_routine","version":"0.1.0","finish_installation":true}

• name — routine identifier (used in cache paths and argv[0]).
• version — reported version (may differ from cache directory version for path: installs, which always use "dev").
• finish_installation — when true, host calls cotis_plugin_finish_installation after install.

String ownership

Functions returning *mut c_char must allocate with something like CString::new(...).into_raw(). The host copies the string and then calls cotis_plugin_free_string to release plugin memory. All strings must be valid UTF-8.

Minimal plugin exports

use std::ffi::{c_char, CString};

#[no_mangle]
pub extern "C" fn cotis_plugin_api_version() -> u32 { 1 }

#[no_mangle]
pub extern "C" fn cotis_plugin_descriptor_json() -> *mut c_char {
    CString::new(r#"{"name":"my_routine","version":"0.1.0"}"#).unwrap().into_raw()
}

#[no_mangle]
pub extern "C" fn cotis_plugin_help() -> *mut c_char {
    CString::new("My routine help text").unwrap().into_raw()
}

#[no_mangle]
pub extern "C" fn cotis_plugin_free_string(ptr: *mut c_char) {
    if !ptr.is_null() {
        unsafe { drop(CString::from_raw(ptr)); }
    }
}

#[no_mangle]
pub extern "C" fn cotis_plugin_run(_argc: i32, _argv: *const *const c_char) -> i32 { 0 }

Reference implementations

• cotis-web-builder — basic ABI without finish_installation.
• cotis-android-builder — uses finish_installation: true and reads COTIS_CLI_CACHE_DIR / COTIS_CLI_INSTALL_PROJECT_DIR during the install hook.

Library modules

• plugin — load and invoke routine dynamic libraries.
• install — parse install specs and install routines into the cache.
• routines — cache path helpers and installed-version discovery.
• CargoTool — optional Cargo metadata/build helper for routine build tooling.

Modules

install

Install routines from local projects, crates.io, or GitHub releases.

plugin

Host-side loading and invocation of routine dynamic libraries.

routines

Cache path helpers and installed-routine discovery.

Structs

CargoTool

Cargo metadata and build helper for routine projects.

Functions

cdylib_filename

Platform-specific dynamic library filename for a Rust cdylib target stem.