safedb 0.3.1011 → 0.4.1002

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 202262aed7ae6b3cffbba137d118838cf8370d7ef54244215833378a1944c56c
-  data.tar.gz: 990e817eab3133c4a42e6bb904874e060a204900319b7d87015e6d0449553c1c
+  metadata.gz: 3bcafea21f4204ecebc6712dd926e839aeb8c078904487528b44de4b1f87b4d8
+  data.tar.gz: 256015d30eb46362a1d3923d6a7cf0c1d88942b67c4f5cd8e7dce6b6b5fb40b4
 SHA512:
-  metadata.gz: 1c2d25554329ceb38a8ed6dde23036100c8e54f9022d5a782f0ef66bee1aa05d207150282a5ea3766f1061f79d2871eb47b954090896452064912ef083ebc68f
-  data.tar.gz: c553057dcbb670b980a8ed7e2a784c0445a04314f53d86bd1bd9f8326997a2bf0dda5a1b2f375df3a5bb0b71c3e92a74509b24f5e10318634572241baa706be4
+  metadata.gz: d013b6386bfc912ede2b8ad1736309c48cbbbb36d3e23731c092f4e041df47a3d012aa9a5ea5ecebb841d8f0066f040da2b3fb1c1e61adfff424997bc429f2ca
+  data.tar.gz: 42a6f28ecad6fc9fcbd759b4abdcfea468ebfe491cd75775698055b52946042009123edf6c1b5cc8bd56cd78fc8f78bd33ee42861cf3b973de44c67a7cc39beb

data/CONTRIBUTING.md

@@ -42,20 +42,68 @@ reek lib
 ```
 
 
-## Releasing Software
+## Automated Software Release
 
-Those with priveleges to release to safedb.net will have a private key to push (or pull) in git repository changes.
+safedb is automatically released by Jenkins using a GitOps style pipeline defined in the Jenkinsfile and Dockerfile. The release to rubygems.org depends on
 
-To release the software to the rubygems.org platform, commonly via a **continuous integration pipeline** based on Jenkins 2.0, one needs
+- a pull request to the [safe github master branch](https://github.com/devops4me/safedb.net.git)
+- an error-free gem build
+- an error-free documentation image build to www.safedb.net
+- immaculate BDD test runs with **Cucumber and Aruba** in Linux environments incl Ubuntu, Raspbian and RHEL.
+- an automated version number bump using the gem-release gem
+- quality numbers passed by the Reek code quality analyzer
+- available rubygems.org credentials in ~/.gem/credentials
 
-- **either** the email address / password combination
-- **or** a credentials file containing a hex API key
+## release safedb to RubyGems.org
 
-Release actors are also responsible for bumping the gem version via semantic versioning principles.
+Once only use **`gem push`** at the repository root to create a **rubygems API key** and slurp it up from the **`~/.gem/credentials`** with **`safe file rubygems.org.credentials ~/.gem/credentials`**
+Now when releasing we eject the file back into **`~/.gem/credentials`**, secure it ( with **`sudo chmod 0600 credentials`** ) and then issue the below command from the **gem-release** gem.
+
+### `gem bump patch --tag --push --release --file=$PWD/lib/version.rb`
+
+The gem bump (and release) command bumps up the patch (or major or minor) version, tags the repository, pushes the changes and releases to rubygems.org
+
+
+
+## safedb development environment commands
+
+### `rake install`
+### `cucumber`
+### `git checkout -b feature.commit-branch`
+### `git add; git commit;`
+### `git cherry -v origin`
+### `git cherry -v origin feature.commit-branch`
+### `git push -u origin feature.commit-branch`
+### `git pull origin master`
+### `git pull origin feature.commit-branch`
+
+## common git feature merge commands
+
+### `git checkout master`
+### `git pull origin master`
+### `git merge feature.commit-branch`
+### `git push -u origin master`
+
+
+## Branch Naming Convention
 
-### git push to github.com/devops4me/safedb.net
+Branch names begin with either
 
-Write out the SSH config and private key files.
+- feature. (or)
+- bug. (or)
+- refactor.
+
+Branch names are then typically a **verb-noun concatenation** like
+
+- feature.safe-inport-export
+- refactor.book-id-create-algorithm
+- refactor.validate-book-names
+
+## how to git push to safedb.net
+
+Those with priveleges to release to safedb.net will have a private key to push pull requests into the repository.
+
+This is how to setup the **ssh config** and **pem private key**.
 
 ```
 safe login safe.ecosystem
@@ -71,15 +119,4 @@ git clone git@safedb.code:devops4me/safedb.net.git mirror.safedb.code
 
 If a config file already exists then safe will back it up with a timestamp prefix before clobbering the file. Now bump up the major, minor or patch versions, then commit.
 
-### development installs | rake install
-
-Use rake install to locally test local software changes.
-
-### bump | tag | release to RubyGems.org
-
-Once only use **`gem push`** at the repository root to create a **rubygems API key** and slurp it up from the **`~/.gem/credentials`** with **`safe file rubygems.org.credentials ~/.gem/credentials`**
-Now when releasing we eject the file back into **`~/.gem/credentials`**, secure it ( with **`sudo chmod 0600 credentials`** ) and then issue the below command from the **gem-release** gem.
-
-### `gem bump patch --tag --push --release --file=$PWD/lib/version.rb`
 
-This command bumps up the patch (or major or minor) version, tags the repository, pushes the changes and releases to rubygems.org

data/README.md

@@ -104,7 +104,7 @@ safe | Install and Configure
 
     $ sudo apt-get install ruby-full     # for OpenSSL we need full ruby
     $ sudo gem install safedb            # install the safe ruby gem
-    $ export SAFE_TTY_TOKEN=`safe token` # setup a shell session variable
+    $ export SAFE_TTY_TOKEN=`safe token` # setup a shell variable
     $ safe init joe@abc ~/safedb.creds   # initialize a safe book in folder
     $ safe login joe@abc                 # login with the created password
 
@@ -143,7 +143,7 @@ Advanced users should avoid adding the export command to <tt>~/.bash_profile</tt
 
 When the shell closes the shell token will disappear which is good. You can clear it immediately with these commands.
 
-    $ unset SAFE_TTY_TOKEN        # Delete the shell session token
+    $ unset SAFE_TTY_TOKEN        # Delete the shell token
     $ env | grep SAFE_TTY_TOKEN   # Check SAFE_TTY_TOKEN is deleted
     $ env -i bash                 # Delete every env var created by shell
 
@@ -578,7 +578,7 @@ safe | moving computer
 We travel between laptops, desktops, virtual machines and even docker containers. Always run init the first time you use a domain on a different computer.
 
     $ gem install safe
-    $ export SAFE_TTY_TOKEN=`safe token`        # setup a shell session variable
+    $ export SAFE_TTY_TOKEN=`safe token`        # setup a shell variable
     $ safe init joe@abc /home/joe/credentials   # initialize a secrets domain
     $ safe login joe@abc                        # login to the new domain
 
@@ -647,7 +647,7 @@ You can require safe (as an SDK) and interact with it directly from any other Ru
     $ gem install safe
     $ irb
     $ > require "safe"
-    $ > SafeDb::Interprete.version()
+    $ > SafeDb::CLI.version()
 
 The above should return the **installed version** of SafeDb.
 
@@ -752,17 +752,17 @@ This method (theoretially) allows a version 3.428.24952 to restore an export of
 
 ## Safe's Concurrency Methodology
 
-A safe repository (book) can be changed by one session but read concurrently by multiple sessions.
+A safe repository (book) can be changed by one branch but read concurrently by multiple branchs.
 
 Directory Links are NOT PORTABLE to use to point to the active workspace especially if we the safe root folder is on a USB key.
 A GOOD engough concurrency technique is a lock file in the BOOK's root folder that is named `safe.concurrency.lockfile.<<book.id>>`
 
-The contents of the file will hold the relative directory name (session ID based) that has the lock and the session ID that had it before that (if not first).
+The contents of the file will hold the relative directory name (branch ID based) that has the lock and the branch ID that had it before that (if not first).
 
-The <machine.id>.<bootup.id> is used to when the first read/write login session occurs. Subsequent logins for a read/write session will then have 2 choices in this shell.
+The <machine.id>.<bootup.id> is used to when the first read/write login branch occurs. Subsequent logins for a read/write branch will then have 2 choices in this shell.
 
-- safe login ali.baba --steal    # take over the primary read/write session
-- safe login ali.baba --branch   # leave primary session but open one that will not change the price of sugar
+- safe login ali.baba --steal    # take over the primary read/write branch
+- safe login ali.baba --branch   # leave primary branch but open one that will not change the price of sugar
 - safe login ali.baba --branch=master
 - safe login ali.baba --branch=experimental
 - safe login ali.baba -b experimental
@@ -775,7 +775,7 @@ A third choice arises if we visit the shell holding the directory pointer and lo
 
 Logout NEVER TOUCHES the lock file (it could have moved on multiple times so only login can act on it).
 
-However logout DELETES the cipher.file intra-sessionary ciphertext that can be unlocked by session key to retrieve the content key. This action renders it impossible to read or write any data from logged in book.
+However logout DELETES the cipher.file branch ciphertext that can be unlocked by branch key to retrieve the content key. This action renders it impossible to read or write any data from logged in book.
 
 A subsequent login can again re-instate this privilege.
 
@@ -790,22 +790,22 @@ The first repo holds the live link.
 
 Subsequent logins must perform two checks
 
-- IS MY DIRECTORY (session) noted as the latest in the lock file (possible if you've logged out of the same shell)
-- (if other directory) - Does the intra-sessionary key within that directory's cipher file have a value
+- IS MY DIRECTORY (branch) noted as the latest in the lock file (possible if you've logged out of the same shell)
+- (if other directory) - Does the branch key within that directory's cipher file have a value
 
 The popup asking the user to STEAL or go READONLY is triggered if the answers above are NO then YES.
 
 ### Safe steal | HowTo
 
-If intra key has no value then stealing is not necessary so the existence of the --steal flag does not change the price of sugar.
+If branch key has no value then stealing is not necessary so the existence of the --steal flag does not change the price of sugar.
 
 The Stealing flow of events is to
 
- - copy the directory into a new one for this session named `<<book.id>>.<<timestamp>>.<<session.key>>`
+ - copy the directory into a new one for this branch named `<<book.id>>.<<timestamp>>.<<branch.key>>`
  - validate the directory for data consistency (nice to have functionality)
  - collect the password and if invalid stop now
  - grab the lock file and write it to point it to our directory (we are it)
- - create our own intra-sessionary key and write it in within our folder
+ - create our own branch key and write it in within our folder
 
 ### Safe branch | HowTo
 

data/Rakefile

@@ -14,3 +14,10 @@ end
 
 task :default => :test
 
+require 'yard'
+# This configuration allows us to run "rake yard"
+# to build documentation.
+YARD::Rake::YardocTask.new do |t|
+ t.files   = ['lib/**/*.rb']   # optional
+ t.stats_options = ['--list-undoc']
+end

data/bin/safe

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
  
 require 'openssl'
-require 'interprete'
+require 'cli'
 
-Interprete.start(ARGV)
+CLI.start(ARGV)

data/lib/{interprete.rb → cli.rb}

@@ -1,14 +1,13 @@
 require "thor"
 require "fileutils"
+require "strscan"
 
-require "session/time.stamp"
-require "logging/gem.logging"
-require "session/require.gem"
-
+require "utils/logs/logger"
+require "controller/requirer"
 
 # Include the logger mixins so that every class can enjoy "import free"
 # logging through pointers to the (extended) log behaviour.
-include OpenLogger
+include LogImpl
 
 
 # This standard out sync command flushes text destined for STDOUT immediately,
@@ -20,7 +19,7 @@ $stdout.sync = true
 # that this code is executing from. Only use this tool if your library is
 # relatively small but highly interconnected. In these instances it raises
 # productivity and reduces pesky "not found" exceptions.
-OpenSession::RecursivelyRequire.now( __FILE__ )
+SafeDb::Require.gems( __FILE__ )
 
 
 # This command line processor extends the Thor gem CLI tools in order to
@@ -32,7 +31,7 @@ OpenSession::RecursivelyRequire.now( __FILE__ )
 # - ensure that the parameter values are in range
 # - delegate processing to the registered handlers
 
-class Interprete < Thor
+class CLI < Thor
 
 
   log.info(x) { "request to interact with a safe book has been received." }
@@ -69,7 +68,7 @@ class Interprete < Thor
   # - either <tt>safe --version</tt>
   # - or <tt>safe version</tt>
   def version
-    log.info(x) { "[usecase] ~> print the version of this safedb.net personal database." }
+    log.info(x) { "print the version of this safedb.net personal database." }
 
     puts ""
     puts "safedb gem version => v#{SafeDb::VERSION}"
@@ -82,25 +81,23 @@ class Interprete < Thor
 
 
 
-  # Description of the init configuration call.
-  desc "init <book_name> <storage_dir>", "initialize the safe book on this device"
+  # Description of the book initialize call.
+  desc "init <book_name> <storage_dir>", "initialize a new safe credentials book"
 
   # Use <tt>password</tt> if confident that either the command history is
   # inaccessible or the call originates from non-interactive software.
   option :password, :aliases => '-p'
 
-  # Initialize the credentials manager, collect the human password and
-  # manufacture the strong asymmetric public / private keypair.
+  # Initialize a safe credentials book with this name and collect the human sourced
+  # pasword to be put through key derivation functions.
   #
-  # @param domain_name [String] the domain the software operates under
-  # @param base_path [String] the path to the base operating directory
-  def init( domain_name, base_path = nil )
-    log.info(x) { "initialize the safe book on this device." }
+  # @param book_name [String] the name of the credentials book to be created
+  def init( book_name )
+    log.info(x) { "initialize a new safe credentials book called [#{book_name}]." }
     init_uc = SafeDb::Init.new
     init_uc.password = options[ :password ] if options[ :password ]
-    init_uc.domain_name = domain_name
-    init_uc.base_path = File.expand_path( base_path ) unless base_path.nil?
-    init_uc.flow_of_events
+    init_uc.book_name = book_name
+    init_uc.flow()
   end
 
 
@@ -112,14 +109,14 @@ class Interprete < Thor
   # inaccessible or the call originates from non-interactive software.
   option :password, :aliases => '-p'
 
-  # Login in order to securely interact with your data.
-  # @param domain_name [String] the domain the software operates under
-  def login( domain_name = nil )
-    log.info(x) { "[usecase] ~> login to the book before interacting with it." }
+  # Login in order to securely interact with your safe credentials.
+  # @param book_name [String] the name of the credentials book to login to
+  def login( book_name = nil )
+    log.info(x) { "login to the safe credentials book called [#{book_name}]." }
     login_uc = SafeDb::Login.new
-    login_uc.domain_name = domain_name unless domain_name.nil?
+    login_uc.book_name = book_name unless book_name.nil?
     login_uc.password = options[ :password ] if options[ :password ]
-    login_uc.flow_of_events
+    login_uc.flow()
   end
 
 
@@ -132,10 +129,10 @@ class Interprete < Thor
   #
   # @param key_name [String] the key whose value is to be printed
   def print key_name
-    log.info(x) { "[usecase] ~> print the key value at the opened chapter and verse." }
+    log.info(x) { "print the key value at the opened chapter and verse." }
     print_uc = SafeDb::Print.new
     print_uc.key_name = key_name
-    print_uc.flow_of_events
+    print_uc.flow()
   end
 
 
@@ -145,21 +142,21 @@ class Interprete < Thor
 
   # Print the name of the verse at the opened chapter and verse location.
   def verse
-    log.info(x) { "[usecase] ~> print the verse name at the opened chapter and verse." }
+    log.info(x) { "print the verse name at the opened chapter and verse." }
     verse_uc = SafeDb::Verse.new
-    verse_uc.flow_of_events
+    verse_uc.flow()
   end
 
 
 
   # Description of the safe token use case.
-  desc "token", "generate and print out an encrypted (shell bound) session token"
+  desc "token", "generate and print out an encrypted (shell bound) shell token"
 
-  # The<b>token</b> use cases prints out an encrypted session token tied
+  # The<b>token</b> use cases prints out an encrypted shell token tied
   # to the workstation and shell environment.
   def token
-    log.info(x) { "[usecase] ~> generate and print out an encrypted (shell bound) session token" }
-    SafeDb::Token.new.flow_of_events
+    log.info(x) { "generate and print out an encrypted (shell bound) shell token" }
+    SafeDb::Token.new.flow()
   end
 
 
@@ -191,11 +188,67 @@ class Interprete < Thor
   # @param verse [String]
   #    the verse of the logged in book and specified chapter to open
   def open chapter, verse
-    log.info(x) { "[usecase] ~> open a chapter and verse to read from or write to." }
+    log.info(x) { "open a chapter and verse to read from or write to." }
     open_uc = SafeDb::Open.new
-    open_uc.env_path = chapter
-    open_uc.key_path = verse
-    open_uc.flow_of_events
+    open_uc.chapter = chapter
+    open_uc.verse = verse
+    open_uc.flow()
+  end
+
+
+
+  # Description of the diff use case command from the point of view
+  # of either a checkout from master to branch, a checkin from branch
+  # to master or a diff listing prophesying about both.
+  desc "diff", "master and branch diff with --checkin (-i), --checkout (-o) or both."
+
+  # A checkin is basically a copy-overwrite operation which does not finesse
+  # like the merging checkout does. The diff report illustrates that the master
+  # will essentially reflect the working branch's current state.
+  method_option :checkin, :type => :boolean, :aliases => "-i"
+
+  # A checkout is effectively an incoming merge of the master's data
+  # structure into the working branch. With checkouts nothing ever gets
+  # deleted.
+  method_option :checkout, :type => :boolean, :aliases => "-o"
+
+  # The <b>diff use case</b> spells out the key differences between the safe book
+  # on the master line the one on the current working branch.
+  #
+  # By default when conflicts occur, priority is given to the current working branch.
+  # No parameters are required to perform a diff.
+  def diff
+    log.info(x) { "prophesy list of checkout and/or checkin actions. CLI options are #{options.to_s()}" }
+    diff_uc = SafeDb::Diff.new()
+    diff_uc.checkin = true if options[ :checkin ]
+    diff_uc.checkout = true if options[ :checkout ]
+    diff_uc.flow()
+  end
+
+
+
+  # Description of the checkin use case command.
+  desc "checkin", "commit (save) the branch changes by putting them into master."
+
+  # The <b>checkin use case</b> commits any changes made to the safe book into
+  # master. This is straightforward if the master's state has not been forwarded
+  # by a ckeckin from another (shell) branch.
+  def checkin
+    log.info(x) { "commit (save) any changes made to this branch into the master." }
+    SafeDb::CheckIn.new.flow()
+  end
+
+
+
+  # Description of the checkout use case command.
+  desc "checkout", "refresh (update) the working branch with changes from the master."
+
+  # The <b>checkout use case</b> commits any changes made to the safe book into
+  # master. This is straightforward if the master's state has not been forwarded
+  # by a ckeckin from another (shell) branch.
+  def checkout
+    log.info(x) { "refresh (update) the working branch with changes from the master." }
+    SafeDb::CheckOut.new.flow()
   end
 
 
@@ -207,117 +260,111 @@ class Interprete < Thor
   # The --print flag demands that the exported text goes to stdout otherwise it
   # will be placed in an aptly named file in  the present working directory.
   def export
-    log.info(x) { "[usecase] ~> export book chapter content or dictionary at verse in JSON format." }
-    SafeDb::Export.new.flow_of_events
+    log.info(x) { "export book chapter content or dictionary at verse in JSON format." }
+    SafeDb::Export.new.flow()
   end
 
 
 
-  # Description of the put secret command.
-  desc "put <key> <value>", "put key/value pair into dictionary at open chapter and verse"
+  # Description of the import use case command.
+  desc "import", "imports the contents of the parameter json file into this book."
 
-  # Put a secret with an id like login/username and a value like joebloggs into the
-  # context (eg work/laptop) that was opened with the open command.
-  #
-  # @param secret_id [String] the id of the secret to put into the opened context
-  # @param secret_value [String] the value of the secret to put into the opened context
-  def put secret_id, secret_value
-    log.info(x) { "[usecase] ~> put key/value pair into dictionary at open chapter and verse." }
-    put_uc = SafeDb::Put.new
-    put_uc.secret_id = secret_id
-    put_uc.secret_value = secret_value
-    put_uc.flow_of_events
+  # The <b>import use case</b> takes a filepath parameter in order to pull in
+  # a <em>json</em> formatted data structure.
+  # @param import_filepath [String] the path to the JSON file that we will import
+  def import import_filepath
+    log.info(x) { "importing into current book from file #{import_filepath}." }
+    import_uc = SafeDb::Import.new
+    import_uc.import_filepath = import_filepath
+    import_uc.flow()    
   end
 
 
 
-  # Description of the file command.
-  desc "file <file_key> <file_url>", "ingest a file into the safe from the filesystem (or S3, ssh, Google Drive)"
+  # Description of the put secret command.
+  desc "put <key> <value>", "put key/value pair into dictionary at open chapter and verse"
 
-  # The <b>file use case</b> pulls a read in from either an accessible readsystem
-  # or from a remote http, https, git, S3, GoogleDrive and/or ssh source.
+  # Put a secret with an id like login/username and a value like joebloggs into the
+  # context (eg work/laptop) that was opened with the open command.
   #
-  # @param file_key [String] keyname representing the file that is being read in
-  # @param file_url [String] url of file to ingest and assimilate into the safe
-  def file file_key, file_url
-    log.info(x) { "[usecase] ~> file read against key [[ #{file_key} ]]" }
-    log.info(x) { "[usecase] ~> file read from url [[ #{file_url} ]]" }
-    file_uc = SafeDb::FileMe.new
-    file_uc.file_key = file_key
-    file_uc.file_url = file_url
-    file_uc.flow_of_events
+  # @param credential_id [String] the id of the secret to put into the opened context
+  # @param credential_value [String] the value of the secret to put into the opened context
+  def put credential_id, credential_value
+    log.info(x) { "put key/value pair into dictionary at open chapter and verse." }
+    put_uc = SafeDb::Put.new
+    put_uc.credential_id = credential_id
+    put_uc.credential_value = credential_value
+    put_uc.flow()
   end
 
 
 
-  # Description of the eject command.
-  desc "eject <file_key>", "write out ingested file at chapter/verse with specified file key"
+  # Description of the set configuration directives command.
+  desc "set <directive_name> <directive_value>", "set book-scoped configuration directive"
 
-  # The <b>eject use case</b> writes out a file that was previously ingested
-  # and coccooned inside the safe typically with the file command.
+  # The <b>set <em>use case</em></b> is the generic tool for setting book scoped
+  # configuration directives. These directives can only be read, written, updated
+  # or removed during a logged in branch.
   #
-  # @param file_key [String] the key that the file was ingested against
-  def eject file_key
-    log.info(x) { "[usecase] ~> eject file at chapter/verse against specified key." }
-    eject_uc = SafeDb::Eject.new
-    eject_uc.file_key = file_key
-    eject_uc.to_dir = options[:to_dir] if options[:to_dir]
-    eject_uc.flow_of_events
+  # @param directive_name [String] the name of the book-scoped configuration directive
+  # @param directive_value [String] the value of the book-scoped configuration directive
+  def set directive_name, directive_value
+    log.info(x) { "set the configuration directive value for #{directive_name}" }
+    set_uc = SafeDb::Set.new
+    set_uc.directive_name = directive_name
+    set_uc.directive_value = directive_value
+    set_uc.flow()
   end
 
 
 
-  # Description of the delete command.
-  desc "delete <entity_id>", "delete a line (key/value pair), or a verse, chapter and even a book"
+  # Description of the remove command.
+  desc "remove <line_id>", "remove a line (key/value pair), or a verse, chapter and even a book"
 
-  # The <b>delete use case</b> can delete a single line (key/value pair), or
+  # The <b>remove use case</b> can remove a single line (key/value pair), or
   # a verse, chapter and even a book
   #
-  # @param entity_id [String] the ID of the entity to delete (line, verse, chapter or book)
-  def delete entity_id
-    log.info(x) { "[usecase] ~> delete a safe entity with a key id [#{entity_id}]." }
-    delete_uc = SafeDb::DeleteMe.new
-    delete_uc.entity_id = entity_id
-    delete_uc.flow_of_events
+  # @param line_id [String] the ID of the entity to remove (line, verse, chapter or book)
+  def remove line_id
+    log.info(x) { "remove a safe entity with a key id [#{line_id}]." }
+    remove_uc = SafeDb::Remove.new()
+    remove_uc.line_id = line_id
+    remove_uc.flow()
   end
 
 
 
   # Description of the read command.
-  desc "read <file_url>", "read (reread) file either locally or via http, git or ssh"
+  desc "read <file_url>", "read file into the open chapter and verse for safe keeping."
 
-  # The <b>read use case</b> pulls a read in from either an accessible readsystem
-  # or from a remote http, https, git, S3, GoogleDrive and/or ssh source.
-  #
-  # This use case expects a @file_url parameter. The actions it takes are to
-  #
-  # - register @in.url to mirror @file_url
-  # - register @out.url to mirror @file_url
-  # - check the location of @file_url
-  # - if no file exists it humbly finishes up
+  # The <b>read use case</b> pulls a file in from either an accessible filesystem.
   #
+  # @param file_key [String] keyname representing the file that is being read in
   # @param file_url [String] url of file to ingest and assimilate into the safe
-  def read file_url
-    log.info(x) { "[usecase] ~> read (reread) file from optional url [[ #{file_url} ]]" }
+  def read file_key, file_url
+    log.info(x) { "read file into key #{file_key} from url #{file_url}" }
     read_uc = SafeDb::Read.new
+    read_uc.file_key = file_key
     read_uc.file_url = file_url
-    read_uc.flow_of_events
+    read_uc.flow()
   end
 
 
 
   # Description of the write command.
-  desc "write <file_url>", "write out file at chapter/verse to (optional) file url"
+  desc "write <file_key>", "write out file to current folder or use --to_dir=</path/to/dir."
 
   # The <b>write use case</b> writes out a file that was previously ingested
   # and coccooned inside the safe.
   #
-  # @param file_url [String] optional file url marking where to write the file
-  def write( file_url = nil )
-    log.info(x) { "[usecase] ~> write out file at chapter/verse to (optional) file url." }
+  # @param file_key [String] the key name of the file to write out onto the filesystem
+  def write( file_key )
+    log.info(x) { "write out the file against key #{file_key}" }
+    log.info(x) { "output folder optionally set to #{options[:to_dir]}" } if options[:to_dir]
     write_uc = SafeDb::Write.new
-    write_uc.file_url = file_url if file_url
-    write_uc.flow_of_events
+    write_uc.file_key = file_key
+    write_uc.to_dir = options[:to_dir] if options[:to_dir]
+    write_uc.flow()
   end
 
 
@@ -328,8 +375,8 @@ class Interprete < Thor
   # Show the secrets at the opened path. These secrets
   # are simply written out to the shell console.
   def show
-    log.info(x) { "[usecase] ~> show dictionary at the opened chapter and verse." }
-    SafeDb::Show.new.flow_of_events
+    log.info(x) { "show dictionary at the opened chapter and verse." }
+    SafeDb::Show.new.flow()
   end
 
 
@@ -340,9 +387,9 @@ class Interprete < Thor
   # Display a bird's eye view of the domain's database including
   # its envelopes, their keys and imported objects such as files.
   def view
-    log.info(x) { "[usecase] ~> print list of chapter and verse combos to console." }
+    log.info(x) { "print list of chapter and verse combos to console." }
     view_uc = SafeDb::View.new
-    view_uc.flow_of_events
+    view_uc.flow()
   end
 
 
@@ -356,10 +403,10 @@ class Interprete < Thor
   # @param index [Number]
   #    the integer index chosen from the list procured by the view command.
   def goto index
-    log.info(x) { "[usecase] ~> opens the chapter and verse at index [#{index}]." }
+    log.info(x) { "opens the chapter and verse at index [#{index}]." }
     goto_uc = SafeDb::Goto.new
     goto_uc.index = index
-    goto_uc.flow_of_events
+    goto_uc.flow()
 
   end
 
@@ -385,10 +432,10 @@ class Interprete < Thor
   #    the terraform command to run which is currently limited to plan, apply and destroy.
   #    This parameter is optional and if nothing is given then "apply" is assumed.
   def terraform( command = nil )
-    log.info(x) { "[usecase] ~> will export IAM credentials then invoke $ terraform #{command}" }
+    log.info(x) { "will export IAM credentials then invoke $ terraform #{command}" }
     terraform_uc = SafeDb::Terraform.new
     terraform_uc.command = command if command
-    terraform_uc.flow_of_events
+    terraform_uc.flow()
   end
 
 
@@ -422,14 +469,14 @@ class Interprete < Thor
   #
   def jenkins( command, service, url )
 
-    log.info(x) { "[usecase] ~> request to #{command} #{service} credentials to Jenkins at #{url}" }
+    log.info(x) { "request to #{command} #{service} credentials to Jenkins at #{url}" }
     jenkins_uc = SafeDb::Jenkins.new
 
     jenkins_uc.command = command if command
     jenkins_uc.service = service if service
     jenkins_uc.url     = url     if url
 
-    jenkins_uc.flow_of_events
+    jenkins_uc.flow()
 
   end
 
@@ -448,10 +495,10 @@ class Interprete < Thor
   #    login or logout
   def docker( command = "login" )
 
-    log.info(x) { "[usecase] ~> request to #{command} into or out of a docker repository." }
+    log.info(x) { "request to #{command} into or out of a docker repository." }
     docker_uc = SafeDb::Docker.new
     docker_uc.command = command
-    docker_uc.flow_of_events
+    docker_uc.flow()
 
   end
 
@@ -461,16 +508,16 @@ class Interprete < Thor
   desc "vpn <command>", "runs vpn command typically safe vpn up or safe vpn down"
 
   # This VPN use case connects to the VPN whose specifics are recorded within the vpn.ini
-  # factfile living in the same directory as the vpn.rb usecase class.
+  # factfile living in the same directory as the vpn.rb controlling class.
   #
   # @param command [String]
   #    the vpn command to run which is currently limited to up or down
   #    This parameter is optional and if nothing is given then "up" is assumed.
   def vpn( command = nil )
-    log.info(x) { "[usecase] ~> VPN connection command #{command} has been issued." }
+    log.info(x) { "VPN connection command #{command} has been issued." }
     vpn_uc = SafeDb::Vpn.new
     vpn_uc.command = command if command
-    vpn_uc.flow_of_events
+    vpn_uc.flow()
   end
 
 
@@ -480,9 +527,9 @@ class Interprete < Thor
 
   # Put out the multiple formats of the current timestamp.
   def id
-    log.info(x) { "[usecase] ~> prints out the current timestamp identifiers." }
+    log.info(x) { "prints out the current timestamp identifiers." }
     id_uc = SafeDb::Id.new
-    id_uc.flow_of_events
+    id_uc.flow()
   end