initial commit

Original commit: elastic/kibana-plugin-helpers@06c603d0d9

packages/kbn-plugin-helpers/.eslintrc

@@ -0,0 +1,2 @@
+---
+extends: "@elastic/kibana"

packages/kbn-plugin-helpers/.gitignore

@@ -0,0 +1,2 @@
+node_modules
+.DS_Store

packages/kbn-plugin-helpers/bin/plugin-helper-build.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+var pkg = require('../package.json');
+var program = require('commander');
+var help = require('../help');
+var task = require('../tasks/build');
+
+program
+  .version(pkg.version)
+  .description('Build a distributable archive')
+  .on('--help', help('build'))
+  .parse(process.argv);
+
+
+task();

packages/kbn-plugin-helpers/bin/plugin-helper-start.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+var program = require('commander');
+
+var pkg = require('../package.json');
+var help = require('../help');
+var task = require('../tasks/start');
+
+program
+  .version(pkg.version)
+  .description('Start kibana and have it include this plugin')
+  .on('--help', help('start'))
+  .parse(process.argv);
+
+
+task();

packages/kbn-plugin-helpers/bin/plugin-helper-test:browser.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+var pkg = require('../package.json');
+var program = require('commander');
+var help = require('../help');
+var task = require('../tasks/test:browser');
+
+program
+  .version(pkg.version)
+  .description('Run the browser tests in a real web browser')
+  .on('--help', help('test:browser'))
+  .parse(process.argv);
+
+
+task(program);

packages/kbn-plugin-helpers/bin/plugin-helper-test:server.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+var program = require('commander');
+
+var pkg = require('../package.json');
+var help = require('../help');
+var task = require('../tasks/test:server');
+
+program
+  .version(pkg.version)
+  .description('Run the server tests using mocha')
+  .on('--help', help('test:server'))
+  .parse(process.argv);
+
+task();

packages/kbn-plugin-helpers/bin/plugin-helper.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+var pkg = require('../package.json');
+var program = require('commander');
+
+program
+  .version(pkg.version)
+  .command('start', 'start the server')
+  .command('test:browser', 'run the browser tests')
+  .command('test:server', 'run the server tests')
+  .command('build', 'build a distributable archive')
+  .parse(process.argv);

packages/kbn-plugin-helpers/help/build.md

@@ -0,0 +1,9 @@
+Copies files from the source into a zip archive that can be distributed for
+installation into production kibana installs. The archive includes the non-
+development npm dependencies and builds itself using raw files in the source
+directory so make sure they are clean/up to date. The resulting archive can
+be found at:
+
+```
+build/{pkg.name}-{pkg.version}.zip
+```

packages/kbn-plugin-helpers/help/index.js

@@ -0,0 +1,18 @@
+var join = require('path').join;
+var readFileSync = require('fs').readFileSync;
+
+function indent(txt, n) {
+  var space = (new Array(n + 1)).join(' ');
+  return space + txt.split('\n').join('\n' + space);
+}
+
+module.exports = function (name) {
+  return function () {
+    var md = readFileSync(join(__dirname, name + '.md'), 'utf8');
+
+    console.log('\n  Docs:');
+    console.log('');
+    console.log(indent(md, 4));
+    console.log('');
+  };
+};

packages/kbn-plugin-helpers/help/start.md

@@ -0,0 +1,6 @@
+Starts the kibana server with this plugin included. In essence this is the same as running the
+following from the root of the kibana install:
+
+```sh
+./bin/kibana --dev --plugin-path=../path/to/plugin
+```

packages/kbn-plugin-helpers/help/test:browser.md

@@ -0,0 +1,51 @@
+writing tests
+=============
+
+Browser tests are written just like server tests, they are just executed differently.
+
+  - place tests near the code they test, in `__tests__` directories throughout
+    the public directory
+
+  - Use the same bdd-style `describe()` and `it()`
+    api to define the suites and cases of your tests.
+
+    ```js
+    describe('some portion of your code', function () {
+      it('should do this thing', function () {
+        expect(true).to.be(false);
+      });
+    });
+    ```
+
+
+starting the test runner
+========================
+
+Under the covers this command uses the `test:dev` task from kibana. This task sets-up
+a test runner that will watch your code for changes and rebuild your tests when necessary.
+You access the test runner through a browser that it starts itself (via Karma).
+
+
+running the tests
+=================
+
+Once the test runner has started you a new browser window should be opened and you should
+see a message saying "connected". Next to that is a "DEBUG" button. This button will open
+an interactive version of your tests that you can refresh, inspects, and otherwise debug
+while you write your tests.
+
+
+focus on the task at hand
+=========================
+
+To limit the tests that run you can either:
+
+  1. use the ?grep= query string to filter the test cases/suites by name
+  2. Click the suite title or (play) button next to test output
+  3. Add `.only` to your `describe()` or `it()` calls:
+
+    ```js
+    describe.only('suite name', function () {
+      // ...
+    });
+    ```

packages/kbn-plugin-helpers/help/test:server.md

@@ -0,0 +1,36 @@
+writing tests
+=============
+
+Server tests are written just like browser tests, they are just executed differently.
+
+  - place tests near the code they test, in `__tests__` directories throughout
+    the server directory
+  - Use the same bdd-style `describe()` and `it()` api to define the suites
+    and cases of your tests.
+
+    ```js
+    describe('some portion of your code', function () {
+      it('should do this thing', function () {
+        expect(true).to.be(false);
+      });
+    });
+    ```
+
+
+running the tests
+=================
+
+Running the server tests is simple, just execute `npm run test:server` in your terminal
+and all of the tests in your server will be run.
+
+
+focus on the task at hand
+=========================
+
+To limit the tests that run add `.only` to your `describe()` or `it()` calls:
+
+```js
+describe.only('suite name', function () {
+  // ...
+});
+```

packages/kbn-plugin-helpers/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "kibana-plugin-helpers",
+  "version": "5.0.0-beta1",
+  "description": "",
+  "main": "index.js",
+  "bin": {
+    "plugin-helper": "bin/plugin-helper.js"
+  },
+  "keywords": [
+    "kibana",
+    "kibana-plugin"
+  ],
+  "author": "Spencer Alger <email@spalger.com>",
+  "license": "Apache-2.0",
+  "scripts": {
+    "lint": "eslint bin/ help/ tasks/"
+  },
+  "dependencies": {
+    "@elastic/eslint-config-kibana": "0.0.2",
+    "babel-eslint": "4.1.8",
+    "commander": "^2.9.0",
+    "eslint": "1.10.3",
+    "eslint-plugin-mocha": "1.1.0",
+    "gulp-rename": "1.2.2",
+    "gulp-zip": "3.1.0",
+    "vinyl-fs": "2.3.1"
+  }
+}

packages/kbn-plugin-helpers/tasks/build.js

@@ -0,0 +1,27 @@
+module.exports = function () {
+
+  var vfs = require('vinyl-fs');
+  var zip = require('gulp-zip');
+  var rename = require('gulp-rename');
+  var join = require('path').join;
+
+  var pkg = require('../package.json');
+  var deps = Object.keys(pkg.dependencies || {});
+  var buildId = `${pkg.name}-${pkg.version}`;
+
+  var files = [
+    'package.json',
+    'index.js',
+    '{lib,public,server,webpackShims}/**/*',
+    `node_modules/{${ deps.join(',') }}/**/*`,
+  ];
+
+  vfs
+    .src(files, { base: join(__dirname, '..') })
+    .pipe(rename(function nestFileInDir(path) {
+      path.dirname = join(buildId, path.dirname);
+    }))
+    .pipe(zip(`${buildId}.zip`))
+    .pipe(vfs.dest('build'));
+
+};

packages/kbn-plugin-helpers/tasks/start.js

@@ -0,0 +1,14 @@
+module.exports = function () {
+  var resolve = require('path').resolve;
+  var execFileSync = require('child_process').execFileSync;
+
+  var pluginDir = resolve(__dirname, '../');
+  var kibanaDir = resolve(pluginDir, '../kibana');
+
+  var cmd = 'bin/kibana';
+  var args = ['--dev', '--plugin-path', pluginDir];
+  execFileSync(cmd, args, {
+    cwd: kibanaDir,
+    stdio: 'inherit'
+  });
+};

packages/kbn-plugin-helpers/tasks/test:browser.js

@@ -0,0 +1,22 @@
+module.exports = function () {
+
+  var resolve = require('path').resolve;
+  var execFileSync = require('child_process').execFileSync;
+
+  var pkg = require('../package.json');
+  var pluginDir = resolve(__dirname, '../');
+  var kibanaDir = resolve(pluginDir, '../kibana');
+
+  var kbnServerArgs = [
+    '--kbnServer.testsBundle.pluginId', pkg.name,
+    '--kbnServer.plugin-path', pluginDir
+  ];
+
+  var cmd = 'npm';
+  var args = ['run', 'test:dev', '--'].concat(kbnServerArgs);
+  execFileSync(cmd, args, {
+    cwd: kibanaDir,
+    stdio: 'inherit'
+  });
+
+};

packages/kbn-plugin-helpers/tasks/test:server.js

@@ -0,0 +1,15 @@
+module.exports = function () {
+  var resolve = require('path').resolve;
+  var execFileSync = require('child_process').execFileSync;
+
+  var pluginDir = resolve(__dirname, '..');
+  var kibanaDir = resolve(pluginDir, '../kibana');
+  var mochaSetupJs = resolve(kibanaDir, 'test/mocha_setup.js');
+
+  var cmd = 'mocha';
+  var args = ['--require', mochaSetupJs, 'server/**/__tests__/**/*.js'];
+  execFileSync(cmd, args, {
+    cwd: pluginDir,
+    stdio: 'inherit'
+  });
+};