{"action":"created","comment":{"url":"https://api.github.com/repos/FormidableLabs/builder/pulls/comments/43192538","id":43192538,"diff_hunk":"@@ -1 +1,263 @@\n-# builder\n+[![Travis Status][trav_img]][trav_site]\n+\n+Builder\n+=======\n+\n+Builder is a task runner.\n+\n+Builder is an enhancement to `npm run TASK`.\n+\n+Builder is a meta-tool for all your common build, quality, and test tasks.\n+\n+## Overview\n+\n+At a high level `builder` is a tool for consuming `package.json` `scripts`\n+commands, providing sensible / flexible defaults, and support various scenarios\n+(\"archetypes\") for your common use cases across multiple projects.\n+\n+Builder is not opinionated, although archetypes _are_ and typically dictate\n+file structure, standard configurations, and dev workflows. Builder supports\n+this in an agnostic way, providing essentially the following:\n+\n+* `NODE_PATH`, `PATH` enhancements to run, build, import from archetypes so\n+  dependencies and configurations don't have to be installed directly in a\n+  root project.\n+* A task runner capable of single tasks (`run`) or multiple concurrent tasks\n+  (`concurrent`).\n+* An intelligent merging of `package.json` `scripts` tasks.\n+\n+... and that's about it!\n+\n+### Usage\n+\n+To start using builder, install and save `builder` and any archetypes you\n+intend to use. For example, here we install `builder` and the\n+[builder-react-component][] archetype:\n+\n+```sh\n+$ npm install --save builder builder-react-component\n+```\n+\n+and then edit `.builderrc` like:\n+\n+```yaml\n+---\n+archetypes:\n+  - builder-react-component\n+```\n+\n+to add archetypes. At this point, `builder` can build any production tasks,\n+as only production `dependencies` of archetypes are installed. However, if\n+you are in a **development** or CI environment, an additional manual step\n+is needed to install the `devDependencies` of all the archetypes:\n+\n+```sh\n+$ builder install\n+```\n+\n+#### Builder Commands\n+\n+Display help.\n+\n+```sh\n+$ builder help\n+```\n+\n+Install archetype `devDependencies`.\n+\n+```sh\n+$ builder install\n+```\n+\n+Run a single `package.json` `scripts` task.\n+\n+```sh\n+$ builder run foo-task\n+```\n+\n+Run multiple `package.json` `scripts` tasks.\n+\n+```sh\n+$ builder concurrent foo-task bar-task baz-task\n+```\n+\n+\n+## Tasks\n+\n+The underyling concept here is that `builder` `script` commands simply _are_\n+NPM-friendly `package.json` `script` commands. Pretty much anything that you\n+can execute with `npm run FOO` can be executed with `builder run FOO`.\n+\n+Builder can run 1+ tasks based out of `package.json` `scripts`. For a basic\n+scenario like:\n+\n+```js\n+{\n+  \"scripts\": {\n+    \"foo\": \"echo FOO\",\n+    \"bar\": \"echo BAR\"\n+  }\n+}\n+```\n+\n+Builder can run these tasks individually:\n+\n+```sh\n+$ builder run foo\n+$ builder run bar\n+```\n+\n+Sequentially via `||` or `&&` shell helpers:\n+\n+```sh\n+$ builder run foo && builder run bar\n+```\n+\n+Concurrently via the Builder built-in `concurrent` command:\n+\n+```sh\n+$ builder concurrent foo bar\n+```\n+\n+With `concurrent`, all tasks continue running until they all complete _or_\n+any task exits with a non-zero exit code, in which case all still alive tasks\n+are killed and the Builder process exits with the error code.\n+\n+## Archetypes\n+\n+Archetypes deal with common scenarios for your projects. Like:\n+\n+* [builder-react-component][]: A React component\n+* A React application server\n+* A Chai / jQuery / VanillaJS widget\n+\n+Archetypes typically provide:\n+\n+* A `package.json` with `builder`-friendly `script` tasks.\n+* Dependencies and dev dependencies to build, test, etc.\n+* Configuration files for all `script` tasks.\n+\n+In most cases, you won't need to override anything. But, if you do, pick the\n+most granular `scripts` command in the archetype you need to override and\n+define _just that_ in your project's `package.json` `script` section. Copy\n+any configuration files that you need to tweak and re-define the command.\n+\n+### Task Resolution\n+\n+The easiest bet is to just have _one_ archetype per project. But, multiple are\n+supported. In terms of `scripts` tasks, we end up with the following example:\n+\n+```\n+ROOT/package.json\n+ROOT/node_modules/ARCHETYPE_ONE/package.json\n+ROOT/node_modules/ARCHETYPE_TWO/package.json\n+```\n+\n+Say we have a `.builderrc` like:\n+\n+```yaml\n+---\n+archetypes:\n+  - ARCHETYPE_ONE\n+  - ARCHETYPE_TWO\n+```\n+\n+The resolution order for a `script` task (say, `foo`) present in all three\n+`package.json`'s would be the following:\n+\n+* Look through `ROOT/package.json` then the configured archetypes in _reverse_\n+  order: `ARCHETYPE_TWO/package.json`, then `ARCHETYPE_ONE/package.json` for\n+  a matching task `foo`\n+* If found `foo`, check if it is a \"passthrough\" task, which means it delegates\n+  to a later instance -- basically `\"foo\": \"builder run foo\"`. If so, then look\n+  to next instance of task found in order above.\n+\n+### Special Archetype Tasks\n+\n+Archetypes use conventional `scripts` task names, except for the following\n+special cases:\n+\n+* `\"npm:postinstall\"`\n+* `\"npm:preversion\"`\n+* `\"npm:version\"`\n+* `\"npm:test\"`\n+\n+These tasks are specifically actionable during the `npm` lifecycle, and","path":"README.md","position":186,"original_position":186,"commit_id":"75468aef34856bbfe41dca9f4e840f5033eec054","original_commit_id":"75468aef34856bbfe41dca9f4e840f5033eec054","user":{"login":"chaseadamsio","id":1024544,"avatar_url":"https://avatars.githubusercontent.com/u/1024544?v=3","gravatar_id":"","url":"https://api.github.com/users/chaseadamsio","html_url":"https://github.com/chaseadamsio","followers_url":"https://api.github.com/users/chaseadamsio/followers","following_url":"https://api.github.com/users/chaseadamsio/following{/other_user}","gists_url":"https://api.github.com/users/chaseadamsio/gists{/gist_id}","starred_url":"https://api.github.com/users/chaseadamsio/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/chaseadamsio/subscriptions","organizations_url":"https://api.github.com/users/chaseadamsio/orgs","repos_url":"https://api.github.com/users/chaseadamsio/repos","events_url":"https://api.github.com/users/chaseadamsio/events{/privacy}","received_events_url":"https://api.github.com/users/chaseadamsio/received_events","type":"User","site_admin":false},"body":"Not doing it this way in `bolt` caused me a lot of headache...this is a great convention.","created_at":"2015-10-27T21:48:31Z","updated_at":"2015-10-27T21:48:31Z","html_url":"https://github.com/FormidableLabs/builder/pull/5#discussion_r43192538","pull_request_url":"https://api.github.com/repos/FormidableLabs/builder/pulls/5","_links":{"self":{"href":"https://api.github.com/repos/FormidableLabs/builder/pulls/comments/43192538"},"html":{"href":"https://github.com/FormidableLabs/builder/pull/5#discussion_r43192538"},"pull_request":{"href":"https://api.github.com/repos/FormidableLabs/builder/pulls/5"}}},"pull_request":{"url":"https://api.github.com/repos/FormidableLabs/builder/pulls/5","id":48667658,"html_url":"https://github.com/FormidableLabs/builder/pull/5","diff_url":"https://github.com/FormidableLabs/builder/pull/5.diff","patch_url":"https://github.com/FormidableLabs/builder/pull/5.patch","issue_url":"https://api.github.com/repos/FormidableLabs/builder/issues/5","number":5,"state":"open","locked":false,"title":"Chore: initial implementation","user":{"login":"ryan-roemer","id":445557,"avatar_url":"https://avatars.githubusercontent.com/u/445557?v=3","gravatar_id":"","url":"https://api.github.com/users/ryan-roemer","html_url":"https://github.com/ryan-roemer","followers_url":"https://api.github.com/users/ryan-roemer/followers","following_url":"https://api.github.com/users/ryan-roemer/following{/other_user}","gists_url":"https://api.github.com/users/ryan-roemer/gists{/gist_id}","starred_url":"https://api.github.com/users/ryan-roemer/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ryan-roemer/subscriptions","organizations_url":"https://api.github.com/users/ryan-roemer/orgs","repos_url":"https://api.github.com/users/ryan-roemer/repos","events_url":"https://api.github.com/users/ryan-roemer/events{/privacy}","received_events_url":"https://api.github.com/users/ryan-roemer/received_events","type":"User","site_admin":false},"body":"Tickets\r\n\r\n* Fixes #1 \"builder executable\"\r\n* Fixes #2 \"pass env information\"\r\n* Fixes #3 \"concurrent\"\r\n\r\nNotes\r\n\r\n* Implements builder executable (very simple)\r\n* Implements underlying library / abstractions\r\n\r\nRelated PRs:\r\n\r\n* `builder`: https://github.com/FormidableLabs/builder/pull/5\r\n* `builder-react-component`: https://github.com/FormidableLabs/builder-react-component/pull/2\r\n* `formidable-react-component-boilerplate`: https://github.com/FormidableLabs/formidable-react-component-boilerplate/pull/52\r\n\r\nTasks:\r\n\r\n* [x] Ferret out and remove all `TODO`'s.\r\n* [x] Abstract the archetype selection / ingestion.\r\n\r\n/cc @boygirl @exogen @kenwheeler @chaseadamsio","created_at":"2015-10-24T23:17:21Z","updated_at":"2015-10-27T21:48:31Z","closed_at":null,"merged_at":null,"merge_commit_sha":"2c6c2970e9f307a3abd8fdd8e96a6e0670e1db9e","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/FormidableLabs/builder/pulls/5/commits","review_comments_url":"https://api.github.com/repos/FormidableLabs/builder/pulls/5/comments","review_comment_url":"https://api.github.com/repos/FormidableLabs/builder/pulls/comments{/number}","comments_url":"https://api.github.com/repos/FormidableLabs/builder/issues/5/comments","statuses_url":"https://api.github.com/repos/FormidableLabs/builder/statuses/75468aef34856bbfe41dca9f4e840f5033eec054","head":{"label":"FormidableLabs:chore-initial-implementation","ref":"chore-initial-implementation","sha":"75468aef34856bbfe41dca9f4e840f5033eec054","user":{"login":"FormidableLabs","id":5078602,"avatar_url":"https://avatars.githubusercontent.com/u/5078602?v=3","gravatar_id":"","url":"https://api.github.com/users/FormidableLabs","html_url":"https://github.com/FormidableLabs","followers_url":"https://api.github.com/users/FormidableLabs/followers","following_url":"https://api.github.com/users/FormidableLabs/following{/other_user}","gists_url":"https://api.github.com/users/FormidableLabs/gists{/gist_id}","starred_url":"https://api.github.com/users/FormidableLabs/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/FormidableLabs/subscriptions","organizations_url":"https://api.github.com/users/FormidableLabs/orgs","repos_url":"https://api.github.com/users/FormidableLabs/repos","events_url":"https://api.github.com/users/FormidableLabs/events{/privacy}","received_events_url":"https://api.github.com/users/FormidableLabs/received_events","type":"Organization","site_admin":false},"repo":{"id":44566613,"name":"builder","full_name":"FormidableLabs/builder","owner":{"login":"FormidableLabs","id":5078602,"avatar_url":"https://avatars.githubusercontent.com/u/5078602?v=3","gravatar_id":"","url":"https://api.github.com/users/FormidableLabs","html_url":"https://github.com/FormidableLabs","followers_url":"https://api.github.com/users/FormidableLabs/followers","following_url":"https://api.github.com/users/FormidableLabs/following{/other_user}","gists_url":"https://api.github.com/users/FormidableLabs/gists{/gist_id}","starred_url":"https://api.github.com/users/FormidableLabs/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/FormidableLabs/subscriptions","organizations_url":"https://api.github.com/users/FormidableLabs/orgs","repos_url":"https://api.github.com/users/FormidableLabs/repos","events_url":"https://api.github.com/users/FormidableLabs/events{/privacy}","received_events_url":"https://api.github.com/users/FormidableLabs/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/FormidableLabs/builder","description":"","fork":false,"url":"https://api.github.com/repos/FormidableLabs/builder","forks_url":"https://api.github.com/repos/FormidableLabs/builder/forks","keys_url":"https://api.github.com/repos/FormidableLabs/builder/keys{/key_id}","collaborators_url":"https://api.github.com/repos/FormidableLabs/builder/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/FormidableLabs/builder/teams","hooks_url":"https://api.github.com/repos/FormidableLabs/builder/hooks","issue_events_url":"https://api.github.com/repos/FormidableLabs/builder/issues/events{/number}","events_url":"https://api.github.com/repos/FormidableLabs/builder/events","assignees_url":"https://api.github.com/repos/FormidableLabs/builder/assignees{/user}","branches_url":"https://api.github.com/repos/FormidableLabs/builder/branches{/branch}","tags_url":"https://api.github.com/repos/FormidableLabs/builder/tags","blobs_url":"https://api.github.com/repos/FormidableLabs/builder/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/FormidableLabs/builder/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/FormidableLabs/builder/git/refs{/sha}","trees_url":"https://api.github.com/repos/FormidableLabs/builder/git/trees{/sha}","statuses_url":"https://api.github.com/repos/FormidableLabs/builder/statuses/{sha}","languages_url":"https://api.github.com/repos/FormidableLabs/builder/languages","stargazers_url":"https://api.github.com/repos/FormidableLabs/builder/stargazers","contributors_url":"https://api.github.com/repos/FormidableLabs/builder/contributors","subscribers_url":"https://api.github.com/repos/FormidableLabs/builder/subscribers","subscription_url":"https://api.github.com/repos/FormidableLabs/builder/subscription","commits_url":"https://api.github.com/repos/FormidableLabs/builder/commits{/sha}","git_commits_url":"https://api.github.com/repos/FormidableLabs/builder/git/commits{/sha}","comments_url":"https://api.github.com/repos/FormidableLabs/builder/comments{/number}","issue_comment_url":"https://api.github.com/repos/FormidableLabs/builder/issues/comments{/number}","contents_url":"https://api.github.com/repos/FormidableLabs/builder/contents/{+path}","compare_url":"https://api.github.com/repos/FormidableLabs/builder/compare/{base}...{head}","merges_url":"https://api.github.com/repos/FormidableLabs/builder/merges","archive_url":"https://api.github.com/repos/FormidableLabs/builder/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/FormidableLabs/builder/downloads","issues_url":"https://api.github.com/repos/FormidableLabs/builder/issues{/number}","pulls_url":"https://api.github.com/repos/FormidableLabs/builder/pulls{/number}","milestones_url":"https://api.github.com/repos/FormidableLabs/builder/milestones{/number}","notifications_url":"https://api.github.com/repos/FormidableLabs/builder/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/FormidableLabs/builder/labels{/name}","releases_url":"https://api.github.com/repos/FormidableLabs/builder/releases{/id}","created_at":"2015-10-19T22:00:13Z","updated_at":"2015-10-27T18:08:42Z","pushed_at":"2015-10-27T18:24:10Z","git_url":"git://github.com/FormidableLabs/builder.git","ssh_url":"git@github.com:FormidableLabs/builder.git","clone_url":"https://github.com/FormidableLabs/builder.git","svn_url":"https://github.com/FormidableLabs/builder","homepage":null,"size":232,"stargazers_count":1,"watchers_count":1,"language":null,"has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":6,"forks":0,"open_issues":6,"watchers":1,"default_branch":"master"}},"base":{"label":"FormidableLabs:master","ref":"master","sha":"8b2ad286f959fbfadcd699f765415bf518285e5d","user":{"login":"FormidableLabs","id":5078602,"avatar_url":"https://avatars.githubusercontent.com/u/5078602?v=3","gravatar_id":"","url":"https://api.github.com/users/FormidableLabs","html_url":"https://github.com/FormidableLabs","followers_url":"https://api.github.com/users/FormidableLabs/followers","following_url":"https://api.github.com/users/FormidableLabs/following{/other_user}","gists_url":"https://api.github.com/users/FormidableLabs/gists{/gist_id}","starred_url":"https://api.github.com/users/FormidableLabs/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/FormidableLabs/subscriptions","organizations_url":"https://api.github.com/users/FormidableLabs/orgs","repos_url":"https://api.github.com/users/FormidableLabs/repos","events_url":"https://api.github.com/users/FormidableLabs/events{/privacy}","received_events_url":"https://api.github.com/users/FormidableLabs/received_events","type":"Organization","site_admin":false},"repo":{"id":44566613,"name":"builder","full_name":"FormidableLabs/builder","owner":{"login":"FormidableLabs","id":5078602,"avatar_url":"https://avatars.githubusercontent.com/u/5078602?v=3","gravatar_id":"","url":"https://api.github.com/users/FormidableLabs","html_url":"https://github.com/FormidableLabs","followers_url":"https://api.github.com/users/FormidableLabs/followers","following_url":"https://api.github.com/users/FormidableLabs/following{/other_user}","gists_url":"https://api.github.com/users/FormidableLabs/gists{/gist_id}","starred_url":"https://api.github.com/users/FormidableLabs/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/FormidableLabs/subscriptions","organizations_url":"https://api.github.com/users/FormidableLabs/orgs","repos_url":"https://api.github.com/users/FormidableLabs/repos","events_url":"https://api.github.com/users/FormidableLabs/events{/privacy}","received_events_url":"https://api.github.com/users/FormidableLabs/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/FormidableLabs/builder","description":"","fork":false,"url":"https://api.github.com/repos/FormidableLabs/builder","forks_url":"https://api.github.com/repos/FormidableLabs/builder/forks","keys_url":"https://api.github.com/repos/FormidableLabs/builder/keys{/key_id}","collaborators_url":"https://api.github.com/repos/FormidableLabs/builder/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/FormidableLabs/builder/teams","hooks_url":"https://api.github.com/repos/FormidableLabs/builder/hooks","issue_events_url":"https://api.github.com/repos/FormidableLabs/builder/issues/events{/number}","events_url":"https://api.github.com/repos/FormidableLabs/builder/events","assignees_url":"https://api.github.com/repos/FormidableLabs/builder/assignees{/user}","branches_url":"https://api.github.com/repos/FormidableLabs/builder/branches{/branch}","tags_url":"https://api.github.com/repos/FormidableLabs/builder/tags","blobs_url":"https://api.github.com/repos/FormidableLabs/builder/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/FormidableLabs/builder/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/FormidableLabs/builder/git/refs{/sha}","trees_url":"https://api.github.com/repos/FormidableLabs/builder/git/trees{/sha}","statuses_url":"https://api.github.com/repos/FormidableLabs/builder/statuses/{sha}","languages_url":"https://api.github.com/repos/FormidableLabs/builder/languages","stargazers_url":"https://api.github.com/repos/FormidableLabs/builder/stargazers","contributors_url":"https://api.github.com/repos/FormidableLabs/builder/contributors","subscribers_url":"https://api.github.com/repos/FormidableLabs/builder/subscribers","subscription_url":"https://api.github.com/repos/FormidableLabs/builder/subscription","commits_url":"https://api.github.com/repos/FormidableLabs/builder/commits{/sha}","git_commits_url":"https://api.github.com/repos/FormidableLabs/builder/git/commits{/sha}","comments_url":"https://api.github.com/repos/FormidableLabs/builder/comments{/number}","issue_comment_url":"https://api.github.com/repos/FormidableLabs/builder/issues/comments{/number}","contents_url":"https://api.github.com/repos/FormidableLabs/builder/contents/{+path}","compare_url":"https://api.github.com/repos/FormidableLabs/builder/compare/{base}...{head}","merges_url":"https://api.github.com/repos/FormidableLabs/builder/merges","archive_url":"https://api.github.com/repos/FormidableLabs/builder/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/FormidableLabs/builder/downloads","issues_url":"https://api.github.com/repos/FormidableLabs/builder/issues{/number}","pulls_url":"https://api.github.com/repos/FormidableLabs/builder/pulls{/number}","milestones_url":"https://api.github.com/repos/FormidableLabs/builder/milestones{/number}","notifications_url":"https://api.github.com/repos/FormidableLabs/builder/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/FormidableLabs/builder/labels{/name}","releases_url":"https://api.github.com/repos/FormidableLabs/builder/releases{/id}","created_at":"2015-10-19T22:00:13Z","updated_at":"2015-10-27T18:08:42Z","pushed_at":"2015-10-27T18:24:10Z","git_url":"git://github.com/FormidableLabs/builder.git","ssh_url":"git@github.com:FormidableLabs/builder.git","clone_url":"https://github.com/FormidableLabs/builder.git","svn_url":"https://github.com/FormidableLabs/builder","homepage":null,"size":232,"stargazers_count":1,"watchers_count":1,"language":null,"has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":6,"forks":0,"open_issues":6,"watchers":1,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/FormidableLabs/builder/pulls/5"},"html":{"href":"https://github.com/FormidableLabs/builder/pull/5"},"issue":{"href":"https://api.github.com/repos/FormidableLabs/builder/issues/5"},"comments":{"href":"https://api.github.com/repos/FormidableLabs/builder/issues/5/comments"},"review_comments":{"href":"https://api.github.com/repos/FormidableLabs/builder/pulls/5/comments"},"review_comment":{"href":"https://api.github.com/repos/FormidableLabs/builder/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/FormidableLabs/builder/pulls/5/commits"},"statuses":{"href":"https://api.github.com/repos/FormidableLabs/builder/statuses/75468aef34856bbfe41dca9f4e840f5033eec054"}}}}