power_stencil 0.5.0 → 0.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 925c1cdc265fdddbe244699558bfe8e89bdf28a7
-  data.tar.gz: 66b36b54757cc3593ce06d9da5c608485839b2bf
+  metadata.gz: 40a1c784720fe14e0e62ee24a66c24d0780d6165
+  data.tar.gz: 4eabaf0235839fe34f87ca9d2c3b59cd9c078b00
 SHA512:
-  metadata.gz: e253fbedf2d8a29458168238a7b55dc8eb46a2f7c84b2f61cbed7653fc0a6e795f17c47ddf5cd8b4aa7a1a5ba389d3a86c36d55e5b18552350fd73399be4edc8
-  data.tar.gz: cfc7fc77bcbb74cab625c3b8bca40b9502943701e12509810eb41945f2390f7a7f528a1e8f6cec6be84434b55ae64b71ef0a39691fe7e4425b8403fc0a617390
+  metadata.gz: 352caf7d55a27af71ad39a8e5c1a201943216ae8a685bb32b8592431a7fdccb9365fdc9f0ef636e06a59636c2941e19c1ec42f861a23bf7231b2a1401e2fc1bc
+  data.tar.gz: 97a20691531c85b72e243b8cc6376da7142924546209fe6713f9a5393c4885f8105c6d48fe3b2d2dcd07e1fabc1c37cc0c62ecb8d2ad3778e6e624d28ec345c9

data/doc/builds.md

@@ -20,6 +20,15 @@ Builds
 
 You build a [buildable] entity by issuing `power_stencil build <entity_type>/<entity_name>`. If you try to build an entity which is not buildable, the process fail with an error message.
 
+**:information_source: You can get the list of buildable entities in your repository by issuing a `power_stencil build --list`:**
+
+```
+$ power_stencil build --list
+ - 'simple_exec' (buildable by 'PowerStencil core' and provided by 'PowerStencil core').
+```
+
+We will see later in the [templates] part what to do with this `simple_exec` entity type.
+
 Let's describe a bit more in detail what this build process is:
 
 ![entity-build-flow]
@@ -32,7 +41,7 @@ I guess you understood this is not a "real" _compilation_ process we are discuss
 
 The mechanism of the compilation is coming from the [universe_compiler] Gem, but the two following features are the ones you really need to understand.
 
-:information_source: The compilation process can be applied to any entity, ie it doesn't need to be [buildable] (see in next paragraph how to run the compilation). But an entity needs to be [buildable] to use `power_stencil build` which corresponds actually to _compilation_ + _detemplatization_.
+:information_source: The compilation process is actually applied to all entities, ie it doesn't need to be [buildable] (see in next paragraph how to run the compilation). But an entity needs to be [buildable] to use `power_stencil build` which corresponds actually to _compilation_ + _detemplatization_.
 
 ## Extending an entity
 

data/doc/entities.md

@@ -58,8 +58,8 @@ $ power_stencil info
 PROJECT REPORT
 --------------------------------------------------------------------------------
  General information:
- - Project required version: 0.2.18
- - PowerStencil version: 0.2.18
+ - Project required version: 0.6.1
+ - PowerStencil version: 0.6.1
 --------------------------------------------------------------------------------
  Paths:
  - Project root path: '/tmp/tst2'
@@ -75,12 +75,12 @@ PROJECT REPORT
  -  project_config: 1
 --------------------------------------------------------------------------------
  Available entity types:
- - Type 'base_entity' --> PowerStencil::SystemEntityDefinitions::ProjectEntity
- - Type 'entity_override' --> UniverseCompiler::Entity::Override
- - Type 'plugin_definition' --> PowerStencil::SystemEntityDefinitions::Plugin (template-template path: '/opt/rbenv/versions/2.3.1/lib/ruby/gems/2.3.0/gems/power_stencil-0.2.18/etc/templates/plugin_definition')
- - Type 'process_descriptor' --> PowerStencil::SystemEntityDefinitions::ProcessDescriptor
- - Type 'project_config' --> PowerStencil::SystemEntityDefinitions::ProjectConfig
- - Type 'simple_exec' --> PowerStencil::SystemEntityDefinitions::SimpleExec (template-template path: '/opt/rbenv/versions/2.3.1/lib/ruby/gems/2.3.0/gems/power_stencil-0.2.18/etc/templates/simple_exec')
+ - Type 'base_entity' --> PowerStencil::SystemEntityDefinitions::ProjectEntity (provided by 'PowerStencil core')
+ - Type 'entity_override' --> UniverseCompiler::Entity::Override (provided by 'PowerStencil core')
+ - Type 'plugin_definition' --> PowerStencil::SystemEntityDefinitions::Plugin (provided by 'PowerStencil core') template-template path: '/opt/rbenv/versions/2.3.1/lib/ruby/gems/2.3.0/gems/power_stencil-0.6.1/etc/templates/plugin_definition'
+ - Type 'process_descriptor' --> PowerStencil::SystemEntityDefinitions::ProcessDescriptor (provided by 'PowerStencil core')
+ - Type 'project_config' --> PowerStencil::SystemEntityDefinitions::ProjectConfig (provided by 'PowerStencil core')
+ - Type 'simple_exec' --> PowerStencil::SystemEntityDefinitions::SimpleExec (provided by 'PowerStencil core') template-template path: '/opt/rbenv/versions/2.3.1/lib/ruby/gems/2.3.0/gems/power_stencil-0.6.1/etc/templates/simple_exec'
 ```
 
 It provides a lot of information about the project, but let's focus on the `Entities` and `Available entity types` parts of the report.
@@ -178,20 +178,23 @@ We have seen the `power_stencil info` returns (among other) the number of entiti
 $ power_stencil check                                  
 RAW ENTITIES
  'base_entity/my_1st_entity':
-  - Storage path: '/tmp/tst2/.ps_project/entities/base_entity/my_1st_entity.yaml'
-  - Status      : Valid 
-  - Buildable   : false
+  - Storage path   : '/tmp/tst2/.ps_project/entities/base_entity/my_1st_entity.yaml'
+  - Provided by    : 'PowerStencil core'
+  - Status         : Valid
+  - Buildable      : false
  'base_entity/my_2nd_entity':
-  - Storage path: '/tmp/tst2/.ps_project/entities/base_entity/my_2nd_entity.yaml'
-  - Status      : Valid 
-  - Buildable   : false
+  - Storage path   : '/tmp/tst2/.ps_project/entities/base_entity/my_2nd_entity.yaml'
+  - Provided by    : 'PowerStencil core'
+  - Status         : Valid
+  - Buildable      : false
  'project_config/Project Config':
-  - Storage path: ''
-  - Status      : Valid 
-  - Buildable   : false
+  - Storage path   : ''
+  - Provided by    : 'PowerStencil core'
+  - Status         : Valid
+  - Buildable      : false
 ```
 
-The goal of this command is normally to check the validity of entities, but it brings as well extra information like if the entity is _buildable_ or even where it is stored in the repository.
+The goal of this command is normally to check the validity of entities, but it brings as well extra information like if the entity is _buildable_ or even where it is stored in the repository or if is provided by the core system (PowerStencil core) or a plugin.
 
 :information_source: You can notice that the `project_config` entity has no storage path, the reason being [it is not persisted](#default-entity-types) in the entities repository (its content actually comes from config files outside of the repository).
 
@@ -203,13 +206,15 @@ By default `power_stencil check` will check all entities in the repository but y
 $ power_stencil check base_entity/my_1st_entity 'project_config/Project Config'
 RAW ENTITIES
  'base_entity/my_1st_entity':
-  - Storage path: '/tmp/tst2/.ps_project/entities/base_entity/my_1st_entity.yaml'
-  - Status      : Valid 
-  - Buildable   : false
+  - Storage path   : '/tmp/tst2/.ps_project/entities/base_entity/my_1st_entity.yaml'
+  - Provided by    : 'PowerStencil core'
+  - Status         : Valid
+  - Buildable      : false
  'project_config/Project Config':
-  - Storage path: ''
-  - Status      : Valid 
-  - Buildable   : false
+  - Storage path   : ''
+  - Provided by    : 'PowerStencil core'
+  - Status         : Valid
+  - Buildable      : false
 ```
 Another possibility is to check a list of objects using a regular expression (applied to the ID of an entity, ie `<entity_type</<entity_name>`) by using the `--regexp` option:
 
@@ -217,13 +222,15 @@ Another possibility is to check a list of objects using a regular expression (ap
 $ power_stencil check base_ --regexp
 RAW ENTITIES
  'base_entity/my_1st_entity':
-  - Storage path: '/tmp/tst2/.ps_project/entities/base_entity/my_1st_entity.yaml'
-  - Status      : Valid 
-  - Buildable   : false
+  - Storage path   : '/tmp/tst2/.ps_project/entities/base_entity/my_1st_entity.yaml'
+  - Provided by    : 'PowerStencil core'
+  - Status         : Valid
+  - Buildable      : false
  'base_entity/my_2nd_entity':
-  - Storage path: '/tmp/tst2/.ps_project/entities/base_entity/my_2nd_entity.yaml'
-  - Status      : Valid 
-  - Buildable   : false
+  - Storage path   : '/tmp/tst2/.ps_project/entities/base_entity/my_2nd_entity.yaml'
+  - Provided by    : 'PowerStencil core'
+  - Status         : Valid
+  - Buildable      : false
 ```
 
 ## Querying and graphing entities
@@ -336,9 +343,10 @@ Created 'base_entity/dev_entity'
 $ power_stencil check base_entity/dev_entity
 RAW ENTITIES
  'base_entity/dev_entity':
-  - Storage path: '/tmp/tst2/.ps_project/user_entities/base_entity/dev_entity.yaml'
-  - Status      : Valid 
-  - Buildable   : false
+  - Storage path   : '/tmp/tst2/.ps_project/user_entities/base_entity/dev_entity.yaml'
+  - Provided by    : 'PowerStencil core'
+  - Status         : Valid
+  - Buildable      : false
 ```
 You can notice where the YAML file has been created.
 
@@ -487,13 +495,13 @@ $ power_stencil info
     .
 --------------------------------------------------------------------------------
  Available entity types:
- - Type 'base_entity' --> PowerStencil::SystemEntityDefinitions::ProjectEntity
+ - Type 'base_entity' --> PowerStencil::SystemEntityDefinitions::ProjectEntity (provided by 'PowerStencil core')
  - Type 'custom_entity' --> MyCustomEntity
- - Type 'entity_override' --> UniverseCompiler::Entity::Override
- - Type 'plugin_definition' --> PowerStencil::SystemEntityDefinitions::Plugin (template-template path: '/opt/rbenv/versions/2.3.1/lib/ruby/gems/2.3.0/gems/power_stencil-0.2.18/etc/templates/plugin_definition')
- - Type 'process_descriptor' --> PowerStencil::SystemEntityDefinitions::ProcessDescriptor
- - Type 'project_config' --> PowerStencil::SystemEntityDefinitions::ProjectConfig
- - Type 'simple_exec' --> PowerStencil::SystemEntityDefinitions::SimpleExec (template-template path: '/opt/rbenv/versions/2.3.1/lib/ruby/gems/2.3.0/gems/power_stencil-0.2.18/etc/templates/simple_exec')
+ - Type 'entity_override' --> UniverseCompiler::Entity::Override (provided by 'PowerStencil core')
+ - Type 'plugin_definition' --> PowerStencil::SystemEntityDefinitions::Plugin (provided by 'PowerStencil core') template-template path: '/opt/rbenv/versions/2.3.1/lib/ruby/gems/2.3.0/gems/power_stencil-0.6.1/etc/templates/plugin_definition'
+ - Type 'process_descriptor' --> PowerStencil::SystemEntityDefinitions::ProcessDescriptor (provided by 'PowerStencil core')
+ - Type 'project_config' --> PowerStencil::SystemEntityDefinitions::ProjectConfig (provided by 'PowerStencil core')
+ - Type 'simple_exec' --> PowerStencil::SystemEntityDefinitions::SimpleExec (provided by 'PowerStencil core') template-template path: '/opt/rbenv/versions/2.3.1/lib/ruby/gems/2.3.0/gems/power_stencil-0.6.1/etc/templates/simple_exec'
 ```
 You see that the `custom_entity` type appeared in the list. Need another proof ?
 ```shell
@@ -503,9 +511,10 @@ Created 'custom_entity/my_1st_custom_entity'
 $ power_stencil check cust -r
 RAW ENTITIES
  'custom_entity/my_1st_custom_entity':
-  - Storage path: '/tmp/tst2/.ps_project/entities/custom_entity/my_1st_custom_entity.yaml'
-  - Status      : Valid 
-  - Buildable   : false
+  - Storage path   : '/tmp/tst2/.ps_project/entities/custom_entity/my_1st_custom_entity.yaml'
+  - Provided by    : 'PowerStencil core'
+  - Status         : Valid
+  - Buildable      : false
 
 $ power_stencil get custom_entity/my_1st_custom_entity --raw
 --- !ruby/object:MyCustomEntity

data/doc/plugins.md

@@ -15,6 +15,7 @@ Plugins
     - [Providing entity types and templates](#providing-entity-types-and-templates)
     - [Providing custom build process](#providing-custom-build-process)
 - [Plugin capabilities and structure](#plugin-capabilities-and-structure)
+- [Using plugins available as gems](#using-plugins-available-as-gems)
 - [Conclusion](#conclusion)
 
 <!-- /TOC -->
@@ -97,7 +98,7 @@ If you do a `power_stencil info` you see a new part appeared in the report
    - command_line: true
    - processors: true
    - build: true
-   - dsl: false
+   - dsl: true
    - entity_definitions: true
    - templates: true
 ```
@@ -123,7 +124,7 @@ Or with the capabilities information:
    command_line: true
    processors: true
    build: true
-   dsl: false
+   dsl: true
    entity_definitions: true
    templates: true
 ```
@@ -205,6 +206,7 @@ we can check using `power_stencil check myplugin_entity/test`:
 $ power_stencil check myplugin_entity/test
  'myplugin_entity/test':
   - Storage path   : '/tmp/demo/.ps_project/entities/myplugin_entity/test.yaml'
+  - Provided by    : plugin 'myplugin'
   - Templates path : '/tmp/demo/myplugin_entity/test'
   - Status         : Valid 
   - Buildable      : true
@@ -336,7 +338,8 @@ But this is not mandatory. Actually the only mandatory file for a plugin to be v
 :build: post_build_hook
 
 # If a dsl module is declared it will be injected in the DSL available in the shell or templates
-:dsl: null
+:dsl:
+ - Myplugin::Dsl::MypluginDsl
 
 # These are the files (array) defining entity types. These files should not be already 
 # required by the plugin as they will be required by the framework when needed.
@@ -349,7 +352,11 @@ But this is not mandatory. Actually the only mandatory file for a plugin to be v
   - etc/templates
 ```
 
-As it is quite self-documented, I won't too much elaborate on the meaning of each of the fields. But actually a plugin can actually provide ... nothing.
+As it is quite self-documented, I won't too much elaborate on the meaning of each of the fields.
+
+So you see that the plugin generated by the `power_stencil plugin --create` command is actually fully featured, providing all possible extras, in order to demonstrate the possibilities as well as ease your job, as you just have to fill the blanks or remove things you don't wan't.create
+
+But a plugin could also actually provide ... nothing.
 
 Let's create a plugin fully manually instead of using the `power_stencil plugin --create`. From the root of the project, let's create the directory:
 
@@ -375,7 +382,7 @@ Bam ! We just created a more than useless yet valid plugin ! You can check that
    - command_line: false
    - processors: false
    - build: false
-   - dsl: false
+   - dsl: true
    - entity_definitions: false
    - templates: false
 ```
@@ -421,12 +428,58 @@ MinimalPlugin::Minimal:
 
 All of this to demonstrate that a plugin can be almost anything, even something very minimalistic, but nevertheless you should keep on using the `power_stencil plugin --create` command and benefit from the structure it brings, as well as the possibility to become a stand-alone plugin gem...
 
+# Using plugins available as gems
+
+Any plugin you have created using the `power_stencil plugin --create` command is directly eligible to become a gem.
+
+**If you release a plugin you created within a project as a gem (by doing `bundle exec rake release` from within the plugin directory, like for any standard gem :+1:), you can then re-use your plugin from any other `PowerStencil` project !**
+
+All you have to do for that is to declare it in the `.ps_project/versioned-config.yaml` config file by adding an array `:project_plugins`:
+
+```yaml
+...
+:project_plugins:
+  - my_awesome_plugin1
+  - my_awesome_plugin2
+  - my_awesome_plugin3
+...
+```
+
+Now if you try to run power_stencil you may face an error if the gem is not locally installed:
+
+```
+▶ power_stencil info
+--------------------------------------------------------------------------------
+PROJECT REPORT
+--------------------------------------------------------------------------------
+ General information:
+Program aborted with message: 'Cannot find plugin 'my_awesome_plugin1'. Try 'power_stencil plugin --install''.
+  Use --debug option for more detail (see --help).
+
+```
+Here you have the choice to either manually install each of your plugins manually by using the regular gem program:
+
+    $ gem install my_awesome_plugin1 my_awesome_plugin2 my_awesome_plugin3
+
+But `PowerStencil` provides a convenient command to install/update your plugins:
+
+```
+$ power_stencil plugin --install
+Fetching: my_awesome_plugin1-0.1.0.gem (100%)
+Fetching: my_awesome_plugin2-0.1.1.gem (100%)
+Fetching: my_awesome_plugin3-1.2.3.gem (100%)
+Installed plugin 'my_awesome_plugin1' (version: 0.1.0)
+Installed plugin 'my_awesome_plugin2' (version: 0.1.1)
+Installed plugin 'my_awesome_plugin3' (version: 1.2.3)
+```
+
+**:star2: ::+1: You can now verify using `power_stencil info` or `power_stencil plugin --list`, that the plugins have been installed and that any feature they provide is now available to your project.**
 
 # Conclusion
 
 The documentation for plugins is not fully complete, so you are encouraged to read the code. Some official plugins are under development, and the documentation will be improved along their development...
 
-**:warning: As opposed to the rest of `PowerStencil`, the functionnality is nevertheless not completely frozen. This will be the case once `PowerStencil` turns 1.0.0.** Yet now _local_ plugins are almost in their final stage. Gem plugins will soon be released and then `PowerStencil` will turn 1.0.0.
+**:warning: As opposed to the rest of `PowerStencil`, the functionnality is nevertheless not completely frozen. This will be the case once `PowerStencil` turns 1.0.0.** but plugins are close to their final release, and anything above version 0.6 is already really usable.
 
 
 [:back:][Documentation root]

data/doc/templates.md

@@ -43,6 +43,7 @@ $ power_stencil check simple_exec/demo_templates
 RAW ENTITIES
  'simple_exec/demo_templates':
   - Storage path   : '/tmp/tst3/.ps_project/entities/simple_exec/demo_templates.yaml'
+  - Provided by    : 'PowerStencil core'
   - Templates path : '/tmp/tst3/simple_exec/demo_templates'
   - Status         : Valid 
   - Buildable      : true

data/etc/base_commands_definition.yml

@@ -104,13 +104,26 @@
     :options:
       create:
         :type: bool
-        :summary: Generates a fully working although useless plugin skeleton.
+        :summary: Scaffolds a fully working plugin skeleton.
         :long_aliases:
           - new
           - scaffold
+        :incompatibilities:
+          - list
+          - install
       list:
         :type: bool
         :summary: List currently used plugins in this project.
+        :incompatibilities:
+          - create
+          - install
+      install:
+        :type: bool
+        :summary: Install gem plugins.
+        :incompatibilities:
+          - create
+          - list
+
   get:
     :banner: |
       Query entities from repository.

data/etc/meta_templates/plugin_seed/etc/plugin_capabilities.yaml

@@ -19,7 +19,8 @@
 :build: post_build_hook
 
 # If a dsl module is declared it will be injected in the DSL available in the shell or templates
-:dsl: null
+:dsl:
+  - <%= plugin_module_name %>::Dsl::<%= plugin_module_name %>Dsl
 
 # These are the files (array) defining entity types. These files should not be already 
 # required by the plugin as they will be required by the framework when needed.

data/etc/meta_templates/plugin_seed/psplugin_{entity}.gemspec

@@ -18,8 +18,10 @@ Gem::Specification.new do |spec|
   # to allow pushing to a single host or delete this section to allow pushing to any host.
   if spec.respond_to?(:metadata)
     spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
+    # This metadata is mandatory for PowerStencil !!
+    spec.metadata['plugin_name'] = '<%= plugin_name %>'
   else
-    raise 'RubyGems 2.0 or newer is required to protect against public gem pushes.'
+    raise 'RubyGems 2.0 or newer is required to protect against public gem pushes and PowerStencil plugin mechanism !'
   end
 
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|

data/etc/templates/plugin_definition/etc/plugin_capabilities.yaml

@@ -19,7 +19,8 @@
 :build: post_build_hook
 
 # If a dsl module is declared it will be injected in the DSL available in the shell or templates
-:dsl: null
+:dsl:
+  - <%= plugin_module_name %>::Dsl::<%= plugin_module_name %>Dsl
 
 # These are the files (array) defining entity types. These files should not be already 
 # required by the plugin as they will be required by the framework when needed.

data/etc/templates/plugin_definition/psplugin_{entity}.gemspec

@@ -18,8 +18,10 @@ Gem::Specification.new do |spec|
   # to allow pushing to a single host or delete this section to allow pushing to any host.
   if spec.respond_to?(:metadata)
     spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
+    # This metadata is mandatory for PowerStencil !!
+    spec.metadata['plugin_name'] = '<%= plugin_name %>'
   else
-    raise 'RubyGems 2.0 or newer is required to protect against public gem pushes.'
+    raise 'RubyGems 2.0 or newer is required to protect against public gem pushes and PowerStencil plugin mechanism !'
   end
 
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|

data/lib/power_stencil/command_processors/build.rb

@@ -15,8 +15,21 @@ module PowerStencil
         if config[:'supported-builds']
           project.engine.available_entities_hash.select do |_, klass|
             klass.respond_to?(:buildable?) and klass.buildable?
-          end .each do |entity_type, _|
-            puts " - '#{entity_type}'"
+          end .each do |entity_type, entity_class|
+            builder = entity_class.buildable_by.empty? ? "'#{PowerStencil.name}'" : "plugin '#{entity_class.buildable_by}'"
+
+            source_provider = entity_class.entity_type_source_provider
+            source_provider_display = if source_provider == PowerStencil
+                                        "'#{source_provider.name}'"
+                                      elsif source_provider == project
+                                        "project '#{source_provider.name}'"
+                                      elsif source_provider.is_a? PowerStencil::Plugins::Base
+                                        "plugin '#{source_provider.name}'"
+                                      else
+                                        raise PowerStencil::Error, "Unidentified source provider for #{entity_class} !"
+                                      end
+
+            puts " - '#{entity_type}' (buildable by #{builder} and provided by #{source_provider_display})."
           end
           return
         end
@@ -37,7 +50,7 @@ module PowerStencil
           if entity_report == ['Ok']
             puts " - '#{entity_full_name}' has been correctly built"
           else
-            puts " - Failed to build '#{entity_full_name}' because ", entity_report
+            puts_and_logs " - Failed to build '#{entity_full_name}' because #{entity_report.join}", logs_as: :error, check_verbose: false
           end
         end
 

data/lib/power_stencil/command_processors/check.rb

@@ -23,6 +23,18 @@ module PowerStencil
         sorted_targets.map do |entity|
           entity_info = [" '#{entity.as_path}':"]
           entity_info << "  - Storage path   : '#{entity.source_uri}'"
+
+          source_provider = entity.class.entity_type_source_provider
+          source_provider_display = if source_provider == PowerStencil
+                                      "'#{source_provider.name}'"
+                                    elsif source_provider == project
+                                      "project '#{source_provider.name}'"
+                                    elsif source_provider.is_a? PowerStencil::Plugins::Base
+                                      "plugin '#{source_provider.name}'"
+                                    else
+                                      raise PowerStencil::Error, "Unidentified source provider for #{entity.class} !"
+                                    end
+          entity_info << "  - Provided by    : #{source_provider_display}"
           entity_info << "  - Templates path : '#{entity.templates_path}'" if entity.respond_to? :templates_path
           entity_info << "  - Status         : #{entity.valid? ? 'Valid' : 'INVALID !'} "
           entity_info << "  - Buildable      : #{entity.buildable?}"