sem 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8036852bc88fc42ae39872cd6db29f0e780928e7
+  data.tar.gz: 598ef13e790734d57ace6f06851ec270137eb9f0
+SHA512:
+  metadata.gz: b1c549f209533cdb62adf4c00bb4726819731f1f172ceb78b4c3c7fa5b4483f7bb42683aae4291c6094e167e7a7baf3501d4e75aca01b4e2678efd88fb139ddd
+  data.tar.gz: 3734c15ca55161ca222ff16270790a95920d0a82f9b0fffc51b0496a48f56d4188fab458c7cc85f030674cf3b5e1a4325a5d909b8cbab6c026d065d06dc78ce4

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/vendor/
+
+# rspec failure tracking
+.rspec_status
+.byebug_history

data/.rspec

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

data/.rubocop.yml

@@ -0,0 +1,103 @@
+require: rubocop-rspec
+
+AllCops:
+  DisplayCopNames: true
+
+  Exclude:
+    - "*.gemspec"
+    - "vendor/**/*"
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/NumericLiterals:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/HashSyntax:
+  EnforcedStyle: hash_rockets
+
+Style/CollectionMethods:
+  StyleGuide: "https://github.com/bbatsov/ruby-style-guide#map-find-select-reduce-size"
+  Enabled: true
+
+Metrics/LineLength:
+  Max: 120
+
+Style/EmptyLinesAroundClassBody:
+  Enabled: false
+
+Style/EmptyLinesAroundModuleBody:
+  Enabled: false
+
+Style/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+  IndentationWidth: 2
+
+Style/SpecialGlobalVars:
+  Enabled: false
+
+Style/PercentLiteralDelimiters:
+  Enabled: false
+
+RSpec/InstanceVariable:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Max: 5
+
+Metrics/BlockLength:
+  Exclude:
+    - "Rakefile"
+    - "**/*.rake"
+    - "spec/**/*.rb"
+
+Style/EmptyLinesAroundBlockBody:
+  Enabled: false
+
+RSpec/BeforeAfterAll:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Enabled: false
+
+RSpec/DescribedClass:
+  Enabled: false
+
+Style/IndentArray:
+  EnforcedStyle: consistent
+
+Style/MultilineMethodCallBraceLayout:
+  Enabled: false
+
+RSpec/MessageSpies:
+  Enabled: false
+
+Style/MultilineBlockLayout:
+  Enabled: false
+
+RSpec/SubjectStub:
+  Enabled: false
+
+RSpec/DescribeClass:
+  Enabled: false
+
+RSpec/LeadingSubject:
+  Enabled: false
+
+Style/WordArray:
+  Enabled: false
+
+RSpec/NotToNot:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in sem.gemspec
+gemspec
+
+gem "dracula", :github => "shiroyasha/dracula"

data/README.md

@@ -0,0 +1,27 @@
+# Semaphore CLI
+
+[![Build Status](https://semaphoreci.com/api/v1/renderedtext/cli/branches/master/badge.svg)](https://semaphoreci.com/renderedtext/cli)
+
+![Semaphore logo](https://d1dkupr86d302v.cloudfront.net/assets/application_bootstrap/layout/semaphore-logo-a6d954e176b6975b511f314a0cc808dc94a8030210077e3a6e904fbe69dc5354.svg)
+
+__Note: This tool is still in the early phase of development.__
+
+The Semaphore CLI is used to manage Semaphore projects from the command line.
+
+For more info about Semaphore see <https://www.semaphoreci.com>
+
+## Issues
+
+For problems directly related to the CLI, [add an issue on GitHub](https://github.com/renderedtext/cli/issues/new).
+
+For other issues, [submit a support ticket](https://semaphoreci.com/support).
+
+[Contributors](https://github.com/renderedtext/cli/contributors).
+
+## Developing
+
+Developing the CLI locally requires Ruby.
+
+While developing please follow the [CLI development guide](guide.md).
+
+To run the CLI locally, use the `bundle exec sem`.

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :quality => [:spec] do
+  system("bundle exec rubocop") != false
+end
+
+task :default => :quality

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "sem"
+
+# 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/exe/sem

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "sem"
+
+exit Sem.start(ARGV)

data/guides.md

@@ -0,0 +1,168 @@
+# Guides & Constraints
+
+This document serves as a guide that highlights the important details while
+developing the CLI. Please consult this guide before merging any Pull Request.
+
+Content:
+
+- [Development language](#development-language)
+- [Simple setup](#simple-setup)
+- [Authentication](#authentication)
+- [Excellent help screens](#excellent-help-screens)
+- [Command line Tab Completion](#command-line-tab-completion)
+- [Errors and warnings](#errors-and-warnings)
+- [Configuration](#configuration)
+- [Format of the Output](#format-of-the-output)
+
+## Development language
+
+We decided to write the CLI in Ruby. Our assumption is
+that most of our customers have Ruby preinstalled, or that they have the
+knowledge to set it up. Ruby is language that offers excellent tools for
+developing command line interfaces (e.g thor), and we have deep understanding of
+the language and the ecosystem.
+
+We want to support Ruby versions >= 2.0, and set up continuous integration for
+every significant Ruby version (2.0, 2.1., 2.2, 2.3, 2.4).
+
+The choice of the language dictates the preferable installation method of `gem
+install semaphore-cli`.
+
+## Simple setup
+
+Developers like to set up and test tools fast. In this area, docker serves as
+a good example as it can be installed with one command:
+
+```
+wget -qO- https://get.docker.com/ | sh
+```
+
+As our client will be written in Ruby, we will have to rely on the user to
+install it before installing our CLI. However, this doesn't mean that we can't
+make the installation step simple and intuitive.
+
+Installation methods for SemaphoreCli:
+
+- `gem install semaphore-cli`
+- (optional) `wget -qO- https://cli.semaphoreci.com | sh`
+- (optional) `sudo apt-get install semaphore-cli`
+
+The shell script installation method should warn if Ruby is not installed, or if
+the installed version is not supported. For clarity and proper versioning, we
+should support installation of specific versions of the client. For example,
+`wget -qO- https://cli.semaphoreci.com/v1.0.3 | sh` will install the `v1.0.3`
+version on the user's system.
+
+## Authentication
+
+For start, we don’t want to store raw credentials, like a
+username and password. Yes, the developer is responsible for their own machine’s
+security, but there are better methods that ensure your CLI and user info will
+stay secure.
+
+Storing the access token in a resource file `~/.semaphoreci` is a better choice.
+If the key falls into the wrong hands, it can be revoked without affecting the
+user’s primary login.
+
+HTTPS is a must.
+
+Users would authenticate with the `semaphore login` command. This is an
+interactive command that asks for the username, password and 2fa code and stores
+the auth token in the `~/.semaphoreci` file.
+
+Non-interactive usage of the `login` command will not be supported as it would
+encourage unsafe practices for the CLI. In a non-interactive environments (e.g
+CI builds) users should inject the `~/.semaphoreci` file in the environment.
+
+## Excellent help screens
+
+Getting started with a CLI is unlike using other software for the first time.
+There is not always a welcome screen, no confirmation email with a link to
+documentation. Only through the command itself can developers explore what’s
+possible.
+
+This experience begins with the help screen. Ideally, we should include multiple
+ways to come across the help screen. For example, git provides `git --help` and
+`git help` both of which shows the same screen. Even better, the help screen
+should be accessible with short flags, such as `-h` or `-?`.
+
+The CLI help screen is essentially a getting started documentation for the
+command line. We should list out the possible commands in logical groups, with
+each group in alphabetical order. Along with each command, give a quick and
+thorough explanation. It’s a balancing act of saying enough without saying too
+much.
+
+As an addition to the main help screen, the users should be able to explore
+further and get help for specific actions. For example, `semaphore help
+team:create` should go in details about the `team:create` command, explaining
+the required and optional parameters, the preconditions for successful
+execution, and the expected results.
+
+## Command line Tab Completion
+
+Using the command line is all about controlling a computer at the speed of
+thought. CLIs aren’t typically seen on the same level as other interfaces. Yet,
+they share the commonality that a good interface helps users get things done.
+
+Tab completion significantly improves the usability of a command line tool. Bash
+and Zsh completion should be implemented and installed out of the box.
+
+## Errors and warnings
+
+A command line tool should not fail silently, neither should it fail with a `0`
+exit status. We should provide meaningful exit statuses accompanied with
+descriptive descriptions that provide context and possible corrections for the
+failure.
+
+Example of descriptive failure:
+
+```
+$ semaphore teams:list
+[ERROR] Can't connect to the remote server semaphoreci.com.
+
+$ echo $?
+19
+```
+
+No Ruby error should be allowed to propagate to the user directly. In case of
+unexpected failures, the command should describe that an unexpected error has
+occurred, a link where the failure can be reported, and a tracelog of the
+command with followed by the context in which it was invoked.
+
+Example of descriptive unexpected failure:
+
+```
+$ semaphore teams:list
+[ERROR] Unexpected error. Please report this issue to semaphoreci.com/support.
+
+Context:
+  Called with: sempahore teams:list
+  Resource file `~/.semaphoreci` not-empty
+  Timestamp: 1500000312321
+  Version: v1.0.4
+
+Trace:
+  ZeroDivisionError: divided by 0
+    from (irb):2:in `/'
+    from (irb):2
+    from /usr/local/rbenv/versions/2.3.4/bin/irb:11:in
+    `<main>'
+
+$ echo $?
+1
+```
+
+## Configuration
+
+A command line tool should be configurable. Setting alternative domains for
+staging, changing the default output format come to my mind.
+
+## Format of the Output
+
+Every command should have a `--json` and `--yaml` flag to indicate that we want
+to display the response as JSON or Yaml.
+
+The default output should be human readable, and should use colors to indicate
+important fields and values.
+
+If the command is piped into another command, no colors should be used.

data/ids.md

@@ -0,0 +1,74 @@
+# IDs in the CLI
+
+Computers like to work with long IDs, but humans are much more comfortable with
+hierarchical identifiers. A good example is git. While you could in theory do
+everything with SHAs, the git interface allows you to work with labels such as
+`master`, `HEAD`, `HEAD^2`, etc...
+
+Semaphore exposes resources and uses UUIDs to uniquely identify resources. This
+is very clean when it comes to the API interface, but it is a struggle to work
+with from the CLI. For each step you must list the resources, find out their
+ids, and then gather any useful information from them.
+
+As an example, let's consider looking up the state of the last build on the
+master branch for the test-boosters project. To achieve this, a user would need
+to look up several IDS:
+
+``` txt
+$ sem orgs
+
+931b14f7-0631-47a7-bb30-58b1c794e62c renderedtext
+68ce72af-5725-4c04-af74-5f6ecc9f5e9a renderedtext-playground
+
+
+$ sem projects --org-id 931b14f7-0631-47a7-bb30-58b1c794e62c
+
+331b14f7-0631-47a7-bb30-58b1c794e62c test-boosters
+68ce72af-5725-4c04-af74-5f6ecc9f5e9a semaphore-blog
+
+
+$ sem branches --project-id 331b14f7-0631-47a7-bb30-58b1c794e62c
+
+531b14f7-0631-47a7-bb30-58b1c794e62c master
+98ce72af-5725-4c04-af74-5f6ecc9f5e9a rspec-test
+78ce99af-5725-4c04-abas-5f6ecc9f5e9a development
+
+
+$ sem builds --branch-id 531b14f7-0631-47a7-bb30-58b1c794e62c
+
+531b14f7-0631-47a7-bb30-58b1c794e62c #9901
+98ce72af-5725-4c04-af74-5f6ecc9f5e9a #9090
+78ce99af-5725-4c04-abas-5f6ecc9f5e9a #9089
+
+
+$ sem builds:info 531b14f7-0631-47a7-bb30-58b1c794e62c
+
+531b14f7-0631-47a7-bb30-58b1c794e62c #9901 PASSED
+```
+
+This is clearly inefficient, and requires many hops from the user. The user
+already knows the following information `renderedtext/test-boosters/master` but
+he doesn't have a good way to tell this information to the semaphore CLI
+efficiently.
+
+A better interface would be:
+
+```
+$ sem builds renderedtext/test-boosters/master
+
+531b14f7-0631-47a7-bb30-58b1c794e62c #9901 PASSED
+98ce72af-5725-4c04-af74-5f6ecc9f5e9a #9090 FAILED
+```
+
+But for this, we need to have a good way to identify and transmit hierarchical
+information to the CLI. The CLI itself can make multiple calls to the API to
+collect this information.
+
+This is not a finished proposal, only an intro for further thinking.
+
+My current best ideas are to use `/` to pass the hierarchical information, but
+this has its downsides.
+
+Other ideas is to look into ARN(amazon resource names) and maybe collect some
+good ideas. That way, we could formalize this format and introduce SRN(semaphore
+resource names) or SRI(semaphore resource identifiers).