power_stencil 0.5.1 → 0.7.0

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 -->
@@ -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
@@ -426,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

@@ -27,7 +27,7 @@ The default templating engine being [ERB], your templates should be written usin
 
 Templates are always associated to some [buildable entities][buildable].
 
-When a [buildable entity][buildable] has some templates associated, they will be located in a directory `<entity_type>/<entity_name>/`. For some entity types, when you will create a new entity of this type, some default templates will be created in that directory (this is the case of the `simple_exec` entity type as you will see in the next paragraph). This is what is called `templates-templates`.
+When a [buildable entity][buildable] has some templates associated, they will be initially generated in a directory `templates/<entity_type>/<entity_name>/` (unless they are [unversioned]). For some entity types, when you will create a new entity of this type, some default templates will be created in that directory (this is the case of the `simple_exec` entity type as you will see in the next paragraph) from some kind of "_meta-templates_". This is what is called `templates-templates` in `PowerStencil`.
 
 In this document, you will learn how to create your own templates, as well as your own templates-templates.
 
@@ -37,19 +37,21 @@ In the basic entity types, the only one providing default templates is the `simp
 
 ```shell
 $ power_stencil create simple_exec/demo_templates 
-Created 'simple_exec/demo_templates'
+Creating 'simple_exec/demo_templates'...
+Generated templates in '/tmp/tst3/templates/simple_exec/demo_templates'.
 
 $ 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'
-  - Templates path : '/tmp/tst3/simple_exec/demo_templates'
+  - Provided by    : 'PowerStencil core'
+  - Templates path : '/tmp/tst3/templates/simple_exec/demo_templates'
   - Status         : Valid 
   - Buildable      : true
 ```
 As you can see the output of `power_stencil check` shows more information than entities we created so far. First we see that this entity is `buildable`, and we'll detail that in the [builds] document, but for the moment what we will focus on the `Templates path` information.
 
-And it's true if we have a look in the `simple_exec/demo_templates/` directory from the root of the project, a file appeared there:
+And it's true if we have a look in the `templates/simple_exec/demo_templates/` directory from the root of the project, a file appeared there:
 
 ```shell
 $ ls -l simple_exec/demo_templates
@@ -78,14 +80,14 @@ End of process 15572
 
 What can we see there ? 
 
-The first line is the most interesting one for us. It says "De-templating ... into ...", and it's true that a brand new directory named `build` appeared at the root of the project. Again we won't focus too much on the name of the sub-directory as we will see that in the [builds], but if we have a look in the generated directory we see the same content as what we had in `simple_exec/demo_templates`... 
+The first line is the most interesting one for us. It says "De-templating ... into ...", and it's true that a brand new directory named `build` appeared at the root of the project. Again we won't focus too much on the name of the sub-directory as we will see that in the [builds], but if we have a look in the generated directory we see the same content as what we had in `templates/simple_exec/demo_templates`... 
 And by the way the generated script seems to have been run, as we can see in the output.
 
 :warning: If bash is not installed on your system, the output will obviously be different as `PowerStencil` won't be able to run the script, yet all the files should have been generated correctly.
 
-Ok is it possible, that everything inside `simple_exec/demo_templates` is actually considered as templates ? **The answer is yes !!**
+Ok is it possible, that everything inside `templates/simple_exec/demo_templates` is actually considered as templates ? **The answer is yes !!**
 
-Let prove it and replace the content of `simple_exec/demo_templates/main.sh` by the following:
+Let prove it and replace the content of `templates/simple_exec/demo_templates/main.sh` by the following:
 
 ```shell
 #!/usr/bin/env bash
@@ -122,7 +124,7 @@ echo "It was done in the scope of 'demo_templates' (which is of the type 'simple
 
 The content has been "de-templated"... :+1: sooo cool !
 
-:information_source: Here the template directory of the `simple_exec/demo_templates` was containing only on file (the bash script), but **any file in any sub-directory of that directory would have been considered as a template** (yet there are some mechanism to control and limit which files have to be processed, like for example imagine there would be images, or zip files, probably you don't want them to be processed. All of this will be covered in the [builds] document).
+:information_source: Here the template directory of the `simple_exec/demo_templates` entity was containing only on file (the bash script), but **any file in any sub-directory of that directory would have been considered as a template** (yet there are some mechanism to control and limit which files have to be processed, like for example imagine there would be images, or zip files, probably you don't want them to be processed. All of this will be covered in the [builds] document).
 
 # What can I do within templates ?
 
@@ -175,7 +177,7 @@ This should be self explanatory, there is another part that could be displayed i
 
 # Where do I create templates ?
 
-**When an entity is [buildable] you can find its templates in the `<entity_type>/<entity_name>` from the root of the project.** 
+**When an entity is [buildable] you can find its templates in the `templates/<entity_type>/<entity_name>` from the root of the project.** 
 
 But by default, that directory is not created, and if no templates is created at this place for a [buildable] entity, the build will fail saying it didn't find any template...
 
@@ -188,7 +190,7 @@ $ power_stencil info
     .
     .
     .
- - 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 '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.3/etc/templates/simple_exec'
 ```
 
 `simple_exec` is an entity type coming with `PowerStencil`, and you can see that it takes its _template-template_ from within the `PowerStencil` gem itself !
@@ -199,7 +201,7 @@ To summarize about templates and _templates-templates_:
 
 ![entity-creation-flow]
 
-:information_source: There is actually a third place where you could find entity types and _templates-templates_, this is within [plugins], but we will cover that in the [plugins] part...
+:information_source: As you can see, there is actually a third place where you could find entity types and _templates-templates_, this is within [plugins], but we will cover that in the [plugins] part...
 
 # Creating templates-templates of your own
 
@@ -230,20 +232,21 @@ Let's now create an entity of this type:
 
 ```shell
 $ power_stencil create custom_buildable_entity/test1
-Created 'custom_buildable_entity/test1'
+Creating 'custom_buildable_entity/test1'...
+Generated templates in '/tmp/tst3/templates/custom_buildable_entity/test1'.
 
-$ ll custom_buildable_entity/test1 
+$ ll templates/custom_buildable_entity/test1 
 total 12
 drwxrwxr-x 2 laurent laurent 4096 août  26 13:40 ./
 drwxrwxr-x 3 laurent laurent 4096 août  26 13:40 ../
 -rw-rw-r-- 1 laurent laurent   26 août  26 13:40 a_useless_text_file.txt
 ```
-Everything, seems ok. The entity `custom_buildable_entity/test1` has been created and there is now a new folder at the root of the project named `custom_buildable_entity/test1` and which content is a text file named `a_useless_text_file.txt`... So far so good.
+Everything, seems ok. The entity `custom_buildable_entity/test1` has been created and there is now a new folder named `templates/custom_buildable_entity/test1` and which content is a text file named `a_useless_text_file.txt`... So far so good.
 
 And what is the content of this file ?
 
 ```shell
-$ cat custom_buildable_entity/test1/a_useless_text_file.txt
+$ cat templates/custom_buildable_entity/test1/a_useless_text_file.txt
 This text has been generated on the 2019-08-26 13:50:35 +0200
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit,
@@ -308,15 +311,16 @@ Et voilà, let's verify:
 
 ```shell
 $ power_stencil create custom_buildable_entity/test2
-Created 'custom_buildable_entity/test2'
+Creating 'custom_buildable_entity/test2'...
+Generated templates in '/tmp/tst3/templates/custom_buildable_entity/test2'.
 
-$ ls -la custom_buildable_entity/test2 
+$ ls -la templates/custom_buildable_entity/test2 
 total 12
 drwxrwxr-x 2 laurent laurent 4096 août  26 18:37 .
 drwxrwxr-x 4 laurent laurent 4096 août  26 18:37 ..
 -rw-rw-r-- 1 laurent laurent  148 août  26 18:37 a_useless_text_file.txt
 
-$ cat custom_buildable_entity/test2/a_useless_text_file.txt 
+$ cat templates/custom_buildable_entity/test2/a_useless_text_file.txt 
 This text has been generated on the <%= Time.now %>
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit,
@@ -351,6 +355,7 @@ Flawless victory !!
 [buildable]: entities.md#buildable-and-buildable_by "How to make an entity buildable ?"
 [entity field]: entities.md#field "How to access basic entity data"
 [reverse methods]: entities.md#has_one "Check reverse methods"
+[unversioned]: entities.md#local-unversioned-entities "Unversioned/developer entities"
 <!-- Code links -->
 
 

data/etc/base_commands_definition.yml

@@ -85,6 +85,12 @@
         :summary: Forces creation in an already existing directory.
         :short_aliases:
           - f
+      no-git:
+        :type: bool
+        :summary: Do not initiate a git repo when creating a new project.
+        :long_aliases:
+          - ng
+          - nogit
   info:
     :banner: |
       Generic information about the repository.
@@ -104,13 +110,34 @@
     :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
+      no-git:
+        :type: bool
+        :summary: Do not include the newly created plugin into the repository.
+        :long_aliases:
+          - ng
+          - nogit
+        :dependencies:
+          - create
+
   get:
     :banner: |
       Query entities from repository.

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/power_stencil.yaml

@@ -23,7 +23,7 @@
 :unversioned_user_project_config_file_name: personal-config.yaml
 # Entity definitions specific to the project
 :project_entity_definitions_directory_name: entity_definitions
-# Templates specific to the project
+# Templates templates specific to the project
 :project_templates_directory_name: templates-templates
 # Directory name where entities are stored
 :project_entities_directory_name: entities
@@ -33,6 +33,10 @@
 :project_plugins_directory_name: plugins
 # Root directory where builds are generated
 :project_build_root_directory_name: build
+# Versioned entities templates directory
+:versioned_entities_templates_directory_name: templates
+# Unversioned entities templates directory
+:unversioned_user_entities_templates_directory_name: unversioned-templates
 # Last build link name
 :project_build_last_stable_path: last_build
 # Previous build link name
@@ -108,4 +112,6 @@
 :log-level: 2
 # Maximum number of retries when editing a file
 :max_file_edit_retry_times: 3
+# Integration with git
+:no-git: false
 

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/etc/templates/project/.zzzgitignore.erb

@@ -1,6 +1,11 @@
 # Ignore power stencil generated files
-<%= File.join '', project_config[:project_build_root_directory_name]  %>
+<%= File.join '', project_config[:project_build_root_directory_name] %>
+
 # Ignore power stencil local entities created by developer
-<%= File.join '', project_config[:default_config_directory_name], project_config[:user_entities_directory_name]  %>
+<%= File.join '', project_config[:default_config_directory_name], project_config[:user_entities_directory_name] %>
+
+# Ignore power stencil local entities templates created by developer
+<%= File.join '', project_config[:unversioned_user_entities_templates_directory_name] %>
+
 # Ignore power stencil local developer's config
-<%= File.join '', project_config[:default_config_directory_name], project_config[:unversioned_user_project_config_file_name]  %>
+<%= File.join '', project_config[:default_config_directory_name], project_config[:unversioned_user_project_config_file_name] %>

data/lib/power_stencil.rb

@@ -1,6 +1,7 @@
 require 'power_stencil/version'
 
 require 'universe_compiler'
+require 'git'
 require 'dir_glob_ignore'
 
 $DO_NOT_AUTOSTART_CLIMATIC=true

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?}"

data/lib/power_stencil/command_processors/create.rb

@@ -12,7 +12,7 @@ module PowerStencil
       def execute
         analyse_extra_params.each do |search_criterion|
           begin
-            puts_and_logs "Creating new entity '#{search_criterion.as_path}'"
+            puts_and_logs "Creating new entity '#{search_criterion.as_path}'...", check_verbose: false
             entity_as_hash = {name: search_criterion.name}
             unless config[:property].nil?
               config[:property].each do |property_def|
@@ -36,11 +36,12 @@ module PowerStencil
             end
 
             new_entity.valid? raise_error: true
-            new_entity.save
-
-            puts "Created '#{new_entity.as_path}'"
+            project.track_action_with_git("Created '#{new_entity.as_path}' (and potential dependencies).") do
+              new_entity.save
+            end
+            puts_and_logs "Generated templates in '#{new_entity.templates_path}'.", check_verbose: false if new_entity.buildable?
           rescue => e
-            puts "Failed to create '#{search_criterion.as_path}' with message '#{e.message}'."
+            puts_and_logs "Failed to create '#{search_criterion.as_path}' with message '#{e.message}'.", logs_as: :error, check_verbose: false
             logger.debug PowerStencil::Error.report_error(e)
           end
         end

data/lib/power_stencil/command_processors/delete.rb

@@ -9,24 +9,32 @@ module PowerStencil
       include PowerStencil::CommandProcessors::EntityHelper
 
       def execute
-        analyse_extra_params.each do |search_criterion|
+        targets = targets_from_criteria analyse_extra_params, project.engine.root_universe
+        targets.each do |target|
           begin
-            unless project.engine.entity *search_criterion.to_a, project.engine.root_universe
-              puts "Skipping '#{search_criterion.as_path}'. Entity not found."
-              next
-            end
-            puts_and_logs "Deleting entity '#{search_criterion.as_path}'"
-            if project.engine.delete_entity project.engine.root_universe,
-                                            *search_criterion.to_a,
-                                            delete_files: config[:'delete-files']
-              msg = "Deleted '#{search_criterion.as_path}'"
-              msg << ' and associated files.' if config[:'delete-files']
-              puts msg
-            else
-              puts 'Cancelled by user input.'
+            # unless project.engine.entity *target.to_a, project.engine.root_universe
+            #   puts_and_logs "Skipping '#{target.as_path}'. Entity not found.", check_verbose: false
+            #   next
+            # end
+            puts_and_logs "Deleting entity '#{target.as_path}'", check_verbose: false
+
+            msg = "Deleted entity '#{target.as_path}' (and potential dependencies)"
+            msg << ' including templates.' if config[:'delete-files']
+            msg << '.'
+            project.track_action_with_git(msg) do
+              if project.engine.delete_entity project.engine.root_universe,
+                                              target.type,
+                                              target.name,
+                                              delete_files: config[:'delete-files']
+                msg = "Deleted '#{target.as_path}'"
+                msg << ' and template files.' if config[:'delete-files']
+                puts_and_logs msg, check_verbose: false
+              else
+                puts_and_logs 'Cancelled by user input.', check_verbose: false
+              end
             end
           rescue => e
-            puts "Failed to delete '#{search_criterion.as_path}' with message '#{e.message}'."
+            puts_and_logs "Failed to delete '#{target.as_path}' with message '#{e.message}'.", logs_as: :error, check_verbose: false
             logger.debug PowerStencil::Error.report_error(e)
           end
         end