finish up docs, add changelog, resolve with spawnArgs

CHANGELOG.md

@@ -0,0 +1,7 @@
+Change Log
+===
+
+v0.2.0
+---
+* add Node API to readme
+* `yarpm` now resolves the promise with the argument list passed to spawn instead of the list passed to `yarpm`

README.md

@@ -1,5 +1,5 @@
 # yarpm
-A CLI tool to run npm scripts with either npm or yarn, depending on how it was started. Useful for setups where
+A CLI tool to run npm scripts with either `npm` or `yarn`, depending on how it was started. Useful for setups where
 some team members use `npm` while others use `yarn`.
 
 This tool is a helper to run scripts from `package.json`. Just substitute all `npm` or `yarn` calls with `yarpm`
@@ -42,8 +42,8 @@ yarn run v0.21.3
 error No command specified.
 ....
 ```
-This is due to the fact that `yarn` doesn't understand the `-s` option. This is up to you to write your scripts in
-a way that is compatible to both, `npm` and `yarn`.
+This is due to the fact that `yarn` doesn't understand the `-s` option. This is up to you to write your scripts so
+ that only commands and options available to both `npm` and `yarn` are used.
 
 ## Installation
 
@@ -53,8 +53,6 @@ $ npm install yarpm --save-dev
 $ yarn add yarpm --dev
 ```
 
-- The `yarpm` package introduces 2 CLI commands: `yarpm` and `yarpm-yarn`.
-
 ## CLI Commands
 
 This `yarpm` package provides 2 CLI commands.
@@ -65,10 +63,10 @@ This `yarpm` package provides 2 CLI commands.
 The main command is `yarpm`.
 
 ### yarpm
-This command is an in-place substitute places in `package.json` where `npm` or `yarn` is being explicitly used. It reads
-the `npm_execpath` environment variable to determine the path to the currently used package manager. This env var is
-only set when running `yarpm` as a script. If `yarpm` is used without being embedded in a script, it will **always**
-choose `npm`.
+This command is an in-place substitute for places in `package.json` where `npm` or `yarn` is being used explicitly.
+It reads the `npm_execpath` environment variable to determine the path to the currently used package manager. This env
+var is only set when running `yarpm` as a script. If `yarpm` is used without being embedded in a script, it will
+**always** choose `npm`.
 
 ### yarpm-yarn
 This command can be used in places where you are not in control of how your script is being started, for example when
@@ -80,11 +78,57 @@ available. Only then will it fall back to `npm`.
 
 The `yarpm` package provides a node API.
 
-- ***TODO***
+```js
+const yarpm = require('yarpm');
+const promise = yarpm(argv, options);
+```
+
+- **argv** `string[]` -- The argument list to pass to npm/yarn.
+- **options** `object|undefined`
+  - **options.npmPath** `string` -
+    The path to npm/yarn.
+    Default is `process.env.npm_execpath` if set, `npm` otherwise.
+  - **options.env** `object` -
+    Sets the environment key-value pairs, replaces the default usage of process.env to spawn child process.
+  - **options.stdin** `stream.Readable|null` --
+    A readable stream to send messages to stdin of child process.
+    If this is `null` or `undefined`, ignores it.
+    If this is `process.stdin`, inherits it.
+    Otherwise, makes a pipe.
+    Default is `null`.
+    Set to `process.stdin` in order to send from stdin.
+  - **options.stdout** `stream.Writable|null` --
+    A writable stream to receive messages from stdout of child process.
+    If this is `null` or `undefined`, cannot send.
+    If this is `process.stdout`, inherits it.
+    Otherwise, makes a pipe.
+    Default is `null`.
+    Set to `process.stdout` in order to print to stdout.
+  - **options.stderr** `stream.Writable|null` --
+    A writable stream to receive messages from stderr of child process.
+    If this is `null` or `undefined`, cannot send.
+    If this is `process.stderr`, inherits it.
+    Otherwise, makes a pipe.
+    Default is `null`.
+    Set to `process.stderr` in order to print to stderr.
+
+`yarpm` returns a promise that will becomes *fulfilled* when the spawned process exits ***regardless of the exit code***.
+The promise will become *rejected* when in case of an internal error inside of `yarpm`.
+
+The promise fulfills with an object with the following 2 properties: `argv` and `code`.
+The `spawnArgs` property is the array arguments that was passed to spawn the sub-process.
+The `code` property is the exit code of the sub-process.
+
+```js
+yarpm(['install']).then(result => {
+  console.log(`${result.spawnArgs} -- ${result.code}`);
+  // if executed as a package.json script via yarn: /usr/share/yarn/bin/yarn.js,install -- 0
+});
+```
 
 ## Changelog
 
-- ***TODO***
+https://github.com/BendingBender/yarpm/blob/master/CHANGELOG.md
 
 ## Contributing
 
@@ -93,3 +137,6 @@ Thank you for contributing!
 ### Bug Reports or Feature Requests
 
 Please use GitHub Issues.
+
+## License
+[MIT](https://github.com/BendingBender/yarpm/blob/master/LICENSE)

lib/index.js

@@ -79,7 +79,7 @@ module.exports = function yarpm(argv, options) {
     });
     cp.on('close', code => {
       cp = null;
-      resolve({argv, code});
+      resolve({spawnArgs, code});
     });
   });
 };

package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarpm",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "CLI tool to run npm scripts with either npm or yarn, depending on how it was started",
   "bin": {
     "yarpm": "bin/yarpm.js",