Skip to content

plugin-run-summary.md

Latest commit

 

History

History
184 lines (130 loc) · 4.15 KB

plugin-run-summary.md

File metadata and controls

184 lines (130 loc) · 4.15 KB

Plugin Execution Feature - Implementation Summary

Version: 1.0 (2025-12-05) Package Versions: cumin 0.13.0, salsa 0.11.0, chili 1.24.0, chell 1.23.0

What Was Implemented

Users can now run ChRIS plugins by typing the plugin name directly in chell. The filesystem location provides implicit data context.

# From upload directory - creates new feed
cd ~/uploads/SAG-anon
pl-dcm2niix-v1.0.2

# From feed directory - continues analysis
cd ~/feeds/feed_2326/pl-dircopy_176660/pl-dcm2niix_176661/data/
pl-segmentation-v1.0.0 --threshold 0.5

Key Features

1. DAG Filesystem Structure

The directory tree mirrors the computational graph:

feeds/feed_2326/
  └── pl-dircopy_176660/
      ├── data/
      └── pl-dcm2niix_176661/
          ├── data/
          └── pl-segmentation_176780/
              └── data/

2. Plugin Name Format Conversion

  • Display format: pl-dcm2niix-v1.0.2
  • ChRIS search format: name_exact:pl-dcm2niix,version:1.0.2
  • Automatic conversion in chell

3. Parameter Syntax

<plugin> <plugin-params> -- <context-params>

Examples:

pl-dcm2niix-v1.0.2 --outputdir results
pl-dcm2niix-v1.0.2 --outputdir results -- feed_title="Brain MRI"

4. Tab Completion Optimizations

  • Pre-caches /bin on startup ("Populating plugin cache...")
  • Builtins complete instantly
  • Plugin names complete from cache (fast after startup)

5. Automatic Defaults

  • Feed title defaults to directory name
  • No interactive prompts (avoids REPL conflicts)
  • User can override via -- feed_title="Custom"

Files Modified/Created

cumin (0.13.0)

  • NEW: src/path/chrisPath.ts - Path analysis utilities
  • MODIFIED: src/plugins/chrisPlugins.ts - Prioritize explicit previous_id
  • All variables explicitly typed per TYPESCRIPT-STYLE-GUIDE

salsa (0.11.0)

  • NEW: src/plugins/plugin_executeInPlace.ts - Execution intent
  • MODIFIED: src/plugins/index.ts - Dictionary to CLI-style conversion

chell (1.23.0)

  • NEW: src/builtins/pluginExecute.ts - Plugin execution builtin
  • MODIFIED: src/chell.ts - Command dispatcher + pre-caching
  • MODIFIED: src/lib/completer/index.ts - Cache-first completion

chili (1.24.0)

  • UPDATED: docs/13_run_a_plugin.adoc - Documentation completion

Technical Highlights

Path Analysis

  • Detects feed directories: /feeds/feed_<id>/
  • Extracts plugin instance IDs from paths
  • Walks directory tree to find parent plugins

DAG Path Construction

// New feed
/home/${user}/feeds/feed_${feedID}/pl-dircopy_${dircopyID}/${plugin}_${instanceID}/data/

// Continue analysis
${previousPluginPath}/${plugin}_${instanceID}/data/

Parameter Conversion

ChRIS expects CLI-style:

--previous_id 123 --title "My Analysis"

Not JSON:

{"previous_id": 123, "title": "My Analysis"}

Error Handling

Full error stack displayed:

Plugin execution failed:
  - [plugin_executeInPlace] | Failed to run plugin
  - [ChRISPlugin.pluginIDs_resolve] | No matching plugins found
  - [ChRISPlugin.pluginIDs_getFromSearchable] | A plugin conforming to "..." was not found

Performance

  • Startup: ~1-2s (plugin cache population)
  • Tab completion: Instant for builtins, fast for plugins
  • Plugin execution: Immediate return (async job scheduling)

Testing Performed

✅ New feed creation ✅ Continue analysis in feed ✅ Multi-level DAG paths ✅ Plugin name format conversion ✅ Parameter parsing with -- delimiter ✅ Error reporting ✅ Tab completion performance ✅ Type compliance (41 violations fixed)

Known Limitations

  1. No real-time status updates
  2. No automatic navigation to output
  3. No plugin output streaming
  4. No plugin status <id> command

These are deferred to Phase 2.

Documentation

  • Implementation Guide: PLUGIN_RUN.md
  • User Guide: docs/pluginrun.adoc
  • Architecture: docs/architecture.adoc
  • Feed Creation: ../chili/docs/13_run_a_plugin.adoc

Version Compatibility

Requires:

  • cumin >= 0.13.0
  • salsa >= 0.11.0
  • chili >= 1.24.0
  • chell >= 1.23.0

All packages must be upgraded together.