{"id":15022685,"url":"https://github.com/puppetlabs/puppetlabs-ruby_task_helper","last_synced_at":"2025-04-09T20:07:58.032Z","repository":{"id":33215504,"uuid":"153164088","full_name":"puppetlabs/puppetlabs-ruby_task_helper","owner":"puppetlabs","description":"A ruby library for running tasks","archived":false,"fork":false,"pushed_at":"2024-11-14T15:33:16.000Z","size":55,"stargazers_count":4,"open_issues_count":1,"forks_count":15,"subscribers_count":78,"default_branch":"main","last_synced_at":"2025-04-09T20:07:54.292Z","etag":null,"topics":["module","supported"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puppetlabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-15T18:41:27.000Z","updated_at":"2024-11-14T15:19:46.000Z","dependencies_parsed_at":"2025-01-16T03:12:19.470Z","dependency_job_id":"62ff6b35-89d8-49b2-9bc0-1255a030f1ff","html_url":"https://github.com/puppetlabs/puppetlabs-ruby_task_helper","commit_stats":{"total_commits":25,"total_committers":7,"mean_commits":"3.5714285714285716","dds":0.6,"last_synced_commit":"969e1c0718a074f9217de7bf82a6de15dd97eb4b"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-ruby_task_helper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-ruby_task_helper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-ruby_task_helper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-ruby_task_helper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puppetlabs","download_url":"https://codeload.github.com/puppetlabs/puppetlabs-ruby_task_helper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248103872,"owners_count":21048245,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["module","supported"],"created_at":"2024-09-24T19:58:16.212Z","updated_at":"2025-04-09T20:07:58.001Z","avatar_url":"https://github.com/puppetlabs.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ruby Task Helper\n\nA Ruby helper library for writing [Puppet tasks](https://puppet.com/docs/bolt/latest/writing_tasks.html). It provides a class that handles error generation, simplifies JSON input and output, and makes testing your task easier. It requires Bolt \u003e= 1.1 or Puppet Enterprise \u003e= 2019.0.\n\n#### Table of Contents\n\n1. [Description](#description)\n1. [Requirements](#requirements)\n1. [Setup](#setup)\n1. [Usage](#usage)\n1. [Debugging](#debugging)\n1. [Testing](#testing)\n\n## Description\n\nThis library handles parsing JSON input, serializing the result as JSON output, and producing a formatted error message for errors.\n\n## Requirements\n\nThis library works with Ruby 2.3 and later, though is tested using Ruby 2.4 and 2.5.\n\n## Setup\n\nTo use this library, include this module in a [Puppetfile](https://puppet.com/docs/pe/2019.0/puppetfile.html):\n\n```ruby\nmod 'puppetlabs-ruby_task_helper'\n```\n\nAdd it to your [task metadata](https://puppet.com/docs/bolt/latest/writing_tasks.html#concept-677)\n```json\n{\n  \"files\": [\"ruby_task_helper/files/task_helper.rb\"],\n  \"input_method\": \"stdin\"\n}\n```\n\n## Usage\n\nWhen writing your task include the library in your script, extend the `TaskHelper` module, and write the `task()` function. The `task()` function should accept its parameters as symbols, and should return a hash. The following is an example of a task that uses the library. All parameters will be symbolized including nested hash keys and hashes contained in arrays.\n\n`mymodule/tasks/mytask.rb`\n```ruby\n#!/usr/bin/env ruby\n\nrequire_relative \"../../ruby_task_helper/files/task_helper.rb\"\n\nclass MyClass \u003c TaskHelper\n  def task(name: nil, **kwargs)\n    {greeting: \"Hi, my name is #{name}\"}\n  end\nend\n\nif __FILE__ == $0\n  MyClass.run\nend\n```\n\nYou can then run the task like any other Bolt task:\n```bash\nbolt task run mymodule::task -t target.example.com name=\"Robert'); DROP TABLE Students;--\"\n```\n\nYou can additionally provide detailed errors by raising a `TaskError`, such as\n```ruby\nclass MyTask \u003c TaskHelper\n  def task(**kwargs)\n    raise TaskHelper::Error.new(\"my task error message\",\n                               \"mytask/error-kind\",\n                               \"Additional details\")\n```\n\n## Debugging\n\nWhen writing your task, it can be helpful to write debugging statement to locate\nthe source of any errors. The library includes a `debug` method that accepts arbitrary\nvalues and logs it as a debugging statement. If the task errors, the list of\ndebugging statements will be included in the resulting `TaskError`.\n\nThe list of debugging statements can also be accessed from the task itself by calling\nthe `debug_statements` method. This can be used to include the debugging statements in\na `TaskError` that you explicitly raise.\n\nAdding a debugging statement:\n```ruby\ndebug \"Result of method call: #{result}\n```\n\nAdding the list of debugging statements to a `TaskError`:\n```ruby\nraise TaskHelper::Error.new(\"my task error message\",\n                            \"mytask/error-kind\",\n                            \"debug\" =\u003e debug_statements)\n```\n\n## Testing\n\nBy implementing the task as a method and not executing the task as a script\nunless it is invoked directly it becomes much easier to write rspec tests for\nyour task. Make sure the task helper repo is checked out next to your module so\nthe relative requires work and you can write simple unit tests for the methods\nof your task.\n\n`mymodule/spec/mytask_spec.rb`\n```ruby\nrequire_relative '../tasks/mytask.rb'\n\ndescribe 'MyTask' do\n  let(:params) { { name: 'Lucy' } }\n  let(:task) { MyTask.new() }\n\n  it 'runs my task' do\n    expect(task.task(params)).to eq({greeting: 'Hi, my name is Lucy'})\n  end\nend\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-ruby_task_helper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-ruby_task_helper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-ruby_task_helper/lists"}