____        _
/ ___|  __ _| |___  __ _
\___ \ / _` | / __|/ _` |
 ___) | (_| | \__ \ (_| |
|____/ \__,_|_|___/\__,_|

Salsa Abstracts Logic Service Assets

salsa is the logic layer of the ChRIS interface ecosystem. It encapsulates high-level business intents and operational logic, serving as the bridge between user-facing interfaces (chell, chili) and the underlying infrastructure (cumin and chrisapi).

Installation

npm install @fnndsc/salsa

Requires Node.js ≥ 20.12. Ships with TypeScript type definitions. Depends on @fnndsc/cumin.

Usage

import { files_listAll, fileContent_get, vfsDispatcher } from "@fnndsc/salsa";

// Salsa returns pure data / typed objects — no CLI dependencies
const listing = await files_listAll({ limit: 1000, offset: 0 }, "files", "/home/chris");
const content = await fileContent_get("/home/chris/uploads/notes.txt");

See Key Modules for the full intent catalogue.

Purpose

• Consolidate Business Logic: Centralises intents such as "list directory", "upload file", "register plugin", "fetch feed note". All frontends share identical behaviour.
• Frontend Agnostic: No CLI-specific dependencies (commander, process.stdout). Returns pure data or typed objects.
• Virtual Filesystem: Owns the VFS dispatcher that maps ChRIS API resources onto Unix-style paths — see VFS below.

Architecture: The Sandwich Model

[ ChELL (REPL) ]  [ Chili (CLI) ]  [ Web App ]  [ Mobile App ]
       |                 |               |              |
       +-----------------+---------------+              |
                         |                              |
                         v                              v
              [      Salsa (Logic / Intents)        ]  <-- YOU ARE HERE
                         |
                         v
              [      Cumin (State / Infrastructure) ]
                         |
                         v
              [      @fnndsc/chrisapi (Client)      ]

Key Modules

Filesystem

| Function | Description | |----------|-------------| | vfsDispatcher | Routes list/read calls to the correct VFS provider by path prefix | | files_list | List a directory (paginated) | | files_listAll | Full directory listing (all pages) | | fileContent_get | Read remote file content | | files_uploadPath | Upload a local file or directory tree to ChRIS | | files_touch | Create an empty file | | files_mkdir | Create a directory | | files_rm | Delete a file or directory | | files_cp / files_mv | Copy / move |

Plugins & Store

| Function | Description | |----------|-------------| | plugins_list / plugins_listAll | Fetch plugin list | | plugin_checkExists | Check if a plugin is already registered | | plugin_registerWithAdmin | Register a plugin via the admin endpoint | | plugin_assignToComputeResources | Assign plugin to compute environments | | plugins_searchPeers | Search peer ChRIS stores (e.g. cube.chrisproject.org) | | plugin_importFromStore | Import a plugin from peer store data | | plugin_searchPeersByImage | Resolve a Docker image to a peer-store plugin |

Feeds & Sub-resources

| Function | Description | |----------|-------------| | feeds_list / feeds_listAll | Fetch feeds | | feedNote_get / feedNote_update | Read or update the singleton note on a feed | | feedComments_list | List comments on a feed | | feedComment_create / feedComment_update / feedComment_delete | Comment CRUD |

Pipelines & Workflows

| Function | Description | |----------|-------------| | pipelines_list | List registered pipelines | | workflow_create | Instantiate a pipeline as a workflow on a feed |

Jobs (Plugin Instance Operations)

| Function | Description | |----------|-------------| | job_cancel(id) | Cancel a running/scheduled instance (PUT {status: cancelled}) | | job_delete(id) | Delete a terminal instance record | | job_statusFetch(id) | Live-fetch current status from API (bypasses cache) | | job_logFetch(id) | Fetch stdout/stderr log for an instance | | procCache_refresh([feedID]) | Rebuild the /proc job cache, optionally scoped to one feed |

Virtual Filesystem (VFS)

vfsDispatcher translates a ChRIS path into a provider call. Each provider handles a path prefix and maps API resources onto filesystem semantics:

| Path prefix | Provider | Backed by | |-------------|----------|-----------| | /home/<user>/ | HomeVfsProvider | ChRIS user-file API | | /home/<user>/feeds/ | FeedVfsProvider | Feed resources | | /bin | BinVfsProvider | Registered plugins (virtual executables) | | /usr/bin | UsrBinVfsProvider | Built-in shell commands (whoami, whereami) | | /etc | EtcVfsProvider | Config files (compute.yaml, group, passwd, cube) | | /net/pacs/queries/ | PacsVfsProvider | PACS query results | | /proc/feeds/ | ProcVfsProvider | Job monitoring DAG (backed by ProcCache in cumin) | | *.chrislink | resolved by dispatcher | Symlinks to other ChRIS paths |

Providers implement a common interface: list(path) → Result<VFSItem[]> and read(path) → Result<string>.

/proc/feeds/ — Job Monitoring

ProcVfsProvider mirrors the computation DAG of every visible feed. Each plugin instance is a directory; virtual files inside expose live status, params, and log:

/proc/feeds/feed_123/
├── status                  ← aggregate: running | finishedSuccessfully | finishedWithError
├── title
└── pl-dircopy_456/         ← type=job in VFSItem; ls -l shows colour-coded status
    ├── status              ← live API fetch if non-terminal
    ├── params              ← key=value, cached permanently
    ├── log                 ← never cached, always live
    └── pl-fshack_789/
        └── …

The cache (ProcCache in cumin) holds two flat maps (instances, children/feedRoots) for O(1) lookup and O(depth) path reconstruction. Structure is permanent; only status of non-terminal nodes is refreshed on read.

Development

Build

npm run build

Test

npm run test

License

MIT — part of the ChRIS Project.

-30-