power_stencil 0.3.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2919b7c8587ab13f5df85a63bcf280c0c77402e0
+  data.tar.gz: 2bb5e955ddebbabd4abd47276d16afb4ecede82d
+SHA512:
+  metadata.gz: 0d8992f40f5a6638a7e453528806d40e18d122ed347f251c7ab82712036b95977712c3c8c8352f48d4221dc96a437d5eb1ce197a387646008e7677db16f62a9e
+  data.tar.gz: 658a06ca8cdbedcda1ebfea8dda9881baaa74ccfac5ba706f579bf8e6c2debd58a7be91b3bf320687eae3f032a6c9ad51eec95bdb9aebcdcc8972db7f6c4c3ad

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/pkg/
+/spec/reports/
+/tmp/
+/etc/templates/plugin_definition-*.old/
+# rspec failure tracking
+.rspec_status
+/.idea/
+/test/test_project/build/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.1
+before_install: gem install bundler -v 1.15.1

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at lbnetid+gh@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in power_stencil.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Laurent B.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,198 @@
+PowerStencil
+============
+
+`Power Stencil` is the Swiss-army knife templating workflow for developers and ops.
+
+<!-- TOC -->
+
+- [Core concepts](#core-concepts)
+- [Pfff, yet another templating engine...](#pfff-yet-another-templating-engine)
+- [Installation](#installation)
+- [Usage](#usage)
+    - [Help](#help)
+    - [Creating a `PowerStencil` project](#creating-a-powerstencil-project)
+    - [`PowerStencil` project structure](#powerstencil-project-structure)
+    - [Getting started](#getting-started)
+- [Contributing](#contributing)
+    - [License](#license)
+    - [Code of Conduct](#code-of-conduct)
+
+<!-- /TOC -->
+
+# Core concepts
+
+`PowerStencil` proposes a radical approach on how to manage your shared configuration.
+
+Internally `PowerStencil` is composed of a data repository and a pretty standard templating flow to generate whatever is needed by your project or organization:
+
+![simple-flow-image]
+
+Configuration is one of the most complex things to maintain, and anyone who participated in a large scale piece of software or documentation knows how complex it is to maintain, keep consistent and avoid duplication on the long run across the various projects that may share this configuration.
+
+`PowerStencil` provides **development and operations friendly workflows to fully manage the maintenance of a complex shared config** in order to generate anything you may want like _documentation_, _static sites_, _code_, _configuration_ for multiple tools..., while **avoiding duplication, and manage it like code** !
+
+It is a common pattern to introduce a database to manage this configuration, and it is a very bad idea because it implies extra tooling, and specific developments that de-facto become single point of failure at the heart of your development process. Why would you do that when something as versatile and ubiquitous as Git exists that will __integrate smoothly within your existing development and operations workflows__, builds, CI/CD, while benefiting from all the goodness provided by Git, like branches, decentralization, versioning, tags, code reviews, traceability, simplified fallbacks etc... ?
+
+**With `PowerStencil` everything is maintained in a git repository**: data, templates, specific code. No more config loss, no more change applied without a full lineage.
+
+See some real world [example use cases].
+
+The `PowerStencil` gem provides the `power_stencil` executable which is a pluggable CLI to:
+
+- CRUD [entities] using either an editor or a dedicated REPL
+- Manage [templates]
+- Manage [builds]
+- Create and manipulate [plugins]
+
+# Pfff, yet another templating engine...
+
+**Actually `PowerStencil` is _not_ a templating engine** per se. Instead it uses already existing and proven templating engines.
+Currently it uses [ERB], which is pretty standard in [Ruby] world, but this is not hardcoded and any templating engine could be used (in parallel, meaning different templating engines can be used automatically depending on what you actually want to generate), even if only [ERB] is implemented for the time-being, `PowerStencil` is modular from ground-up and at least a second implementation for [Haml] templating engine is planned to ease generation of XML-like files, still currently you can do it with [ERB]. See the [templates] section for more information about templates in `PowerStencil`.
+
+No, the real value of `PowerStencil` is not really in its templating capabilities even if very powerful, but in the development flow it proposes around this templating mechanism for both development and/or operations teams, in the way you organize and trace the data which is the real asset, and in the way you can easily extend it to fit the particular needs of a project or organization.
+
+# Installation
+
+You need a working install of the [Ruby] language (>= 2.2).
+
+You can install the `PowerStencil` gem by issuing the usual:
+
+    $ gem install power_stencil
+
+# Usage
+
+## Help
+
+The `power_stencil` CLI provides a contextual help. You can start by:
+
+    $ power_stencil --help
+
+That will display a basic help:
+
+```shell
+This is power_stencil. A powerful templating engine.
+-- Options ---------------------------------------------------------------------
+    -v, --verbose  Displays extra runtime information.
+    -h, --help  Displays this help.
+    --program-version, -V, --version  Displays program version.
+    --simulate  Will not perform actual actions
+    --debug  Debug mode
+    --debug-on-err, --debug-on-stderr  Sends debugging to SDTERR
+    --log-level  Defines the level of logging (0 to 5)
+    --log-file  Specifies a file to log into
+    --truncate-log-file  Truncates the log file (appends by default)
+    --project-path  Specifies a startup path to use instead of '.'
+    --auto  Bypasses command-line confirmations to the user
+
+--------------------------------------------------------------------------------
+ Following subcommands exist too:
+ For more information you can always issue sub_command_name --help...
+--------------------------------------------------------------------------------
+ * init: Initializes a PowerStencil repository ...
+ * info: Generic information about the repository ...
+ * new-plugin: Generates the skeleton for a plugin ...
+ * get: Query entities from repository ...
+ * shell: Opens a shell to interact with entities ...
+ * check: Check repository entities consistency ...
+ * create: Creates entities in the repository ...
+ * edit: Edit entities from repository ...
+ * delete: Delete entities from repository ...
+ * build: Builds entities ...
+```
+
+The program uses the standard paradigm of sub-commands (à-la-git), and each can have its own options that you can check using:
+
+    $ power_stencil <subcommand> --help
+
+[Plugins] may bring extra subcommands and/or options, so depending on the project you are working in, the output of `--help` may differ...
+
+## Creating a `PowerStencil` project
+
+To create a new project, use the `init` sub-command. It works as you would expect. If you run it in an existing directory it will create the project here but you can specify the directory where you want the project to be created (the path will be created provided you have the rights on the filesystem):
+
+    $ power_stencil init --project-path /where/you/want
+
+The `--project-path` option can be applied to any sub-command, but à-la-git, once the project created if you are anywhere within the project tree, you don't need to specify the project path.
+
+:information_source: The rest of this documentation will assume you are at the root of this created project.
+
+## `PowerStencil` project structure
+
+The structure of a brand new `PowerStencil` project is the following:
+
+```
+├── .gitignore
+└── .ps_project
+    ├── entities
+    │   └── README.md
+    ├── entity_definitions
+    │   └── README.md
+    ├── personal-config.yaml
+    ├── plugins
+    ├── templates-templates
+    │   └── README.md
+    ├── user_entities
+    │   └── README.md
+    └── versioned-config.yaml
+```
+New directories will appear once you start some [builds] or when you will define [templates].
+
+Not all the files in this directory should be versioned, and this the reason why there is a preconfigured `.gitignore` at the root of the project.
+
+The project has two distinct config files. Keep the official project config in the `.ps_project/versioned-config.yaml` which, as its name suggest will be versioned. But any developer who wants to temporarily override some configuration should do it in the `.ps_project/personal-config.yaml` which is not be versioned. The content defined in the latter overrides the content of the official one. This is a clean way for anyone who wants to test something to safely do it locally without the risk to pollute the central repo.
+
+There is the same mechanism between `.ps_project/entities` and `.ps_project/user_entities`, but as opposed to the two aforementioned config files you should not edit anything directly there, but instead interact using the CLI. More information on how to manage entities [here][entities].
+
+The `plugins` directory can optionally contain project specific plugins. Plugins are a great way to extend `PowerStencil` for the needs of a project or organization. See the [plugins] documentation.
+
+## Getting started
+
+The core of the system is the `entity`, so you should start by having a look at what entities are, how they are easily managed using the `PowerStencil` CLI and shell.
+
+:arrow_forward: [Entities]
+
+Then it is important to understand how to use entities within `templates`. Templates are the way to generate something (doc, code, descriptors, sites, whatever...) from the data that the entities represent.
+
+:arrow_forward: [Templates]
+
+The mechanism that combines entities and templates is called a `build`. A build is always attached to an entity (you build something). The result of a build is a set of files. Optionally an action can be triggered after the files are generated (could be as simple as calling a script that has been generated).
+
+:arrow_forward: [Builds]
+
+`PowerStencil` could stop there, and you would be able to do whatever you want, but there is a whole world beyond. `Plugins` provide a way to completely extend `PowerStencil`, further control relations between entities, implement complex post-build actions, add CLI sub-commands and options. Plugins can be local to the project or coming in the form of standard Ruby Gems ! The icing on the cake...
+
+:arrow_forward: [Plugins]
+
+# Contributing
+
+Bug reports and pull requests are welcome on Gitlab at https://gitlab.com/tools4devops/power_stencil. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License].
+
+## Code of Conduct
+
+Everyone interacting in the PowerStencil project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct].
+
+<!-- End of Document -->
+
+<!-- Pages -->
+[templates]: doc/templates.md "Templates in PowerStencil"
+[entities]: doc/entities.md "Entities in PowerStencil"
+[builds]: doc/builds.md "Builds in PowerStencil"
+[plugins]: doc/plugins.md "Plugins in PowerStencil"
+[example use cases]: doc/example_use_cases.md "Example uses cases using PowerStencil"
+[code of conduct]: CODE_OF_CONDUCT.md
+
+<!-- Code links -->
+[ERB implementation]: lib/power_stencil/engine/renderers/erb.rb "Mostly the only module you need to clone to implement another templating engine"
+
+<!-- Illustrations -->
+[simple-flow-image]: doc/images/power-stencil-simple-flow.svg
+
+<!-- External links -->
+[MIT License]: http://opensource.org/licenses/MIT "The MIT license"
+[ERB]: https://ruby-doc.org/stdlib-2.6.3/libdoc/erb/rdoc/ERB.html "Quick ERB description"
+[Haml]: http://haml.info/ "The templating engine for XML-like documents"
+[Ruby]: https://www.ruby-lang.org "The powerful Ruby language"

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'power_stencil'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/bin/update_plugin_template

@@ -0,0 +1,79 @@
+#!/usr/bin/env ruby
+
+
+require 'bundler/setup'
+require 'tmpdir'
+require 'power_stencil'
+
+LOGGER = Logger.new STDERR
+
+def logger
+  LOGGER
+end
+
+include Climatic::Proxy
+include PowerStencil::Utils::FileHelper
+include PowerStencil::Utils::DirectoryProcessor
+
+POWER_STENCIL_ETC = File.expand_path File.join( '..', '..', 'etc'), __FILE__
+POWER_STENCIL_TEMPLATES_PATH = File.join POWER_STENCIL_ETC, 'templates'
+PLUGIN_DEFINITION_PATH = File.join POWER_STENCIL_TEMPLATES_PATH,'plugin_definition'
+PLUGIN_SEED_PATH = File.join POWER_STENCIL_ETC, 'meta_templates', 'plugin_seed'
+BACKUP_PATH = "%s-#{timestamp Time.now}.old" % [PLUGIN_DEFINITION_PATH]
+# puts "Plugin definition path: '#{PLUGIN_DEFINITION_PATH}'", "Backup path:            '#{BACKUP_PATH}'"
+
+def generate_gem(gem_name, dir)
+  Dir.chdir dir do
+    # Let's create a new gem using bundle
+    res = `bundle gem #{gem_name} --no-exe`
+    # Remove useless files from generated gem source
+    logger.debug "#{res}"
+    gem_path = File.join dir, gem_name
+    substituted_path = File.join dir, 'plugin_definition'
+    gitdir = File.join gem_path,'.git'
+    libdir = File.join gem_path,'lib'
+    gemspecfile = File.join gem_path, "#{gem_name}.gemspec"
+    FileUtils.remove_entry_secure gitdir
+    FileUtils.remove_entry_secure libdir
+    FileUtils.remove_entry_secure gemspecfile
+    # Copy files from power_stencil seed files
+    FileUtils.copy_entry PLUGIN_SEED_PATH, gem_path
+    # Perform file names and content substitutions
+    process_directory source: gem_path,
+                      destination: substituted_path do |source_file, potential_target_file|
+      next if File.directory? source_file
+      target_file = potential_target_file.gsub gem_name, '{entity}'
+      logger.info "Processing #{source_file} -> #{target_file}"
+      file_content = File.read source_file
+      file_content.gsub! gem_name, '<%= plugin_module_name %>'
+      modes = File.stat(source_file).mode
+      FileUtils.mkdir_p(File.dirname target_file)
+      File.open(target_file, 'w') do |file|
+        file.puts file_content
+      end
+      logger.debug "Processed #{target_file}"
+    end
+
+  end
+end
+
+def update_definition_template(source_dir, dest_dir)
+  # Backup old plugin template definition in power stencil gem
+  FileUtils.mv PLUGIN_DEFINITION_PATH, BACKUP_PATH
+  # Copy new definition into gem
+  FileUtils.copy_entry source_dir, dest_dir
+end
+
+fake_gem_name = 'XXXXXXXXXXXX'
+
+Dir.mktmpdir do |tmpdir|
+  Dir.chdir tmpdir do
+    generate_gem fake_gem_name, tmpdir
+    generated_gem_path = File.join(tmpdir, 'plugin_definition')
+    update_definition_template generated_gem_path, PLUGIN_DEFINITION_PATH
+    puts 'bye'
+  end
+end
+
+
+