Historically, every time we've needed to write out something tabular,
we've hand-rolled an ad hoc padded row writer. Yes, in each case. Such
is #startuplife.

The third time we did this we wrote this with bugs, and so now we are
rewriting it in a general, tested function, and transitioning all places
where we call this to use this function.

Renaming environment should also rename nested .jsonnet

[bug fix] Fix optionalParam defaults

Signed-off-by: Jessica Yao <jessica@heptio.com>

Currently the env directory is being renamed on `env set foo
--name=bar`, however the `foo.jsonnet` file also needs to be renamed to
`bar.jsonnet`. This commit fixes that.

De/serialize specification objects with YAML

Add optional params to prototype spec

Jsonnet handling of component names with special characters

Fixes #69.

Currently we allow users to specify prototypes using Jsonnet. At the
head of each prototype should be a comment with semi-structured
metadata, e.g.,

  // @apiVersion 0.0.1
  // @name io.ksonnet.pkg.nginx-simple
  // @description Deploys a simple, stateless nginx server with server
  // blocks (roughly equivalent
  //   to nginx virtual hosts). The nginx container is deployed using a
  //   Kubernetes deployment, and is exposed to a network with a service.
  // @param namespace string default Namespace in which to put the
  // application
  // @param name string Name to give to each of the components

Critically, some metadata about params is stored using the `@param` tag,
including name, type, and description, for pretty printing.

This commit will introduce a new param type, `@optionalParam`. This type
has a name, type, default value, and description.

It is currently not possible to specify a default value with spaces, but
this should be good enough for MVP.

Fixes #48.

Currently the structs `app.Spec`, `registry.Spec`, and `parts.Spec` are
all serialized and deserialized using JSON instead of YAML.

This commit will resolve this issue.

Currently, if a component name contains a special character, ex:
foo-bar, this translates to the jsonnet identifier: foo-bar, which is
invalid syntax.

This change will quote component names where there are special
characters.

Add `vendor/` to Jsonnet paths

Pass context & overrides by reference when initiating client

This resolves the first half of #68. When we `generate` using a
prototype from a vendored dependency, it often results in a compilation
error when we `apply`, because these prototypes usually depend on code
that exists in the dependency, and `vendor/` is not a part of the
Jsonnet search path.

This commit resolves this problem by adding it to the search path.

This fixes the bug where objects weren't being deployed to the cluster
specified by the environment. This bug occurred because overrides (ex:
cluster, namespace) were being lost because we weren't applying the
changes to the correct override object. To fix this, we needed to pass
the overrides by reference.

Add ability to retrieve prototypes from vendor/

Add alias 'ks generate' for 'ks prototype use'

Add rudimentary package management

The ksonnet project exposes a "default" registry, `incubator`, in the
ksonnet/parts repository.

This commit will cause ever `ks init` command to automatically add this
registry to the ksonnet application.

The vast majority of ksonnet apps will know about at least one registry,
the official ksonnet `incubator` registry. In general, managing
registries can involve fairly complex logic (e.g., resolving a reference
to a registry to a remote registry specification; finding all
libraries exposed by a registry; and so on).

This commit will introduce the `registry.Manager` abstraction, as well
as an implementation for registries hosted as GitHub repositories.

When the user calls `ks init <whatever>`, we need to emit an `app.yaml`
for the new project. This commit will introduce such behavior.

Every ksonnet application has an `app.yaml`, which is similar in
principle to node.js's `package.json`. It contains important metadata,
such as description, names, and information about dependencies. This is
similarly true of `registry.yaml`, which contains information about a
package registry.

This commit will introduce schemas for both these files.

Introduce environment params

Pretty prints differences between the component parameters of two
environments.

A component flag is accepted to diff against a single component. By
default, the diff is performed against all components.

Pretty prints component or environment parameters.

This command will display all parameters for the component specified. If
a component is not specified, parameters for all components will be
listed.

Furthermore, parameters can be listed on a per-environment basis.

Examples:

List all component parameters
  ks param list

List all parameters for the component "guestbook"
  ks param list guestbook

List all parameters for the environment "dev"
  ks param list --env=dev

List all parameters for the component "guestbook" in the environment
"dev"
  ks param list guestbook --env=dev`,

Parameters are the customizable fields defining ksonnet components. For
example, replica count, component name, or deployment image.

Parameters are also able to be defined separately across environments.
Meaning, this supports features to allow a "development" environment to
only run a single replication instance for it's components, whereas
allowing a "production" environment to run more replication instances to
meet heavier production load demands.

'ks param set' is defined as follows:
  'ks param set <component-name> <param-key> <param-value>'

Examples:

Updates the replica count of the 'guestbook' component to 4.
  'ks param set guestbook replicas 4'

Updates the replica count of the 'guestbook' component to 2 for the
environment 'dev'
  'ks param set guestbook replicas 2 --env=dev'

The goal of this commit is to add an interface to `metadata.Manager`
that allows retrieving of all environment params:
`getEnvironmentParams(envName)`.

This is done by:

1. Adding functionality to the snippet parser to get all environment
params out of the snippet read from
`environments/<env>/params.libsonnet`

2. Adding functionality to the snippet parser to get all component
params out of the snippet read from `components/params.libsonnet`

3. Having the `metadata.Manager` implementation handle the 'joining' of
params from 1) and 2), and returning that result.

This commit will add an interface `SetEnvironmentParams` to
metadata.Manager that allows setting of env params.

Also implements the logic for parsing the jsonnet snippet to
append / modify params in simple env param schemas. It will:

1. Update the params if the component exists in the jsonnet
snippet.
2. Add the component if it does not exist.

This commit will add an interface `GetComponentParams` to
metadata.Manager that returns a map of parameters for the passed in
component.

Also implements the logic for parsing the jsonnet snippet to retrieve
the parameters.

This functionality will later support new commands to list parameters.

This commit will:

1. Add an interface `SetComponentParams` to metadata.Manager that takes
a list of parameters and sets those fields for the given component.

2. Add the jsonnet snippet manipulation logic that does the
'setting'. Parameters are set by:

a. Keeping track of the parameters that are to be modified / added --
this defaults to the parameters provided to us.
b. Discovering the current parameters in the existing snippet.
c. Adding any parameters from (b) that is not in (a).
d. Swapping out the old parameters with (c) in the snippet based on
the location text span, and returning the new snippet.

This commit will append both mandatory and optional  prototype
parameters to the component params.libsonnet file on `ks gen foo ...`.

Default values will be used for optional params where the user does not
specify flags to `ks gen foo ...`.

Because we are trying to append to jsonnet, we will have to traverse the
AST to first identify the location of where to insert the new component
params. New components will be inserted at the bottom of the components
object, with the params ordered alphabetically.

We are currently parsing system prototypes using the default TextMate
snippet which does not take into account the translation of params of
format `import 'param://foo`. The jsonnet snippet parser does take this
into account.

Rewrite system prototype params from `${foo}` format to `import
'param://foo'` so that they can be parsed correctly by the jsonnet
snippet.

This commit will cause the jsonnet snippet parser to parse input of the
form `import 'param://foo` to `params.foo` as opposed to the previous
`${foo}`.

${foo} does not provide an easily accessible way to the params that are
exposed through the params.libsonnet file. Since parameters are being
exposed using a local 'params' variable, it makes sense for the jsonnet
snippet to parse `import param://foo as `params.foo` instead.