panko

A CLI-based project manager that reads from a list of separate profiles and allows various tasks to be completed.

Setup

Installation

Install panko globally with Yarn.

yarn global add panko-cli

Updating

Update with Yarn.

yarn global upgrade panko-cli

Quick Guide

1. Create a .pankorc file

   See Creating your .pankorc

   {
     "sources": {
       "my-gh-account": {
         "type": "github-user",
         "handle": "angeloashmore",
         "token": "supersecretpersonalaccesstoken",
         "branch": "development"
       }
     }
   }

2. Install the necessary source plugins

   See List of Source Plugins

   yarn global add panko-source-github-user

3. Update your project cache

   panko update

4. panko is ready to do cool things, but you'll need some command plugins to do some really cool things. Read on.

Creating your .pankorc

Your .pankorc is a JSON file that determines how panko functions.

Example .pankorc:

{
  "sources": {
    "my-gh-account": {
      "type": "github-user",
      "handle": "angeloashmore",
      "token": "supersecretpersonalaccesstoken",
      "branch": "development"
    }
  }
}

Usage

panko is a simple tool to route project metadata, such as server addresses and GitHub repository names, to panko-aware commands. It provides a method to gather project metadata from different sources. It allows for filtering which projects are passed to a command for processing.

Project Profile Files

panko gathers project information through profile files. panko source plugins will typically look for a profile.json file in your project, however this is configurable in your .pankorc.

The following is an example project profile.json file:

{
  "name": "angeloashmore.github.io",
  "repo": "[email protected]:angeloashmore/angeloashmore.github.io.git",
  "arch": {
    "name": "middleman",
    "version": "^4.2"
  }
}

name is the only required attribute for now. As commands are created, these requirements may change.

Sources

Source plugins "source" project information. Sources can gather projects, for example, from the filesystem, GitHub repositories, or even right in the .pankorc file.

Sources are defined under the sources key in .pankorc. Each source has a key and a map of options. At minimum, each source must define it's type in its options so panko knows which plugin to run.

The following options are availble for all sources:

Option | Description --- | --- type | Required: The type of source to use. Determines which plugin to run. file | Name of the profile file to look for. Default: profile.json ttl | Amount of time in milliseconds before panko suggests refreshing the source cache. Default: 1209600000 (14 days)

Additional options are dependent on the source plugin.

List of Source Plugins

1. panko-source-inline: Write a profile file directly in .pankorc
2. panko-source-filesystem: TODO: Point to a directory of projects in the filesystem
3. panko-source-github-user
4. panko-source-github-organization
5. panko-source-gitlab-group

Commands

Command plugins perform tasks on a set projects. panko provides functionality to determine the set of projects passed to a command.

Examples

# Run the "list" command with all projects from the "github" source
panko list --source github

# Run the "list" command with all projects that have the name "personal-site"
panko list --name personal-site

# Run the "list" command with all projects from the "github" source that have
# the name "personal-site"
panko list --source github --name personal-site

Built-In Commands

panko only includes a minimal set of commands to gather project metadata and a system to call external subcommands.

Command | Description --- | --- list | List all projects sources | List all sources in .pankorc update | Update the project cache help | TODO: Print help message

Other functionality, such as listing server statuses or getting page screenshots, are added by installing command plugins. See List of Command Plugins

All commands provide at least the following options:

Option | Description --- | --- --source or -a | Set which source's projects are included. Default: all sources --name or -n | Set which project by name is included. Default: all names

Both options can be combined for instances where a project with the same name, but different metadata, exists in multiple sources.

List of Command Plugins

1. panko-command-status: List server statuses and ping times
2. panko-command-docs: TODO: Open documentation for project
3. panko-command-screenshot: Take screenshots of websites