Merge pull request #2 from geeklearningio/feature/npm-package

Npm Package

Author: sandorfr

README.md

@@ -1 +1,87 @@
-# gl-vsts-tasks-build
+# gl-vsts-tasks-build
+
+This package provides npm utility commands to ease **VSTS Build And Release Tasks** extensions developement.
+This currently powers the development process behind [Geek Learning's VSTS extensions](https://marketplace.visualstudio.com/search?term=publisher%3A%22Geek%20Learning%22&target=VSTS&sortBy=Relevance).
+
+## Features
+
+* **Multiple packages generation** : This allows you to generate testing versions of the extension using unique ids, so you can easily
+test your extension and setup staged deployment to the store. At Geek Learning our CI builds 3 versions of the extension 
+(Dev, Preview, Production) and stores them as build artifacts. We then use Release Management to publish them to the marketplace.
+Dev package is always published automatically upon successfull build. Preview and Production are manually pushed if it passes our
+final review. Ids and packages settings, are defined in the `Configuration.json` file
+* **Manifest automation** : We automatically populate the contributions in the vss-extension in order to reduced manual maintainance
+of this file.
+* **Common shared code** : We provide an easy way to share powershell or node scripts accros your tasks without the need to make a 
+package of them. Place them in the right subfolder of `Common` and they will be automatically copied where appropriate on build.
+* **Node : Automic dependency installation** : Vsts Agent node execution engine requires npm dependencies to be bundled with your task
+We automatically install two dependencies as a postbuild step after a successfull `npm install` at root.
+* **Automatic versionning** : Visual Studio Marketplace does not support semver, but we always rely on it when it comes to versionnning.
+As a result we needed a way to encode our semver to a Major.Minor.Patch format. This feature can be switched of if you rely on another
+source of versionning.
+
+## Project structure
+
+At the moment, if you wish to use this tooling, your project will need to comply with the architecture we designed.
+
+Directory Structure
+```
+Root
+|-- package.json
+|-- Configuration.json
+|-- tsconfig.json                       // Optional if not using typescript
+|-- Common                              // Optional
+|   |-- Node                            // Node common scripts
+|   |   |-- *.ts                        
+|   |
+|   |-- Powershell3                     // Powershell3 common scripts
+|   |   |-- *.ps1
+|
+|-- Extension
+|   |-- vss-extension.json              // Extension Manifest
+|   |-- ...
+|
+|-- Tasks                               // Task Directory
+|   |-- NodeTask1
+|   |   |-- task.json                   // Task manifest
+|   |   |-- icon.png                    // Task icon
+|   |   |-- package.json                // Package.json, this is where this task dependencies must be listed 
+|   |   |-- *.ts                        // Task source files
+|   |   |-- ...
+|   |
+|   |-- PowershellTask1
+|   |   |-- task.json
+|   |   |-- icon.png
+|   |   |-- *.ps1                       // Task powershell scripts
+|   |   |-- ...
+|   |
+|   | -- ...
+```
+
+## Root `Package.json`
+
+First you should install this package
+
+```bash
+npm install gl-vsts-tasks-build-scripts --save-dev
+```
+
+Then to get the best of this tooling we recommand that you tweak your `package.json` file a little by adding a few `scripts` :
+```json
+{
+    "scripts": {
+        "clean": "vsts-build-tools-clean",
+        "postinstall": "vsts-build-tools-install",
+        "prebuild": "vsts-build-tools-prebuild",
+        "build": "tsc",
+        "package": "vsts-build-tools-package"
+    }
+}
+```
+
+You can now restore or update dependencies and task bundled dependencies by running a single `npm install` at the root.
+You can clean common files using `npm run clean`
+You can build node tasks using `npm run build`
+You can package your extension by running `npm run package`. Output will be placed in the `.BuildOutput` subdirectory at root.
+
+

extension-version.js

@@ -12,6 +12,10 @@ exports.getSemanticVersion = () => {
         console.log('Found version: ' + version);
     }
 
+    if (options.disable-version-transform){
+        return version;
+    }
+
     if (!semver.valid(version)) {
         throw new Error('Package: invalid semver version: ' + version);
     }

package.json

@@ -1,7 +1,13 @@
 {
   "name": "gl-vsts-tasks-build-scripts",
-  "private": true,
+  "private": false,
   "version": "0.0.0",
+  "bin": {
+    "vsts-build-tools-clean": "./run/vsts-build-tools-clean",
+    "vsts-build-tools-install": "./run/vsts-build-tools-install",
+    "vsts-build-tools-package": "./run/vsts-build-tools-package",
+    "vsts-build-tools-prebuild": "./run/vsts-build-tools-prebuild"
+  },
   "devDependencies": {
     "async": "^2.0.1",
     "fs-extra": "0.30.0",
@@ -11,9 +17,9 @@
     "tslint": "^3.6.0",
     "typescript": "^1.8.10",
     "typings": "1.3.2",
-    "jasmine" : "2.4.1",
+    "jasmine": "2.4.1",
     "semver": "5.3.0",
     "tfx-cli": "0.3.23",
     "glob": "7.0.5"
   }
-}
+}

run/vsts-build-tools-clean

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../clean');

run/vsts-build-tools-clean.cmd

@@ -0,0 +1 @@
+@node "%~dpn0" %*

run/vsts-build-tools-install

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../install');

run/vsts-build-tools-install.cmd

@@ -0,0 +1 @@
+@node "%~dpn0" %*

run/vsts-build-tools-package

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../package');

run/vsts-build-tools-package.cmd

@@ -0,0 +1 @@
+@node "%~dpn0" %*

run/vsts-build-tools-prebuild

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../prebuild');