some code refactoring: preparation for use as a library & non-CLI clients