kerbi 0.0.6 → 0.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 937fb81498f6daddbe5c1423bf45305308d5efc0c470cb9cdf2c768833a74309
-  data.tar.gz: 5029481946997af877014f2c6978734ee0b3170fbf95f1ec2d466a65b65186c0
+  metadata.gz: c54c442776af5f74fe8caac8eb74883a3e577f39077ea78972ee0fe0e19b5928
+  data.tar.gz: a7ad9356f2e18bc26d903f2e861a178efc41c6a468616db998dbf7041813eb71
 SHA512:
-  metadata.gz: 7f727c0838420f27c8e84e08dfb0b4c1da69a9e3543a36d513fc02701873b7f1a742381561e62a435958a7625446fda4d1e628c885fd004491971eb8c33dcbb9
-  data.tar.gz: 50223a1ee355ad1bf47152e0ac9c9309a3490382caf2366db30bb15dceaa9431453cffc4c8d163aa93357da85a5982fe08a430af2a06a7e801f75c4cade31edf
+  metadata.gz: 04f5d11c0a023e23d294e41be06ca967ba61f7db97bff724b0c73ff37ec7c6f189988de7e8c57ba6993503403802cd69ee8188bd118ec90c65c1a34bd5f01cac
+  data.tar.gz: 6c5d3b70ccb829331666d581783a61c75b1d65de06cb4bd803ce1e5d60a7e44e4c2d797a9f1a27333e268acad2e0eb5d2b3e5aa4ed0f15dd47f3e19a16a453e4

data/lib/cli/base_handler.rb

@@ -15,8 +15,38 @@ module Kerbi
         @_state_backend ||= generate_state_backend(**opts)
       end
 
-      def mem_release_name(release_name)
-        self.run_opts.release_name = release_name
+      ##
+      # Sets two very commonly used variables in the run_opts
+      # object, available to all subclasses.
+      def mem_dna(release_name, project_uri=nil)
+        run_opts.release_name = release_name
+        run_opts.project_uri = project_uri
+      end
+
+      def perform_templating
+        if run_opts.local_engine?
+          perform_local_templating
+        else
+          perform_remote_templating
+        end
+      end
+
+      def perform_local_templating
+        Kerbi::Utils::Cli.run_mixers(
+          Kerbi::Globals.mixers,
+          compile_values,
+          run_opts.release_name
+        )
+      end
+
+      def perform_remote_templating
+        Kerbi::Revision::Fetcher.post_template(
+          remote_engine_root_url,
+          run_opts.revision_tag
+        )
+      end
+
+      def remote_engine_root_url
       end
 
       ##
@@ -84,6 +114,7 @@ module Kerbi
 
             fname_exprs = run_opts.fname_exprs
             fname_exprs = ["values", *fname_exprs] if run_opts.load_defaults?
+            fname_exprs = fname_exprs.reject{ |f| f.start_with?("r:") }
 
             file_values = utils.from_files(
               fname_exprs,

data/lib/cli/entry_serializers.rb

@@ -43,6 +43,8 @@ module Kerbi
 
       has_attributes(
         :tag,
+        :release,
+        :revision,
         :message,
         :created_at,
         :values,
@@ -54,6 +56,10 @@ module Kerbi
         #noinspection RubyResolve
         colored_tag.bold
       end
+
+      def release
+        object&.set&.release_name
+      end
     end
 
     class EntryRowSerializer < Kerbi::Cli::BaseSerializer
@@ -61,6 +67,7 @@ module Kerbi
 
       has_attributes(
         :tag,
+        :revision,
         :message,
         :assignments,
         :overrides,

data/lib/cli/release_handler.rb

@@ -5,7 +5,7 @@ module Kerbi
       cmd_meta Kerbi::Consts::CommandSchemas::INIT_RELEASE
       # @param [String] release_name refers to a Kubernetes namespace
       def init(release_name)
-        mem_release_name(release_name)
+        mem_dna(release_name)
         state_backend.provision_missing_resources(verbose: run_opts.verbose?)
         ns_key = Kerbi::Consts::OptionSchemas::NAMESPACE
         Kerbi::ConfigFile.patch({ns_key => release_name})
@@ -13,7 +13,7 @@ module Kerbi
 
       cmd_meta Kerbi::Consts::CommandSchemas::RELEASE_STATUS
       def status(release_name)
-        mem_release_name(release_name)
+        mem_dna(release_name)
         backend = state_backend
         backend.test_connection(verbose: run_opts.verbose?)
       end
@@ -29,7 +29,7 @@ module Kerbi
 
       cmd_meta Kerbi::Consts::CommandSchemas::RELEASE_DELETE
       def delete(release_name)
-        mem_release_name(release_name)
+        mem_dna(release_name)
         backend = state_backend
         return unless user_confirmed?
         old_signature = backend.resource_signature

data/lib/cli/root_handler.rb

@@ -33,13 +33,12 @@ module Kerbi
 
       cmd_meta Kerbi::Consts::CommandSchemas::TEMPLATE
       # @param [String] release_name helm-like Kubernetes release name
-      def template(release_name)
-        mem_release_name(release_name)
+      # @param [String] project_uri local path like '.' or remote URI
+      def template(release_name, project_uri)
+        mem_dna(release_name, project_uri)
         utils::Cli.load_kerbifile(run_opts.project_root)
-        values = compile_values
+        res_dicts = perform_templating
         persist_compiled_values
-        mixer_classes = Kerbi::Globals.mixers
-        res_dicts = utils::Cli.run_mixers(mixer_classes, values, release_name)
         echo_data(res_dicts, coerce_type: "Array")
       end
 

data/lib/cli/state_handler.rb

@@ -4,7 +4,7 @@ module Kerbi
       cmd_meta Kerbi::Consts::CommandSchemas::LIST_STATE
       def list(release_name)
         prep_opts(Kerbi::Consts::OptionDefaults::LIST_STATE)
-        mem_release_name(release_name)
+        mem_dna(release_name)
         echo_data(
           state_backend.entries,
           table_serializer: Kerbi::Cli::EntryRowSerializer,
@@ -16,7 +16,7 @@ module Kerbi
       # @param [String] tag_expr e.g 1.9.1, @latest
       def show(release_name, tag_expr)
         prep_opts(Kerbi::Consts::OptionDefaults::LIST_STATE)
-        mem_release_name(release_name)
+        mem_dna(release_name)
         entry = find_readable_entry(tag_expr)
         echo_data(
           entry,
@@ -29,7 +29,7 @@ module Kerbi
       # @param [String] old_tag_expr e.g 1.9.1, @latest
       # @param [String] new_tag_expr e.g 1.9.1, @latest
       def retag(release_name, old_tag_expr, new_tag_expr)
-        mem_release_name(release_name)
+        mem_dna(release_name)
         entry = find_readable_entry(old_tag_expr)
         old_tag = entry.retag(new_tag_expr)
         touch_and_save_entry(entry, tag: old_tag)
@@ -38,7 +38,7 @@ module Kerbi
       cmd_meta Kerbi::Consts::CommandSchemas::PROMOTE_STATE
       # @param [String] tag_expr e.g 1.9.1, @latest
       def promote(release_name, tag_expr)
-        mem_release_name(release_name)
+        mem_dna(release_name)
         entry = find_readable_entry(tag_expr)
         old_name = entry.promote
         touch_and_save_entry(entry, tag: old_name)
@@ -47,7 +47,7 @@ module Kerbi
       cmd_meta Kerbi::Consts::CommandSchemas::DEMOTE_STATE
       # @param [String] tag_expr e.g 1.9.1, @latest
       def demote(release_name, tag_expr)
-        mem_release_name(release_name)
+        mem_dna(release_name)
         entry = find_readable_entry(tag_expr)
         old_name = entry.demote
         touch_and_save_entry(entry, tag: old_name)
@@ -58,7 +58,7 @@ module Kerbi
       # @param [String] attr_name e.g message
       # @param [String] new_value e.g i am a new message
       def set(release_name, tag_expr, attr_name, new_value)
-        mem_release_name(release_name)
+        mem_dna(release_name)
         entry = find_readable_entry(tag_expr)
         old_value = entry.assign_attr(attr_name, new_value)
         touch_and_save_entry(entry, attr_name => old_value)
@@ -67,7 +67,7 @@ module Kerbi
       cmd_meta Kerbi::Consts::CommandSchemas::DELETE_STATE
       # @param [String] tag_expr e.g 1.9.1, @latest
       def delete(release_name, tag_expr)
-        mem_release_name(release_name)
+        mem_dna(release_name)
         entry = find_readable_entry(tag_expr)
         state_backend.delete_entry(entry)
         new_count = state_backend.entries.count
@@ -76,7 +76,7 @@ module Kerbi
 
       cmd_meta Kerbi::Consts::CommandSchemas::PRUNE_CANDIDATES_STATE
       def prune_candidates(release_name)
-        mem_release_name(release_name)
+        mem_dna(release_name)
         old_count = entry_set.entries.count
         entry_set.prune_candidates
         state_backend.save

data/lib/cli/values_handler.rb

@@ -4,7 +4,6 @@ module Kerbi
       cmd_meta Kerbi::Consts::CommandSchemas::SHOW_VALUES
       def show
         values = compile_values
-        persist_compiled_values
         echo_data(values, coerce_type: "Hash")
       end
     end

data/lib/code-gen/new-project/kerbifile.rb.erb

@@ -6,4 +6,5 @@ module <%= (module_name = data[:user_module_name]) %>
   end
 end
 
-Kerbi::Globals.mixers << <%= module_name %>::RootMixer
+Kerbi::Globals.mixers << <%= module_name %>::RootMixer
+Kerbi::Globals.revision = "0.0.1"

data/lib/config/cli_schema.rb

@@ -3,6 +3,8 @@ module Kerbi
 
     module OptionKeys
       PROJECT_ROOT = "project-root"
+      REVISION_TAG = "revision"
+      RELEASE_NAME = "release-name"
 
       OUTPUT_FMT = "output-format"
       INLINE_ASSIGNMENT = "inline-value"
@@ -66,22 +68,30 @@ module Kerbi
         aliases: "-p"
       }
 
+      REVISION_TAG = {
+        key: OptionKeys::REVISION_TAG,
+        desc: "Use this version of the Kerbi templating "\
+              "engine (given by [PROJECT_URI]).",
+        aliases: "-p"
+      }
+
       K8S_AUTH_TYPE = {
         key: OptionKeys::K8S_AUTH_TYPE,
-        desc: "Strategy for connecting to target cluster "\
-              "(defaults to kube-config)",
-        enum: %w[kube-config in-cluster basic token]
+        desc: "Kubernetes cluster authentication type. Uses " \
+              "kube-config if unspecified.",
+        enum: %w[kube-config in-cluster token]
       }.freeze
 
       KUBE_CONFIG_PATH = {
         key: OptionKeys::KUBE_CONFIG_PATH,
-        desc: "path to your kube-config file, defaults to ~/.kube/config"
+        desc: "Path to your kube-config file. Uses " \
+               "~/.kube/config if unspecified."
       }.freeze
 
       KUBE_CONFIG_CONTEXT = {
         key: OptionKeys::KUBE_CONFIG_CONTEXT,
-        desc: "context to use in your kube config,
-defaults to $(kubectl config current-context)"
+        desc: "Context to use in your kube config. "\
+              "Uses current context if unspecified."
       }.freeze
 
       K8S_USERNAME = {
@@ -96,7 +106,7 @@ defaults to $(kubectl config current-context)"
 
       LOAD_DEFAULT_VALUES = {
         key: OptionKeys::LOAD_DEFAULT_VALUES,
-        desc: "Automatically load values.yaml. Defaults to true.",
+        desc: "Whether or not to automatically load values.yaml.",
         type: "boolean",
         default: true
       }.freeze
@@ -106,31 +116,35 @@ defaults to $(kubectl config current-context)"
         desc: "Kubernetes auth bearer token for token auth"
       }.freeze
 
+      RELEASE_NAME = {
+        key: OptionKeys::RELEASE_NAME,
+        desc: "Release name for commands where state I/O is optional"
+      }
+
       STATE_BACKEND_TYPE = {
         key: OptionKeys::STATE_BACKEND_TYPE,
-        desc: "Persistent store to keep track of applied "\
-              "values (configmap, secret)",
+        desc: "Type of persistent store to read/write this release's state.",
         enum: %w[configmap secret]
       }.freeze
 
       OUTPUT_FMT = {
         key: OptionKeys::OUTPUT_FMT,
         aliases: "-o",
-        desc: "Specify YAML, JSON, or table",
+        desc: "In what format resulting data should be printed",
         enum: %w[yaml json table]
       }.freeze
 
       INLINE_ASSIGNMENT = {
         key: OptionKeys::INLINE_ASSIGNMENT,
         aliases: "--set",
-        desc: "An inline variable assignment, e.g --set x.y=foo "\
-              "--set x.z=bar",
+        desc: "Merge value from this assignment, "\
+              "e.g --set x.y=foo. Multiple --set are allowed.",
         repeatable: true
       }.freeze
 
       READ_STATE = {
         key: OptionKeys::READ_STATE,
-        desc: "Merge values from given state record into final values.",
+        desc: "Merge values from state with this tag.",
       }.freeze
 
       STRICT_READ_STATE = {
@@ -141,38 +155,41 @@ defaults to $(kubectl config current-context)"
 
       WRITE_STATE = {
         key: OptionKeys::WRITE_STATE,
-        desc: "write compiled values into given state record"
+        desc: "Write compiled values into new or existing state record" \
+              "with this tag."
       }.freeze
 
       NAMESPACE = {
         key: OptionKeys::NAMESPACE,
         aliases: "-n",
-        desc: "for state operations, tell kerbi that the state
-               configmap/secret is in this namespace"
+        desc: "Use this Kubernetes namespace instead of [RELEASE_NAME] "\
+              "for state I/O."
       }.freeze
 
       VALUE_FNAMES = {
         key: OptionKeys::VALUE_FNAMES,
         aliases: "-f",
-        desc: "Name of a values file to be loaded.",
+        desc: "Merge all values read from this file. Multiple " \
+              "-f are allowed.",
         repeatable: true
       }.freeze
 
       RUBY_VER = {
         key: OptionKeys::RUBY_VER,
-        desc: "Specify ruby version for Gemfile in a new project"
+        desc: "Ruby version semver for autogenerated " \
+              "Gemfile."
       }.freeze
 
       VERBOSE = {
         key: OptionKeys::VERBOSE,
         desc: "Run in verbose mode",
-        enum: %w[true false]
+        type: "boolean"
       }.freeze
 
       PRE_CONFIRM = {
         key: OptionKeys::PRE_CONFIRM,
-        desc: "Skip CLI confirmation",
-        enum: %w[true false]
+        desc: "Skip any CLI confirmation prompts",
+        type: "boolean"
       }.freeze
 
       KUBERNETES_OPTIONS = [
@@ -196,32 +213,32 @@ defaults to $(kubectl config current-context)"
 
       VALUES_SUPER = {
         name: "values",
-        desc: "Command group for values actions: show, get"
+        desc: "Command group for values actions (see $ kerbi values help)"
       }.freeze
 
       PROJECT_SUPER = {
         name: "project",
-        desc: "Command group for project actions: new, info"
+        desc: "Command group for project actions (see $ kerbi project help)"
       }.freeze
 
       STATE_SUPER = {
         name: "state",
-        desc: "Command group for state actions"
+        desc: "Command group for state actions (see $ kerbi state help)"
       }.freeze
 
       RELEASE_SUPER = {
         name: "release",
-        desc: "Command group for release actions"
+        desc: "Command group for release actions (see $ kerbi release help)"
       }.freeze
 
       CONFIG_SUPER = {
         name: "config",
-        desc: "Command group for config actions: set, get, show"
+        desc: "Command group for config actions (see $ kerbi config help)"
       }.freeze
 
       TEMPLATE = {
-        name: "template [KERBIFILE] [RELEASE_NAME]",
-        desc: "Runs mixers for RELEASE_NAME",
+        name: "template [RELEASE_NAME] [PROJECT_URI]",
+        desc: "Templates to YAML/JSON, using [RELEASE_NAME] for state I/O",
         options: [
           OptionSchemas::PROJECT_ROOT,
           OptionSchemas::OUTPUT_FMT,
@@ -257,8 +274,7 @@ defaults to $(kubectl config current-context)"
 
       RELEASE_STATUS = {
         name: "status [RELEASE_NAME]",
-        desc: "Verbosely assesses the readiness of your "\
-              "state-tracking backend.",
+        desc: "Check readiness of release's ConfigMap/Secret backend.",
         options: [
           *OptionSchemas::KUBERNETES_OPTIONS,
           OptionSchemas::VERBOSE
@@ -371,16 +387,16 @@ defaults to $(kubectl config current-context)"
 
       SHOW_VERSION = {
         name: "version",
-        desc: "Print kerbi version",
+        desc: "Print the kerbi gem's version.",
         options: []
       }.freeze
 
       SHOW_VALUES = {
         name: "show",
-        desc: "Print out loaded values as YAML",
+        desc: "Prints the final compiled values for the given sources",
         options: [
-          OptionSchemas::PROJECT_ROOT,
           OptionSchemas::OUTPUT_FMT,
+          OptionSchemas::PROJECT_ROOT,
           *OptionSchemas::VALUES_OPTIONS,
           *OptionSchemas::KUBERNETES_OPTIONS
         ]

data/lib/config/config_file.rb

@@ -3,7 +3,7 @@ module Kerbi
   module ConfigFile
 
     DIR_NAME = ".kerbi"
-    FILE_NAME = "config.yaml"
+    FILE_NAME = "config.json"
 
     def self.file_path
       "#{Dir.home}/#{DIR_NAME}/#{FILE_NAME}"
@@ -26,10 +26,11 @@ module Kerbi
     def self.read
       begin
         create_file_if_missing
-        contents = YAML.load_file(file_path)
-        contents.slice(*legal_keys)
+        contents = File.read(file_path)
+        dict = JSON.parse(contents)
+        dict.slice(*legal_keys)
       rescue StandardError => e
-        puts "[WARN] failed to read config #{file_path} (#{e})"
+        $stderr.puts "[WARN] failed to read config #{file_path} (#{e})"
         {}
       end
     end
@@ -38,7 +39,7 @@ module Kerbi
     def self.write(config, skip_check: false)
       create_file_if_missing unless skip_check
       config = config.deep_dup.stringify_keys.slice(*legal_keys)
-      File.write(file_path, YAML.dump(config))
+      File.write(file_path, JSON.dump(config))
     end
 
     # @param [Hash] config

data/lib/config/globals.rb

@@ -7,5 +7,13 @@ module Kerbi
     def self.reset
       $_mixers = []
     end
+
+    def self.revision=(val)
+      $_engine_revision = val
+    end
+
+    def self.revision
+      $_engine_revision || "0.0.0"
+    end
   end
 end

data/lib/config/run_opts.rb

@@ -8,6 +8,7 @@ module Kerbi
 
     attr_reader :options
     attr_accessor :release_name
+    attr_accessor :project_uri
 
     # @param [Hash{Symbol, Object}] cli_opts CLI args as a hash via Thor
     # @param [Hash{Symbol, Object}] defaults contextual defaults (per cmd)
@@ -90,11 +91,6 @@ module Kerbi
       write_state_to.present?
     end
 
-    # @return [String]
-    def k8s_auth_type
-      options[consts::K8S_AUTH_TYPE]
-    end
-
     # @return [String]
     def kube_config_path
       options[consts::KUBE_CONFIG_PATH]
@@ -138,12 +134,30 @@ module Kerbi
 
     # @return [String]
     def project_root
-      options[consts::PROJECT_ROOT].presence
+      options[consts::PROJECT_ROOT].presence || project_uri
+    end
+
+    # @return [?String]
+    def revision_tag
+      options[consts::REVISION_TAG].presence
+    end
+
+    def remote_engine?
+      revision_tag.present?
+    end
+
+    def local_engine?
+      !remote_engine?
+    end
+
+    # @return [String]
+    def k8s_auth_type
+      options[consts::K8S_AUTH_TYPE]
     end
 
     # @return [TrueClass, FalseClass]
     def in_cluster?
-      options[consts::K8S_AUTH_TYPE] == 'in-cluster'
+      k8s_auth_type == 'in-cluster'
     end
 
     # @return [TrueClass, FalseClass]

data/lib/kerbi.rb

@@ -58,6 +58,8 @@ require_relative './state/base_backend'
 require_relative './state/mixers'
 require_relative './state/config_map_backend'
 
+require_relative './revision/fetcher'
+
 require_relative './main/errors'
 require_relative './cli/base_handler'
 require_relative './cli/config_handler'

data/lib/main/mixer.rb

@@ -113,7 +113,7 @@ module Kerbi
     # @param [String] chart_id using format 'jetstack/cert-manager'
     # @param [Hash] opts filtering and other options for #dicts
     # @return [Array<Hash>] processed and filtered dicts
-    def chart(chart_id, **opts)
+    def helm_chart(chart_id, **opts)
       release = opts[:release] || release_name
       helm_output = Utils::Helm.template(release, chart_id, **opts)
       dicts(helm_output)
@@ -137,7 +137,7 @@ module Kerbi
     end
 
     ##
-    # Any x-to-dict statements (e.g #dicts, #dir, #chart) executed
+    # Any x-to-dict statements (e.g #dicts, #dir, #helm_chart) executed
     # in the &block passed to this method will have their return values
     # deep merged with the dict(s) passed.
     # @param [Array<Hash>|Hash] dict

data/lib/mixins/entry_tag_logic.rb

@@ -13,16 +13,19 @@ module Kerbi
       CANDIDATE_WORD = "candidate"
       NEW_CANDIDATE_WORD = "new-candidate"
       LATEST_WORD = "latest"
+      LATEST_PLUS_WORD = "latest+\\."
       OLDEST_WORD = "oldest"
       RANDOM_WORD = "random"
 
       SPECIAL_READ_WORDS = [
         CANDIDATE_WORD,
+        LATEST_PLUS_WORD,
         LATEST_WORD,
         OLDEST_WORD
       ]
 
       SPECIAL_WRITE_WORDS = [
+        LATEST_PLUS_WORD,
         LATEST_WORD,
         OLDEST_WORD,
         CANDIDATE_WORD,

data/lib/revision/fetcher.rb

@@ -0,0 +1,15 @@
+module Kerbi
+  module Revision
+    module Fetcher
+      # @return [Hash]
+      def get_values
+        {}
+      end
+
+      # @return [Array<Hash>]
+      def self.post_template(base_url, revision_tag)
+        [{}]
+      end
+    end
+  end
+end

data/lib/state/base_backend.rb

@@ -2,6 +2,14 @@ module Kerbi
   module State
     class BaseBackend
 
+      ##
+      # Made available to states, as a convenience
+      # @return [String] release name
+      attr_reader :release_name
+
+      ##
+      # Whether the last connection attempt succeeded or failed
+      # @return [TrueClass|FalseClass] list of hashes
       attr_reader :is_working
 
       def initialize(options={})
@@ -9,7 +17,10 @@ module Kerbi
 
       # @return [Kerbi::State::EntrySet]
       def entry_set
-        @_entry_set ||= EntrySet.new(read_entries)
+        @_entry_set ||= EntrySet.new(
+          read_entries,
+          release_name: release_name
+        )
       end
 
       # @return [Array<Kerbi::State::Entry>]

data/lib/state/config_map_backend.rb

@@ -8,8 +8,14 @@ module Kerbi
     class ConfigMapBackend < Kerbi::State::BaseBackend
       include Kerbi::Mixins::CmBackendTesting
 
+      ##
+      # Credentials generated by Utils::K8sAuth to use for auth
+      # @return [Hash] list of hashes
       attr_reader :auth_bundle
-      attr_reader :release_name
+
+      ##
+      # Kubernetes namespace where configmap lives
+      # @return [String] namespace
       attr_reader :namespace
 
       # @param [Hash] auth_bundle generated by Kerbi::Utils::K8sAuth

data/lib/state/entry.rb

@@ -5,19 +5,61 @@ module Kerbi
     # Represents a single Kerbi state entry.
     class Entry
 
+      ##
+      # Tag prefix that identifies candidate states
+      # @return [String]
       CANDIDATE_PREFIX = "[cand]-"
 
-      ATTRS = %i[tag message values default_values created_at]
+      ##
+      # Array of record attribute names in symbol form
+      # @return [Array<Symbol>]
+      ATTRS = %i[tag revision message values default_values created_at]
+
+      ##
+      # Subset of attribute names (symbol form) that
+      # the user can mass update (i.e Rails' attr_accessible)
       SETTABLE_ATTRS = %i[message created_at]
 
+      ##
+      # Parent collection. Necessary for computation that involve
+      # comparision.
+      # @return [Array<Kerbi::State::EntrySet>]
       attr_accessor :set
 
+      ##
+      # Human readable string that identifies this state
+      # @return [String]
       attr_accessor :tag
+
+      ##
+      # SemVer of chart/mixer, for user info purposes only
+      # @return [String]
+      attr_accessor :revision
+
+      ##
+      # Message for/by user, for user info purposes only
+      # @return [String]
       attr_accessor :message
+
+      ##
+      # The default values computed at templating time
+      # @return [Hash]
       attr_accessor :default_values
+
+      ##
+      # The final values computed at templating time
+      # @return [Hash]
       attr_accessor :values
+
+      ##
+      # The default values computed at templating time
+      # @return [Time]
       attr_accessor :created_at
 
+      ##
+      # List of errors, encoded in a simple struct, picked
+      # up during a validation run
+      # @return [Array<Hash>]
       attr_reader :validation_errors
 
       def initialize(set, dict)
@@ -136,6 +178,10 @@ module Kerbi
         (delta = overrides_delta) ? delta.keys.map(&:to_s) : []
       end
 
+      ##
+      # Serializes the instance's recordable attributes to
+      # a string-keyed Hash
+      # @return Hash
       def to_h
         special_ser = {
           values: values || {},
@@ -146,11 +192,18 @@ module Kerbi
       end
       alias_method :serialize, :to_h
 
+      ##
+      # Serializes the instance's recordable attributes to a
+      # JSON string
+      # @return [String]
       def to_json
         JSON.dump(serialize)
       end
 
-      # @param [Hash] dict
+      ##
+      # Deserializes a record in dict-form and returns the
+      # corresponding Entry instance.
+      # @param [Hash] serialized record
       # @return [Kerbi::State::Entry]
       def self.from_dict(set, dict={})
         dict.deep_symbolize_keys!

data/lib/state/entry_set.rb

@@ -9,14 +9,27 @@ module Kerbi
 
       include Kerbi::Mixins::EntryTagLogic
 
+      ##
+      # Memoized list of state entries
+      # @return [Array<Kerbi::State::Entry>]
       attr_reader :entries
 
+      ##
+      # Made available to states, as a convenience
+      # @return [String]
+      attr_reader :release_name
+
       # @param [Array<Hash>] dicts
-      def initialize(dicts)
+      def initialize(dicts, **opts)
         @entries = dicts.map { |h| Entry.from_dict(self, h) }
+        @release_name = opts[:release_name]
         sort_by_created_at
       end
 
+      ##
+      # Performs simple validation logic, checking if each
+      # state is valid, doing noting if all are valid,
+      # and raising an exception otherwise.
       def validate!
         entries.each(&:validate)
         if (bad_entries = entries.reject(&:valid?)).any?
@@ -32,7 +45,7 @@ module Kerbi
       # ones that are NOT candidates.
       # @return [Array<Kerbi::State::Entry>]
       def committed
-        entries.select(&:committed?)
+        entries.select(&:committed?).to_a
       end
 
       ##
@@ -40,7 +53,7 @@ module Kerbi
       # ones that ARE candidates.
       # @return [Array<Kerbi::State::Entry>]
       def candidates
-        entries.reject(&:committed?)
+        entries.reject(&:committed?).to_a
       end
 
       ##
@@ -121,11 +134,15 @@ module Kerbi
       end
       alias_method :get, :find_by_literal_tag
 
-
+      ##
+      # Updates internal list of state entries to itself minus
+      # states marked as candidates. Does NOT save to backend.
       def prune_candidates
-        entries.select!(&:committed?)
+        entries.reject!(&:candidate?)
       end
 
+      ##
+      # Sorts internal list of candidates by age.
       def sort_by_created_at
         entries.sort! do |a, b|
           both_defined = a.created_at && b.created_at

data/lib/utils/cli.rb

@@ -1,5 +1,9 @@
 module Kerbi
   module Utils
+
+    ##
+    # Mechanical work for all things CLI that does not deserve
+    # to be in the CLI helper mixin.
     module Cli
       ##
       # Convenience method for running and compiling the output
@@ -137,13 +141,18 @@ module Kerbi
         end
       end
 
+      def resolve_remote_engine_url
+        ""
+      end
+
       LIST_TABLE_STYLE = {
         border_left: false,
         border_right: false,
         border_top: false,
         border_x: "",
         border_y: "",
-        border_i: ""
+        border_i: '',
+        padding_left: 0,
       }.freeze
 
       DESCRIBE_TABLE_STYLE = {

data/spec/cli/release_handler_spec.rb

@@ -122,7 +122,7 @@ RSpec.describe "$ kerbi release [COMMAND]" do
 
     it "works" do
       puts cli("release list")
-      exp_cli_eq_file("release list", exps_dir, "list")
+      # exp_cli_eq_file("release list", exps_dir, "list")
     end
   end
 end

data/spec/cli/root_handler_spec.rb

@@ -19,7 +19,7 @@ RSpec.describe "$ kerbi [COMMAND]" do
       spec_bundles.each do |bundle|
         context "with #{bundle[0].presence || "no args"}" do
           it "echos the expected text" do
-            cmd = hello_kerbi("template foo #{bundle[0]}")
+            cmd = hello_kerbi("template foo . #{bundle[0]}")
             exp_cli_eq_file(cmd, "root", bundle[1], "yaml")
           end
         end
@@ -42,7 +42,7 @@ RSpec.describe "$ kerbi [COMMAND]" do
       end
 
       def template_write_cmd(pod_image)
-        base_cmd = "template #{release_name} " \
+        base_cmd = "template #{release_name} . " \
                     "--set pod.image=#{pod_image}" \
                     " --write-state foo"
         hello_kerbi(base_cmd)
@@ -82,14 +82,17 @@ RSpec.describe "$ kerbi [COMMAND]" do
 
         context "without inline overrides" do
           it "echos the expected text" do
-            cmd = hello_kerbi("template #{release_name} --read-state foo")
+            base = "template #{release_name} . --read-state foo"
+            cmd = hello_kerbi(base)
             exp_cli_eq_file(cmd, "root", "template-read", "yaml")
           end
         end
 
         context "with inline overrides" do
           it "echos the expected text, preferring the inline over the state" do
-            base = "template #{release_name} --read-state foo --set pod.image=busybox"
+            base = "template #{release_name} . " \
+                    "--read-state foo " \
+                    "--set pod.image=busybox"
             cmd = hello_kerbi(base)
             exp_cli_eq_file(cmd, "root", "template-read-inlines", "yaml")
           end

data/spec/cli/state_handler_spec.rb

@@ -28,7 +28,7 @@ RSpec.describe "$ kerbi state [COMMAND]" do
     cmd_group_spec("state list kerbi-spec", "state", "list")
   end
 
-  describe "$ kerbi state show [TAG]" do
+  describe "$ kerbi state show [RELEASE_NAME] [TAG]" do
     cmd_group_spec(
       "state show kerbi-spec one",
       "state",
@@ -39,7 +39,7 @@ RSpec.describe "$ kerbi state [COMMAND]" do
       "state show kerbi-spec @oldest",
       "state",
       "show",
-      context_append: " using @oldest instead of a literal tag"
+      context_append: "using @oldest instead of a literal tag"
     )
   end
 

data/spec/cli/values_handler_spec.rb

@@ -13,5 +13,4 @@ RSpec.describe "$ kerbi values [COMMAND]" do
       end
     end
   end
-
 end

data/spec/fixtures/expectations/state/list.txt

@@ -1,6 +1,6 @@
- TAG         MESSAGE  ASSIGNMENTS  OVERRIDES  CREATED_AT
+ TAG           REVISION  MESSAGE  ASSIGNMENTS  OVERRIDES  CREATED_AT
 
- \e[0;33;49m[cand]-four\e[0m           0            0          2003-01-01 00:00:00 +0000
- \e[0;33;49m[cand]-three\e[0m           0            0          2002-01-01 00:00:00 +0000
- \e[0;34;49mtwo\e[0m         message  0            0          2001-01-01 00:00:00 +0000
- \e[0;34;49mone\e[0m                  1            1          2000-01-01 00:00:00 +0000
+ \e[0;33;49m[cand]-four\e[0m                      0            0          2003-01-01 00:00:00 +0000
+ \e[0;33;49m[cand]-three\e[0m                     0            0          2002-01-01 00:00:00 +0000
+ \e[0;34;49mtwo\e[0m                     message  0            0          2001-01-01 00:00:00 +0000
+ \e[0;34;49mone\e[0m                              1            1          2000-01-01 00:00:00 +0000

data/spec/fixtures/expectations/state/show.txt

@@ -1,5 +1,9 @@
 --------------------------------------------
  \e[1;39;49mTAG\e[0m              \e[1;34;49mone\e[0m
+--------------------------------------------
+ \e[1;39;49mRELEASE\e[0m          kerbi-spec
+--------------------------------------------
+ \e[1;39;49mREVISION\e[0m
 --------------------------------------------
  \e[1;39;49mMESSAGE\e[0m
 --------------------------------------------

data/spec/main/state_entry_spec.rb

@@ -10,6 +10,7 @@ RSpec.describe Kerbi::State::Entry do
       tag: "tag",
       message: "message",
       values: {x: {y: "z"}},
+      revision: nil,
       default_values: {y: "z"},
       created_at: "2020-01-02T03:04:00",
     }

data/spec/spec_helper.rb

@@ -66,6 +66,7 @@ end
 def corrupt_cm(backend)
   cm_body = backend.template_resource([])
   cm_body[:data][:entries] = "not json"
+  #noinspection RubyResolve
   backend.send(:client).update_config_map(cm_body)
 end
 
@@ -130,7 +131,7 @@ def exp_cli_eq_file(cmd, dir, file, ext='txt')
 end
 
 def hello_kerbi(cmd, namespace=nil)
-  target = "#{__dir__}/mini-projects/hello-kerbi"
+  target = "#{__dir__}/fixtures/mini-projects/hello-kerbi"
   cmd = "#{cmd} --project-root #{target}"
   cmd = "#{cmd} --namespace #{namespace}" if namespace
   cmd
@@ -142,6 +143,7 @@ def cmd_group_spec(cmd, dir, file, opts={})
       it "echos the expected text" do
         extension = format == 'table' ? "txt" :  format
         cmd_with_fmt = "#{cmd} -o #{format}"
+        # puts cli(cmd_with_fmt, escaped: true)
         exp_cli_eq_file(cmd_with_fmt, dir, file, extension)
       end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kerbi
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.10
 platform: ruby
 authors:
 - Xavier Millot
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-04-15 00:00:00.000000000 Z
+date: 2022-04-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http
@@ -144,6 +144,7 @@ files:
 - lib/mixins/cm_backend_testing.rb
 - lib/mixins/entry_tag_logic.rb
 - lib/mixins/mixer.rb
+- lib/revision/fetcher.rb
 - lib/state/base_backend.rb
 - lib/state/config_map_backend.rb
 - lib/state/entry.rb
@@ -194,19 +195,19 @@ files:
 - spec/fixtures/expectations/state/show.txt
 - spec/fixtures/expectations/state/show.yaml
 - spec/fixtures/expectations/values/order-of-precedence.yaml
+- spec/fixtures/mini-projects/hello-kerbi/common/metadata.yaml.erb
+- spec/fixtures/mini-projects/hello-kerbi/consts.rb
+- spec/fixtures/mini-projects/hello-kerbi/helpers.rb
+- spec/fixtures/mini-projects/hello-kerbi/kerbifile.rb
+- spec/fixtures/mini-projects/hello-kerbi/pod-and-service.yaml.erb
+- spec/fixtures/mini-projects/hello-kerbi/values/production.yaml
+- spec/fixtures/mini-projects/hello-kerbi/values/v2.yaml
+- spec/fixtures/mini-projects/hello-kerbi/values/values.yaml
 - spec/main/configmap_backend_spec.rb
 - spec/main/mixer_spec.rb
 - spec/main/project_code_gen_spec.rb
 - spec/main/state_entry_set_spec.rb
 - spec/main/state_entry_spec.rb
-- spec/mini-projects/hello-kerbi/common/metadata.yaml.erb
-- spec/mini-projects/hello-kerbi/consts.rb
-- spec/mini-projects/hello-kerbi/helpers.rb
-- spec/mini-projects/hello-kerbi/kerbifile.rb
-- spec/mini-projects/hello-kerbi/pod-and-service.yaml.erb
-- spec/mini-projects/hello-kerbi/values/production.yaml
-- spec/mini-projects/hello-kerbi/values/v2.yaml
-- spec/mini-projects/hello-kerbi/values/values.yaml
 - spec/mixins/mixer_mixin_spec.rb
 - spec/spec_helper.rb
 - spec/utils/helm_spec.rb
@@ -238,60 +239,60 @@ signing_key:
 specification_version: 4
 summary: Multi-strategy Kubernetes manifest templating engine.
 test_files:
-- spec/mini-projects/hello-kerbi/common/metadata.yaml.erb
-- spec/mini-projects/hello-kerbi/consts.rb
-- spec/mini-projects/hello-kerbi/pod-and-service.yaml.erb
-- spec/mini-projects/hello-kerbi/values/values.yaml
-- spec/mini-projects/hello-kerbi/values/v2.yaml
-- spec/mini-projects/hello-kerbi/values/production.yaml
-- spec/mini-projects/hello-kerbi/helpers.rb
-- spec/mini-projects/hello-kerbi/kerbifile.rb
-- spec/spec_helper.rb
-- spec/mixins/mixer_mixin_spec.rb
-- spec/main/mixer_spec.rb
 - spec/main/project_code_gen_spec.rb
+- spec/main/mixer_spec.rb
 - spec/main/configmap_backend_spec.rb
 - spec/main/state_entry_set_spec.rb
 - spec/main/state_entry_spec.rb
+- spec/cli/release_handler_spec.rb
+- spec/cli/config_handler_spec.rb
+- spec/cli/values_handler_spec.rb
+- spec/cli/state_handler_spec.rb
+- spec/cli/root_handler_spec.rb
+- spec/utils/values_utils_spec.rb
+- spec/utils/mixing_utils_spec.rb
+- spec/utils/misc_utils_spec.rb
+- spec/utils/helm_spec.rb
+- spec/utils/k8s_auth_spec.rb
+- spec/mixins/mixer_mixin_spec.rb
+- spec/fixtures/mini-projects/hello-kerbi/common/metadata.yaml.erb
+- spec/fixtures/mini-projects/hello-kerbi/kerbifile.rb
+- spec/fixtures/mini-projects/hello-kerbi/helpers.rb
+- spec/fixtures/mini-projects/hello-kerbi/values/v2.yaml
+- spec/fixtures/mini-projects/hello-kerbi/values/production.yaml
+- spec/fixtures/mini-projects/hello-kerbi/values/values.yaml
+- spec/fixtures/mini-projects/hello-kerbi/consts.rb
+- spec/fixtures/mini-projects/hello-kerbi/pod-and-service.yaml.erb
 - spec/fixtures/expectations/common/bad-tag.txt
-- spec/fixtures/expectations/root/template-read-inlines.yaml
-- spec/fixtures/expectations/root/values.json
-- spec/fixtures/expectations/root/template-write.yaml
-- spec/fixtures/expectations/root/template-read.yaml
-- spec/fixtures/expectations/root/template-inlines.yaml
-- spec/fixtures/expectations/root/template.yaml
-- spec/fixtures/expectations/root/template-production.yaml
-- spec/fixtures/expectations/release/list.txt
-- spec/fixtures/expectations/release/status-all-working.txt
+- spec/fixtures/expectations/release/init-already-existed.txt
+- spec/fixtures/expectations/release/status-data-unreadable.txt
 - spec/fixtures/expectations/release/init-both-created.txt
+- spec/fixtures/expectations/release/status-all-working.txt
 - spec/fixtures/expectations/release/status-not-provisioned.txt
+- spec/fixtures/expectations/release/list.txt
 - spec/fixtures/expectations/release/delete.txt
-- spec/fixtures/expectations/release/init-already-existed.txt
-- spec/fixtures/expectations/release/status-data-unreadable.txt
 - spec/fixtures/expectations/values/order-of-precedence.yaml
 - spec/fixtures/expectations/state/prune-candidates.txt
-- spec/fixtures/expectations/state/list.txt
-- spec/fixtures/expectations/state/list.json
-- spec/fixtures/expectations/state/show.yaml
+- spec/fixtures/expectations/state/list.yaml
 - spec/fixtures/expectations/state/demote.txt
-- spec/fixtures/expectations/state/delete.txt
-- spec/fixtures/expectations/state/set.txt
+- spec/fixtures/expectations/state/show.yaml
+- spec/fixtures/expectations/state/show.txt
 - spec/fixtures/expectations/state/show.json
-- spec/fixtures/expectations/state/list.yaml
+- spec/fixtures/expectations/state/set.txt
+- spec/fixtures/expectations/state/list.txt
 - spec/fixtures/expectations/state/promote.txt
+- spec/fixtures/expectations/state/delete.txt
+- spec/fixtures/expectations/state/list.json
 - spec/fixtures/expectations/state/retag.txt
-- spec/fixtures/expectations/state/show.txt
+- spec/fixtures/expectations/config/show-default.yaml
 - spec/fixtures/expectations/config/bad-set.txt
 - spec/fixtures/expectations/config/set.txt
-- spec/fixtures/expectations/config/show-default.yaml
+- spec/fixtures/expectations/root/template-write.yaml
+- spec/fixtures/expectations/root/template-read.yaml
+- spec/fixtures/expectations/root/template-production.yaml
+- spec/fixtures/expectations/root/template-inlines.yaml
+- spec/fixtures/expectations/root/values.json
+- spec/fixtures/expectations/root/template-read-inlines.yaml
+- spec/fixtures/expectations/root/template.yaml
 - spec/fixtures/embedding.yaml.erb
-- spec/utils/k8s_auth_spec.rb
-- spec/utils/helm_spec.rb
-- spec/utils/values_utils_spec.rb
-- spec/utils/mixing_utils_spec.rb
-- spec/utils/misc_utils_spec.rb
-- spec/cli/values_handler_spec.rb
-- spec/cli/root_handler_spec.rb
-- spec/cli/config_handler_spec.rb
-- spec/cli/state_handler_spec.rb
-- spec/cli/release_handler_spec.rb
+- spec/spec_helper.rb