particle-commands 0.3.0 → 0.4.0

package/.circleci/config.yml

@@ -0,0 +1,68 @@
+version: 2.1
+
+jobs:
+  run-tests:
+    parameters:
+      node-version:
+        type: string
+    docker:
+      - image: cimg/node:<< parameters.node-version >> # Primary execution image
+        auth:
+          username: $DOCKERHUB_USERNAME
+          password: $DOCKERHUB_PASSWORD
+    steps:
+      - checkout
+      - run:
+          name: NPM install
+          command: npm ci
+      - run:
+          name: Run tests with coverage
+          command: npm run test:ci
+  publish-npm:
+    docker:
+      - image: cimg/node:16.15.0 # Primary execution image
+        auth:
+          username: $DOCKERHUB_USERNAME
+          password: $DOCKERHUB_PASSWORD
+    steps:
+      - checkout
+      - run:
+          name: NPM install
+          command: npm ci
+      - run:
+          name: Authenticate with NPM
+          command: npm config set '//registry.npmjs.org/:_authToken' "${NPM_TOKEN}"
+      - run:
+          name: Publish package
+          command: |
+            # Publish as beta for pre-release tags like v1.2.3-pre.1
+            [[ $CIRCLE_TAG =~ ^v.*- ]] && NPM_TAG=--tag=beta
+            npm publish $NPM_TAG
+
+workflows:
+  version: 2
+  test-and-publish:
+    jobs:
+      - run-tests:
+          context:
+            - particle-ci-private
+          matrix:
+            parameters:
+              node-version: ["12.22.12", "14.19.2", "16.15.0"]
+          # run tests for all branches and tags
+          filters:
+            tags:
+              only: /^v.*/
+            branches:
+              only: /.*/
+      - publish-npm:
+          requires:
+            - run-tests
+          context:
+            - particle-ci-private
+          # publish for tags only
+          filters:
+            tags:
+              only: /^v.*/
+            branches:
+              ignore: /.*/

package/.nvmrc

@@ -0,0 +1 @@
+16

package/CHANGELOG.md

@@ -3,6 +3,9 @@
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+### 0.4.0 - 2022-05-31
+- Move to `node@16` and `npm@8` for local development
+
 ### 0.3.0 - 2018-09-06
 ### Change
 - revert changes for analytics

package/README.md

@@ -1,15 +1,94 @@
-# Particle Commands [![Build Status](https://travis-ci.org/spark/particle-commands.svg?branch=master)](https://travis-ci.org/spark/particle-commands)
+# Particle Commands 
 UX-neutral commands for developer tools
 
-# Release
+[![Build Status](https://circleci.com/gh/particle-iot/particle-commands.svg?style=shield)](https://app.circleci.com/pipelines/github/particle-iot/particle-commands)
 
-Run these commands to release
-```
-npm version <minor|major|patch>
-# update CHANGELOG.md
-git push --follow-tags
-npm publish
-```
+[Installation](#installation) | [Development](#development)  | [Conventions](#conventions) | [Docs](#docs--resources) | [Releasing](#releasing) | [License](#license)
 
-Then create a GitHub release
+## Installation
+1. Install Node.js [`node@16.x` and `npm@8.x` are required]
+1. Clone this repository `$ git clone git@github.com:particle-iot/particle-commands.git && cd ./particle-commands`
+1. Install dependencies `$ npm install`
+1. View available commands `$ npm run`
+1. Run the tests `$ npm test`
+1. Start Hacking!
 
+## Development
+
+All essential commands are available at the root via `npm run <script name>` - e.g. `npm run lint`. To view the available commands, run: `npm run`
+
+<details id="develop-run-tests">
+<summary><b>How to run your tests</b></summary>
+<p>
+
+to run the tests:
+
+`npm test`
+
+to run the coverage:
+
+`npm run coverage`
+
+</p>
+</details>
+
+
+<details id="develop-npm-scripts">
+<summary><b>How to name npm scripts</b></summary>
+<p>
+
+npm scripts are the primary means of executing programmatic tasks (e.g. tests, linting, releasing, etc) within the repo. to view available scripts, run `npm run`.
+
+when creating a new script, be sure it does not already exist and use the following naming convention:
+
+`<category>:[<subcategory>]:[<action>]`
+
+our standard categories include: `test`, `lint`, `build`, `clean`, `docs`, `package`, `dependencies`, and `release`. top-level scripts - e.g. `npm run clean` - will typically run all of its subcategories (e.g. `npm run clean:dist && npm run clean:tmp`).
+
+`npm` itself includes special handling for `test` and `start` (doc: [1](https://docs.npmjs.com/cli/v6/commands/npm-test), [2](https://docs.npmjs.com/cli/v6/commands/npm-start)) amongst other [lifecycle scripts](https://docs.npmjs.com/cli/v7/using-npm/scripts#life-cycle-scripts) - use these to expose key testing and start-up commands.
+
+sometimes your new script will be very similar to an existing script. in those cases, try to extend the existing script before adding another one.
+
+</p>
+</details>
+
+
+## Conventions
+
+* [npm scripts](https://docs.npmjs.com/misc/scripts) form the _developer's API_ for the repo and all of its packages - key orchestration commands should be exposed here
+* document developer-facing process / tooling instructions in the [Development](#development) section
+* plan to release your changes upon merging to `main` - refrain from merging if you cannot so you don't leave unpublished changes to others
+* avoid making changes in files unrelated to the work you are doing so you aren't having to publish trivial updates
+* test files live alongside their source files and are named like `*.test.js` or `*.spec.js`
+* if the linter does not flag your code (error or warning), it's formatted properly
+* avoid reformatting unflagged code as it can obscure more meaningful changes and increase the chance of merge conflicts
+* todo comments include your last name and are formatted like: `TODO (mirande): <message>`
+  
+## Docs & Resources
+
+* [Mocha](https://mochajs.org/)
+* [Chai](http://www.chaijs.com/api/bdd/)
+* [Sinon](https://sinonjs.org/)
+* [NYC](https://github.com/istanbuljs/nyc)
+
+## Releasing
+
+Packages are only released from the `main` branch after peer review.
+
+1. make sure you have the latest:
+	* `$ git checkout main`
+	* `$ git pull`
+1. make sure tests pass
+	* `$ npm test`
+1. run the version command
+	* `$ npm version <major|minor|patch>`
+	* This command will bump the current version of the library in the `package.json` file. Before the command finishes, update `CHANGELOG.md`.
+1. push your tags:
+	* `$ git push origin main --follow-tags`
+1. CircleCI will publish the npm package to the `latest` tag
+1. Create a release on GitHub with the notes from the `CHANGELOG.md`
+1. Point your project to the new version `npm install particle-commands@latest`
+
+## License
+
+Copyright &copy; 2016 Particle Industries, Inc. Released under the Apache 2.0 license. See [LICENSE](/LICENSE) for details.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "particle-commands",
   "description": "Library of UX-neutral commands that provide key functionality for developer tools",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "author": "Matthew McGowan",
   "bugs": {
-    "url": "https://github.com/spark/particle-commands/issues"
+    "url": "https://github.com/particle-iot/particle-commands/issues"
   },
   "contributors": [
     {
@@ -40,9 +40,9 @@
     "eslint": "~2.2.0",
     "eslint-config-particle": "^1.0.1",
     "fs-extra": "^0.30.0",
-    "istanbul": "^0.3.22",
     "mocha": "^3.0.2",
-    "mock-fs": "^3.12.1",
+    "mock-fs": "^5.1.2",
+    "nyc": "^15.1.0",
     "proxyquire": "^1.6.0",
     "rimraf-promise": "^2.0.0",
     "sinon": "^1.15.4",
@@ -52,10 +52,7 @@
     "testdouble-chai": "^0.2.2",
     "tmp": "0.0.28"
   },
-  "engines": {
-    "node": ">=0.10.40"
-  },
-  "homepage": "https://github.com/spark/particle-commands/",
+  "homepage": "https://github.com/particle-iot/particle-commands/",
   "keywords": [
     "cli",
     "core",
@@ -70,22 +67,27 @@
   "preferGlobal": false,
   "repository": {
     "type": "git",
-    "url": "https://github.com/spark/particle-commands"
+    "url": "https://github.com/particle-iot/particle-commands"
   },
   "scripts": {
-    "all": "npm run lint && npm run test && npm run accept",
+    "prepublish": "npm run compile",
+    "preversion": "npm run lint && npm run test && npm run prepublish",
+    "version": "npm run update-changelog",
+    "compile": "babel src -d dist --copy-files",
     "babel-watch": "babel src -d dist --watch --source-maps --copy-files",
-    "coverage": "istanbul cover ./node_modules/mocha/bin/_mocha -- -R spec test/ --compilers js:babel-register",
-    "coveralls": "istanbul cover ./node_modules/mocha/bin/_mocha --report lcovonly -- -R spec --compilers js:babel-register test/ && cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js && rm -rf ./coverage",
     "doctoc": "doctoc --title '## Table of Contents' README.md",
     "list-folders": "node --require babel-register bin/list_folders.js",
+    "test": "npm run lint && npm run test:unit",
+    "test:ci": "npm run lint && npm run test:unit -- --forbid-only && npm run coverage",
+    "test:unit": "mocha test test/cmd test/integration --compilers js:babel-register",
+    "test:unit:silent": "npm run test:unit > tmp/test-unit-log.txt 2>&1",
     "lint": "eslint -f unix src/**/*.js",
     "lint:fix": "eslint --fix -f unix src/ test/",
-    "test": "mocha test test/cmd test/integration --compilers js:babel-register",
-    "compile": "babel src -d dist --copy-files",
-    "prepublish": "npm run compile",
-    "preversion": "npm run lint && npm run test && npm run prepublish",
-    "version": "npm run update-changelog",
+    "coverage": "nyc --reporter=text --include='src/**/*.js' --temp-dir=./tmp/ --check-coverage --lines 50 npm run test:unit:silent",
     "update-changelog": "VERSION=`node -p -e \"require('./package.json').version\"` bash -c 'read -p \"Update CHANGELOG.md for version $VERSION and press ENTER when done.\"' && git add CHANGELOG.md"
+  },
+  "engines": {
+    "node": ">=12.x",
+    "npm": "8.x"
   }
 }

package/.idea/jsLibraryMappings.xml

@@ -1,6 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="JavaScriptLibraryMappings">
-    <includedPredefinedLibrary name="ECMAScript 6" />
-  </component>
-</project>

package/.idea/misc.xml

@@ -1,6 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="JavaScriptSettings">
-    <option name="languageLevel" value="ES6" />
-  </component>
-</project>

package/.idea/modules.xml

@@ -1,8 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="ProjectModuleManager">
-    <modules>
-      <module fileurl="file://$PROJECT_DIR$/.idea/particle-commands.iml" filepath="$PROJECT_DIR$/.idea/particle-commands.iml" />
-    </modules>
-  </component>
-</project>

package/.idea/particle-commands.iml

@@ -1,10 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<module type="WEB_MODULE" version="4">
-  <component name="NewModuleRootManager">
-    <content url="file://$MODULE_DIR$">
-      <excludeFolder url="file://$MODULE_DIR$/dist" />
-    </content>
-    <orderEntry type="inheritedJdk" />
-    <orderEntry type="sourceFolder" forTests="false" />
-  </component>
-</module>

package/.idea/vcs.xml

@@ -1,6 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="VcsDirectoryMappings">
-    <mapping directory="$PROJECT_DIR$" vcs="Git" />
-  </component>
-</project>

package/.idea/watcherTasks.xml

@@ -1,4 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="ProjectTasksOptions" suppressed-tasks="Babel" />
-</project>