Polishing the new monorepo

docs/CONTRIBUTING.md

@@ -0,0 +1,115 @@
+# Contributing to Twilio Serverless Toolkit
+
+## About the Project
+
+This project is a "monorepo" meaning it contains several Node.js packages in one repository. The code for all packages are in the [`packages/`](../packages) directory. We are using a tool called [Lerna](https://lerna.js.org) to manage those multiple packages.
+
+## Before you contribute
+
+We welcome everyone to contribute to this project. If you don't know what to work on, [check our open Issues](https://github.com/twilio-labs/serverless-toolkit/issues) and specifically for the `Help Wanted` and `Good First Issue` labels.
+
+If you want to work on one of those open issues, please comment on the issue to let us know that you are working on it. Similarly if you can't work on it anymore, please let us know.
+
+If you are planning to contribute something that does not have an open issue yet, please open an issue for it before you start working on it. This way we can help you find a good solution.
+
+## Requirements
+
+Make sure you have Node.js 10 or newer installed. Due to compatibility with Twilio
+Functions this project has to support at least Node.js 10.0.0.
+
+We are using the npm CLI to manage our project. You should be able to use yarn but you might hit some issues.
+
+## Setup your local project
+
+1. Clone project and install dependencies
+
+```bash
+git clone https://github.com/twilio-labs/serverless-toolkit.git
+cd serverless-toolkit
+npm install
+npm run bootstrap
+```
+
+## Contributing
+
+1. Perform changes. Check out [Working with Lerna](#working-with-lerna) for more info
+2. Make sure tests pass by running `npm test`
+3. Stage the files you changed by running `git add` with the files you changed.
+4. Run `git commit` to kick off validation and enter your commit message. We are using [conventional commits](https://www.conventionalcommits.org/en/) for this project. When you run `npm run cm` it will trigger [`commitizen`](https://npm.im/commitizen) to assist you with your commit message.
+5. Submit a Pull Request
+
+**Working on your first Pull Request?** You can learn how from this _free_ series [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github)
+
+## For Maintainers: Releasing
+
+This project uses [`lerna version`](https://www.npmjs.com/package/@lerna/version) to create new releases for any package needed, create the respective git tag and update the necessary `CHANGELOG.md` files. We always pass certain flags, so please use it via `npm run release`. Here are the steps you need to run to release a new version:
+
+### Pre-release version (from `main` or any `features/*` branch):
+
+For example to release a new pre-release version containing `beta` and releasing it as `next`:
+
+```bash
+npm run release -- --conventional-prerelease --preid beta
+git push origin main --follow-tags
+npm run publish -- --otp=<OTP> --dist-tag next
+```
+
+If you want to turn a prerelease into a permanent version you can use:
+
+```bash
+npm run release -- --conventional-commits --conventional-graduate
+git push origin main --follow-tags
+npm run publish -- --otp=<OTP>
+```
+
+### Normal release (from `main` branch):
+
+For a normal release `standard-version` will detect the version increment automatically. Run:
+
+```bash
+npm run release
+git push origin main --follow-tags
+npm run publish -- --otp=<OTP>
+```
+
+To ship a specific version instead (like a forced minor bump) you can run:
+
+```bash
+npm run release -- minor
+git push origin master --follow-tags
+npm run publish -- --otp=<OTP>
+```
+
+## Working with Lerna
+
+### Linking Packages
+
+Lerna will automatically link together the different dependencies that are part of the project. You can run `npm run bootstrap` to create the links.
+
+### Installing Dependencies
+
+Dev dependencies should ideally be installed at the top level using `npm install --save-dev`. If you want to execute a binary from a dependency in a particular package you should install it in that particular package instead.
+
+Installing dependencies for packages can be done in two ways. You can either use the [`lerna add` command](https://github.com/lerna/lerna/tree/master/commands/add) or using `npm install` inside the respective package.
+
+The later might be the more intuitive one but it might cause some bootstraping issues.
+
+### Running Scripts
+
+Scripts that are on the top level can be run via `npm run <script>`.
+
+If you want to run a script in every individual package where it is defined you can run: [`lerna run <script>`](https://github.com/lerna/lerna/tree/master/commands/run).
+
+To execute any bash command inside every package you can use [`lerna exec`](https://github.com/lerna/lerna/tree/master/commands/exec).
+
+### Resetting dependencies
+
+You can run `lerna clean` to delete all `node_modules` folder. To reinstall them run `npm run bootstrap`
+
+## Code of Conduct
+
+Please be aware that this project has a [Code of Conduct](https://github.com/twilio-labs/.github/blob/master/CODE_OF_CONDUCT.md). The tldr; is to just be excellent to each other ❤️
+
+## Licensing
+
+All third party contributors acknowledge that any contributions they provide will be made under the same open source license that the open source project is provided under.

DESIGN.md → docs/DESIGN.md

@@ -18,7 +18,7 @@ consideration.
 While all modules together form the Serverless Toolkit, we offer with the
 different modules a way for people to use different parts of the project.
 
-For example the [Serverless Framework Integration](https://github.com/twilio-labs/serverless-framework-integration) makes use of [`@twilio-labs/serverless-api`] but not of any of the CLI functionality.
+For example the [Serverless Framework Integration][`@twilio-labs/serverless-twilio-runtime`] makes use of [`@twilio-labs/serverless-api`] but not of any of the CLI functionality.
 
 Right now the project breaks down into the following modules:
 

package.json

@@ -4,7 +4,8 @@
   "scripts": {
     "bootstrap": "lerna bootstrap --no-ci",
     "postbootstrap": "lerna run build",
-    "release": "lerna version --conventional-commits",
+    "release": "lerna version --conventional-commits --no-commit-hooks --no-push",
+    "publish": "lerna publish from-git",
     "cm": "git-cz",
     "jest": "jest",
     "build:noemit": "lerna run build:noemit",

packages/README.md

@@ -0,0 +1,12 @@
+# Packages Overview
+
+This repository is structured as a monorepo using [Lerna](https://lerna.js.org) and contains multiple packages:
+
+| Package                                                               | Description                                                                                                                 | Changelog                                                        |                                                                                                                                                                                                                                                          |
+| :-------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`@twilio-labs/plugin-serverless`](plugin-serverless)                 | [Twilio CLI](https://www.twilio.com/docs/cli) Plugin that wraps `create-twilio-function` and `twilio-run`                   | [Changelog](@twilio-labs/plugin-serverless/CHANGELOG.md)         | ![npm](https://img.shields.io/npm/v/@twilio-labs/plugin-serverless?color=red&label=@twilio-labs/plugin-serverless&style=flat-square) <br> ![npm](https://img.shields.io/npm/dm/@twilio-labs/plugin-serverless?style=flat-square)                         |
+| [`@twilio-labs/serverless-api`](serverless-api)                       | Wrapper library to work with the [Functions & Assets API from Twilio](https://twilio.com/docs/runtime/functions-assets-api) | [Changelog](@twilio-labs/serverless-api/CHANGELOG.md)            | ![npm](https://img.shields.io/npm/v/@twilio-labs/serverless-api?color=red&label=@twilio-labs/serverless-api&style=flat-square) <br> ![npm](https://img.shields.io/npm/dm/@twilio-labs/serverless-api?style=flat-square)                                  |
+| [`@twilio-labs/serverless-runtime-types`](serverless-runtime-types)   | TypeScript types representing the Twilio Runtime for Functions                                                              | [Changelog](@twilio-labs/serverless-runtime-types/CHANGELOG.md)  | ![npm](https://img.shields.io/npm/v/@twilio-labs/serverless-runtime-types?color=red&label=@twilio-labs/serverless-runtime-types&style=flat-square) <br> ![npm](https://img.shields.io/npm/dm/@twilio-labs/serverless-runtime-types?style=flat-square)    |
+| [`@twilio-labs/serverless-twilio-runtime`](serverless-twilio-runtime) | Integration for the [Serverless](https://serverless.com) Platform.                                                          | [Changelog](@twilio-labs/serverless-twilio-runtime/CHANGELOG.md) | ![npm](https://img.shields.io/npm/v/@twilio-labs/serverless-twilio-runtime?color=red&label=@twilio-labs/serverless-twilio-runtime&style=flat-square) <br> ![npm](https://img.shields.io/npm/dm/@twilio-labs/serverless-twilio-runtime?style=flat-square) |
+| [`create-twilio-function`](create-twilio-function)                    | CLI tool to create new Twilio Functions projects                                                                            | [Changelog](create-twilio-function/CHANGELOG.md)                 | ![npm](https://img.shields.io/npm/v/create-twilio-function?color=red&label=create-twilio-function&style=flat-square) <br> ![npm](https://img.shields.io/npm/dm/create-twilio-function?style=flat-square)                                                 |
+| [`twilio-run`](twilio-run)                                            | CLI tool to develop, debug and deploy Twilio Serverless products                                                            | [Changelog](twilio-run/CHANGELOG.md)                             | ![npm](https://img.shields.io/npm/v/twilio-run?color=red&label=twilio-run&style=flat-square) <br> ![npm](https://img.shields.io/npm/dm/twilio-run?style=flat-square)                                                                                     |

packages/create-twilio-function/package.json

@@ -12,14 +12,17 @@
     "twilio-functions",
     "serverless"
   ],
-  "author": "Phil Nash <philnash@twilio.com> (https://philna.sh)",
+  "author": "Twilio Inc. <open-source@twilio.com> (https://www.twilio.com/labs)",
+  "contributors": [
+    "Phil Nash <philnash@twilio.com> (https://philna.sh)"
+  ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/twilio-labs/create-twilio-function.git"
+    "url": "https://github.com/twilio-labs/serverless-toolkit.git"
   },
-  "homepage": "https://github.com/twilio-labs/create-twilio-function",
+  "homepage": "https://github.com/twilio-labs/serverless-toolkit",
   "bugs": {
-    "url": "https://github.com/twilio-labs/create-twilio-function/issues"
+    "url": "https://github.com/twilio-labs/serverless-toolkit/issues"
   },
   "license": "MIT",
   "devDependencies": {

packages/plugin-serverless/package.json

@@ -2,8 +2,10 @@
   "name": "@twilio-labs/plugin-serverless",
   "description": "Develop and deploy Twilio Serverless Functions",
   "version": "1.8.0",
-  "author": "Dominik Kundel <dkundel@twilio.com>",
-  "bugs": "https://github.com/twilio-labs/plugin-serverless/issues",
+  "author": "Twilio Inc. <open-source@twilio.com> (https://www.twilio.com/labs)",
+  "contributors": [
+    "Dominik Kundel <dkundel@twilio.com>"
+  ],
   "dependencies": {
     "@oclif/command": "^1.5.19",
     "@oclif/config": "^1.13.3",
@@ -30,7 +32,6 @@
     "LICENSE",
     "README.md"
   ],
-  "homepage": "https://github.com/twilio-labs/plugin-serverless",
   "keywords": [
     "oclif-plugin",
     "twilio-cli-plugin",
@@ -74,7 +75,14 @@
   "publishConfig": {
     "access": "public"
   },
-  "repository": "twilio-labs/plugin-serverless",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/twilio-labs/serverless-toolkit.git"
+  },
+  "homepage": "https://github.com/twilio-labs/serverless-toolkit",
+  "bugs": {
+    "url": "https://github.com/twilio-labs/serverless-toolkit/issues"
+  },
   "scripts": {
     "postpack": "rm -f oclif.manifest.json",
     "prepack": "oclif-dev manifest && oclif-dev readme",

packages/serverless-api/README.md

@@ -1,6 +1,3 @@
-> # Important:
-> This repository is being moved into a monorepo. In the meantime, for any issues please open an issue at [github.com/twilio-labs/twilio-run/issues](https://github.com/twilio-labs/twilio-run/issues).
-
 <h1 align="center">@twilio-labs/serverless-api</h1>
 <p align="center">A module to interact with the <a href="https://www.twilio.com/functions">Twilio Serverless</a> API. For example to deploy projects. 
 Part of the <a href="https://github.com/twilio-labs/serverless-toolkit">Serverless Toolkit</a>.
@@ -9,20 +6,20 @@ Part of the <a href="https://github.com/twilio-labs/serverless-toolkit">Serverle
 <img alt="npm (scoped)" src="https://img.shields.io/npm/v/@twilio-labs/serverless-api.svg?style=flat-square"> <img alt="npm" src="https://img.shields.io/npm/dt/@twilio-labs/serverless-api.svg?style=flat-square"> <img alt="GitHub" src="https://img.shields.io/github/license/twilio-labs/serverless-api.svg?style=flat-square"> <a href="#contributors"><img alt="All Contributors" src="https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square" /></a> <a href="https://github.com/twilio-labs/.github/blob/master/CODE_OF_CONDUCT.md"><img alt="Code of Conduct" src="https://img.shields.io/badge/%F0%9F%92%96-Code%20of%20Conduct-blueviolet.svg?style=flat-square"></a> <a href="http://makeapullrequest.com"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square" alt="PRs Welcome" /></a> </<a>
 <hr>
 
-* [Installation](#installation)
-* [Example](#example)
-* [HTTP Client Configuration](#http-client-configuration)
-* [API](#api)
-  * [`client.activateBuild(activateConfig: ActivateConfig): Promise<ActivateResult>`](#clientactivatebuildactivateconfig-activateconfig-promiseactivateresult)
-  * [`client.deployLocalProject(deployConfig: DeployLocalProjectConfig): Promise<DeployResult>`](#clientdeploylocalprojectdeployconfig-deploylocalprojectconfig-promisedeployresult)
-  * [`client.deployProject(deployConfig: DeployProjectConfig): Promise<DeployResult>`](#clientdeployprojectdeployconfig-deployprojectconfig-promisedeployresult)
-  * [`client.getClient(): GotClient`](#clientgetclient-gotclient)
-  * [`client.list(listConfig: ListConfig): Promise<ListResult>`](#clientlistlistconfig-listconfig-promiselistresult)
-  * [`api` and `fsHelpers`](#api-and-fshelpers)
-* [Contributing](#contributing)
-  * [Code of Conduct](#code-of-conduct)
-  * [Contributors](#contributors)
-* [License](#license)
+- [Installation](#installation)
+- [Example](#example)
+- [HTTP Client Configuration](#http-client-configuration)
+- [API](#api)
+  - [`client.activateBuild(activateConfig: ActivateConfig): Promise<ActivateResult>`](#clientactivatebuildactivateconfig-activateconfig-promiseactivateresult)
+  - [`client.deployLocalProject(deployConfig: DeployLocalProjectConfig): Promise<DeployResult>`](#clientdeploylocalprojectdeployconfig-deploylocalprojectconfig-promisedeployresult)
+  - [`client.deployProject(deployConfig: DeployProjectConfig): Promise<DeployResult>`](#clientdeployprojectdeployconfig-deployprojectconfig-promisedeployresult)
+  - [`client.getClient(): GotClient`](#clientgetclient-gotclient)
+  - [`client.list(listConfig: ListConfig): Promise<ListResult>`](#clientlistlistconfig-listconfig-promiselistresult)
+  - [`api` and `fsHelpers`](#api-and-fshelpers)
+- [Contributing](#contributing)
+  - [Code of Conduct](#code-of-conduct)
+  - [Contributors](#contributors)
+- [License](#license)
 
 ## Installation
 
@@ -35,28 +32,28 @@ npm install @twilio-labs/serverless-api
 If you want to deploy a local project you can do this using:
 
 ```js
-const { TwilioServerlessApiClient } = require('@twilio-labs/serverless-api');
+const { TwilioServerlessApiClient } = require("@twilio-labs/serverless-api");
 
 const client = new TwilioServerlessApiClient({
-  accountSid: '...',
-  authToken: '...',
+  accountSid: "...",
+  authToken: "..."
 });
 
-client.on('status-update', evt => {
+client.on("status-update", evt => {
   console.log(evt.message);
 });
 
 const result = await client.deployLocalProject({
-  cwd: '...',
-  envPath: '...',
-  accountSid: '...',
-  authToken: '...',
+  cwd: "...",
+  envPath: "...",
+  accountSid: "...",
+  authToken: "...",
   env: {},
   pkgJson: {},
-  serviceName: 'serverless-example',
-  functionsEnv: 'dev',
-  assetsFolderName: 'static',
-  functionsFolderName: 'src',
+  serviceName: "serverless-example",
+  functionsEnv: "dev",
+  assetsFolderName: "static",
+  functionsFolderName: "src"
 });
 ```
 
@@ -116,23 +113,23 @@ Updates to the deployment will be emitted as events to status-update.
 const result = await client.deployProject({
   env: {},
   pkgJson: {},
-  serviceName: 'serverless-example',
-  functionsEnv: 'dev',
+  serviceName: "serverless-example",
+  functionsEnv: "dev",
   functions: [
     {
-      name: 'hello-world',
-      path: '/hello-world-path',
-      content: await readFile(path.join(__dirname, 'some-dir', 'handler.js')),
-      access: 'public',
-    },
+      name: "hello-world",
+      path: "/hello-world-path",
+      content: await readFile(path.join(__dirname, "some-dir", "handler.js")),
+      access: "public"
+    }
   ],
   assets: [
     {
-      name: 'image',
-      path: '/foo/image.jpg',
-      access: 'public',
-      content: await readFile(path.join(__dirname, 'another-dir', 'image.jpg')),
-    },
+      name: "image",
+      path: "/foo/image.jpg",
+      access: "public",
+      content: await readFile(path.join(__dirname, "another-dir", "image.jpg"))
+    }
   ]
 });
 ```
@@ -158,11 +155,11 @@ There's also a variety of small helper libraries that you can find more details
 You can consume them in two ways:
 
 ```js
-const { fsHelpers, api, utils } = require('@twilio-labs/serverless-api');
+const { fsHelpers, api, utils } = require("@twilio-labs/serverless-api");
 // or
-const fsHelpers = require('@twilio-labs/serverless-api/dist/utils/fs');
-const api = require('@twilio-labs/serverless-api/dist/api');
-const utils = require('@twilio-labs/serverless-api/dist/utils');
+const fsHelpers = require("@twilio-labs/serverless-api/dist/utils/fs");
+const api = require("@twilio-labs/serverless-api/dist/api");
+const utils = require("@twilio-labs/serverless-api/dist/utils");
 ```
 
 ## Contributing
@@ -193,6 +190,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 
 <!-- markdownlint-enable -->
 <!-- prettier-ignore-end -->
+
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
 This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!

packages/serverless-api/package.json

@@ -19,13 +19,20 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/twilio-labs/serverless-api.git"
+    "url": "https://github.com/twilio-labs/serverless-toolkit.git"
+  },
+  "homepage": "https://github.com/twilio-labs/serverless-toolkit",
+  "bugs": {
+    "url": "https://github.com/twilio-labs/serverless-toolkit/issues"
   },
   "keywords": [
     "twilio",
     "serverless"
   ],
-  "author": "Dominik Kundel <hi@dominik.dev> (https://dkundel.com)",
+  "author": "Twilio Inc. <open-source@twilio.com> (https://www.twilio.com/labs)",
+  "contributors": [
+    "Dominik Kundel <dkundel@twilio.com> (https://dkundel.com)"
+  ],
   "license": "MIT",
   "files": [
     "dist/",