Add new v4 section and table of contents

README.md

@@ -10,6 +10,19 @@ Publish Roku projects to a Roku device by using Node.js.
 [![npm version](https://img.shields.io/npm/v/roku-deploy.svg?logo=npm)](https://www.npmjs.com/package/roku-deploy)
 [![license](https://img.shields.io/github/license/rokucommunity/roku-deploy.svg)](LICENSE)
 [![Slack](https://img.shields.io/badge/Slack-RokuCommunity-4A154B?logo=slack)](https://join.slack.com/t/rokudevelopers/shared_invite/zt-4vw7rg6v-NH46oY7hTktpRIBM_zGvwA)
+
+### Table of Contents
+- [Installation](#installation)
+- [Requirements](#requirements)
+- [Upgrading to V4](#upgrading-to-v4)
+- [CLI Usage](#cli-usage)
+- [JavaScript Usage](#javascript-usage)
+- [roku-deploy JSON](#roku-deploy-json)
+- [Files Array](#files-array)
+- [roku-deploy Options](#roku-deploy-options)
+- [Troubleshooting](#troubleshooting)
+- [Changelog](#changelog)
+
 ## Installation
 
     npm install roku-deploy
@@ -22,6 +35,8 @@ Publish Roku projects to a Roku device by using Node.js.
     images/
     source/
     manifest
+    locale/
+    fonts/
 
 2. You should create a rokudeploy.json file at the root of your project that contains all of the overrides to the default options. roku-deploy will auto-detect this file and use it when possible. (**note**: `rokudeploy.json` is jsonc, which means it supports comments).
 
@@ -33,6 +48,26 @@ sample rokudeploy.json
     "password": "securePassword"
 }
 ```
+
+## Upgrading to V4
+The new release has a few breaking changes that is worth going over in order to prepare developers for what they will need to change when they choose to upgrade.
+
+The first is that the Node API no longer loads user-specified defaults from the config file. The config file is only used in the CLI commands. This process will only check `roku-deploy.json`, as bsconfig.json is no longer supported. The order of priority goes: if there are arguments in the CLI command, those are used. If some are missing, roku-deploy.json values are used. If there is no JSON or there are some values that are required for the CLI command but not available in the JSON or the CLI arguments, a set of predetermined default values are used. These can be found in the section titled [roku-deploy Options](#roku-deploy-options).
+
+Another set of changes are the names and features available in the Node API. Some have been renamed and others have been change to be used only as CLI commands in order to organize and simplify what is offered. Renamed functions:
+- `zipPackage()` -> `zip()`
+- `pressHomeButton()` -> `closeChannel()` which will press home twice in order to cancel instant resume
+- `publish()` -> `sideload()`
+- `signExistingPackage()` -> `createSignedPackage()`
+- `deleteInstalledChannel()` -> `deleteDevChannel()`
+- `takeScreenshot()` -> `captureScreenshot()`
+
+Some functions were added which allow for any remote-to-Roku interaction: `keyPress()`, `keyUp()`, `keyDown()`, and `sendText()`
+
+Previously, functions `deploy()`, `createPackage()`, and `deployAndSignPackage()` were available in the Node API, but have been moved to CLI commands.
+
+Lastly, the default files array has changed. node modules and static analysis files have been excluded to speed up load times. Also, `fonts/` and `locale/` was added as they are in a few Roku documentation. The new default array can be seen in the section titled [Files Array](#files-array)
+
 ## CLI Usage
 
 ### Deploy a zip package
@@ -97,7 +132,9 @@ rokuDeploy.stage({
         "source/**/*",
         "components/**/*",
         "images/**/*",
-        "manifest"
+        "manifest",
+        "locale/**/*",
+        "fonts/**/*"
     ],
     //...other options if necessary
 }).then(function(){
@@ -200,7 +237,7 @@ From an npm script in `package.json`. (Requires `rokudeploy.json` to exist at th
         }
     }
 
-## roku-deploy.json
+## roku-deploy JSON
 As stated, many of the config settings are loaded from `roku-deploy.json`. Here is the loading order:
  - if CLI arguments are found, those are used.
  - if `roku-deploy.json` is found, fill in any missing settings.
@@ -218,10 +255,14 @@ For most standard projects, the default files array should work just fine:
 ```jsonc
 {
     "files": [
-        "source/**/*",
-        "components/**/*",
-        "images/**/*",
-        "manifest"
+        "source/**/*.*",
+        "components/**/*.*",
+        "images/**/*.*",
+        "locale/**/*",
+        "fonts/**/*",
+        "manifest",
+        "!node_modules",
+        "!**/*.{md,DS_Store,db}"
     ]
 }
 ```
@@ -233,12 +274,16 @@ If you want to include additonal files, you will need to provide the entire arra
 ```jsonc
 {
     "files": [
-        "source/**/*",
-        "components/**/*",
-        "images/**/*",
-        "manifest"
+        "source/**/*.*",
+        "components/**/*.*",
+        "images/**/*.*",
+        "locale/**/*",
+        "fonts/**/*",
+        "manifest",
+        "!node_modules",
+        "!**/*.{md,DS_Store,db}",
         //your folder with other assets
-        "assets/**/*",
+        "assets/**/*"
     ]
 }
 ```
@@ -334,26 +379,25 @@ For example, if you have a base project, and then a child project that wants to
 Here are the available options. The defaults are shown to the right of the option name, but all can be overridden:
 
 - **host:** string (*required*)
-    The IP address or hostname of the target Roku device. Example: `"192.168.1.21"`
+    The IP address or hostname of the target Roku device. Example: `"192.168.1.21"`.
 
 - **password:** string (*required*)
-    The password for logging in to the developer portal on the target Roku device
+    The password for logging in to the developer portal on the target Roku device.
 
 - **signingPassword:** string (*required for signing*)
-    The password used for creating signed packages
+    The password used for creating signed packages.
 
 - **rekeySignedPackage:** string (*required for rekeying*)
-    Path to a copy of the signed package you want to use for rekeying
+    Path to a copy of the signed package you want to use for rekeying.
 
 - **devId:** string
-    Dev ID we are expecting the device to have. If supplied we check that the dev ID returned after keying matches what we expected
-
+    Dev ID we are expecting the device to have. If supplied we check that the dev ID returned after keying matches what we expected.
 
 - **outDir?:** string = `"./out"`
-    A full path to the folder where the zip/pkg package should be placed
+    A full path to the folder where the zip/pkg package should be placed.
 
 - **outFile?:** string = `"roku-deploy"`
-    The base filename the zip/pkg file should be given (excluding the extension)
+    The base filename the zip/pkg file should be given (excluding the extension).
 
 - **rootDir?:** string = `'./'`
     The root path to the folder holding your project. The manifest file should be directly underneath this folder. Use this option when your roku project is in a subdirectory of where roku-deploy is installed.
@@ -364,7 +408,11 @@ Here are the available options. The defaults are shown to the right of the optio
         "source/**/*.*",
         "components/**/*.*",
         "images/**/*.*",
-        "manifest"
+        "locale/**/*",
+        "fonts/**/*",
+        "manifest",
+        "!node_modules",
+        "!**/*.{md,DS_Store,db}"
     ]
     ```
     An array of file paths, globs, or `{ src: string; dest: string }` objects that will be copied into the deployment package. Make sure to _exclusively_ use forward slashes ( `/` ) for path separators (even on Windows), as backslashes are reserved for character escaping. You can learn more about this requirement [here](https://www.npmjs.com/package/fast-glob?activeTab=readme#how-to-write-patterns-on-windows).
@@ -405,27 +453,36 @@ Here are the available options. The defaults are shown to the right of the optio
    The path to the staging folder (where roku-deploy places all of the files right before zipping them up).
 
 - **convertToSquashfs?:** boolean = `false`
-   If true we convert to squashfs before creating the pkg file
-
-- **incrementBuildNumber?:** boolean = `false`
-    If true we increment the build number to be a timestamp in the format yymmddHHMM
+   If true we convert to squashfs before creating the pkg file.
 
 - **username?:** string = `"rokudev"`
     The username for the roku box. This will always be 'rokudev', but allow to be passed in
-    just in case roku adds support for custom usernames in the future
+    just in case roku adds support for custom usernames in the future.
 
-- **packagePort?:** string = 80
+- **packagePort?:** number = `80`
     The port used for package-related requests. This is mainly used for things like emulators, or when your roku is behind a firewall with a port-forward.
 
-- **remotePort?:** string = 8060
+- **remotePort?:** number = `8060`
     The port used for sending remote control commands (like home press or back press). This is mainly used for things like emulators, or when your roku is behind a firewall with a port-forward.
 
-- **remoteDebug?:** boolean = false
+- **screenshotDir?:** string = `"./tmp/roku-deploy/screenshots/"`
+    The directory where screenshots should be saved. Will use the OS temp directory by default.
+
+- **timeout?:** number = `150000`
+    The number of milliseconds at which point this request should timeout and return a rejected promise.
+
+- **remoteDebug?:** boolean = `false`
      When publishing a side loaded channel this flag can be used to enable the socket based BrightScript debug protocol. This should always be `false` unless you're creating a plugin for an editor such as VSCode, Atom, Sublime, etc.
      More information on the BrightScript debug protocol can be found here: https://developer.roku.com/en-ca/docs/developer-program/debugging/socket-based-debugger.md
 
-- **deleteInstalledChannel?:** boolean = true
-    If true the previously installed dev channel will be deleted before installing the new one
+- **cwd?:** string = `process.cwd()`
+    The current working directory, which all other paths will be set relative to. If left to default, it will be set as the process.cwd() method, which returns the current working directory of the Node.js process.
+
+- **deleteDevChannel?:** boolean = `true`
+    If true the previously installed dev channel will be deleted before installing the new one.
+
+- **packageUploadOverrides?:**
+    Overrides for values used during the zip upload process. You probably don't need to change these...
 
 
 Click [here](https://github.com/rokucommunity/roku-deploy/blob/8e1cbdfcccb38dad4a1361277bdaf5484f1c2bcd/src/RokuDeploy.ts#L897) to see the typescript interface for these options

src/RokuDeployOptions.ts

@@ -6,11 +6,6 @@ export interface RokuDeployOptions {
      */
     cwd?: string;
 
-    /**
-     * Path to a bsconfig.json project file
-     */
-    project?: string;
-
     /**
      * A full path to the folder where the zip/pkg package should be placed
      * @default './out'