bajo 2.0.1 → 2.1.0

package/class/base.js

@@ -0,0 +1,106 @@
+import Plugin from './plugin.js'
+
+/**
+ * This is the class that your own plugin suppose to extend. Don't use {@link Plugin} directly
+ * unless you know what you're doing.
+ *
+ * @class
+ */
+
+class Base extends Plugin {
+  /**
+   * Dependencies to other plugins. Enter all plugin's package name your plugin dependent from.
+   *
+   * Semver is also supported.
+   *
+   * @constant {string[]}
+   * @memberof Base
+   */
+  static dependencies = []
+
+  /**
+   * @param {string} pkgName - Package name (the one you use in package.json)
+   * @param {Object} app - App instance reference. Usefull to call app method inside a plugin
+   */
+  constructor (pkgName, app) {
+    super(pkgName, app)
+    this.state = {}
+  }
+
+  /**
+   * Load config from file in data directory, program arguments and environment variables. Level of importance:
+   * ```Env Variables > Program Arguments > Config File```
+   *
+   * @method
+   * @async
+   */
+  loadConfig = async () => {
+    const { defaultsDeep } = this.app.lib.aneka
+    const { get, kebabCase, keys, pick } = this.app.lib._
+    const { log, readJson, parseObject, getModuleDir, readAllConfigs } = this.app.bajo
+    const defKeys = keys(this.config)
+    log.trace('- %s', this.ns)
+    const dir = this.ns === this.app.mainNs ? (`${this.app.bajo.dir.base}/${this.app.mainNs}`) : getModuleDir(this.pkgName)
+    let cfg = await readAllConfigs(`${dir}/config`)
+    this.constructor.alias = this.alias ?? (this.pkgName.slice(0, 5) === 'bajo-' ? this.pkgName.slice(5).toLowerCase() : this.ns.toLowerCase())
+    this.constructor.alias = kebabCase(this.alias)
+
+    this.dir = {
+      pkg: dir,
+      data: `${this.app.bajo.dir.data}/plugins/${this.ns}`
+    }
+    const file = `${dir + (this.ns === this.app.mainNs ? '/..' : '')}/package.json`
+    const pkgJson = await readJson(file)
+    this.pkg = pick(pkgJson,
+      ['name', 'version', 'description', 'author', 'license', 'homepage'])
+    if (this.ns === this.app.mainNs) {
+      this.constructor.alias = this.app.mainNs
+      this.title = this.title ?? this.alias
+    }
+    // merge with config from datadir
+    try {
+      const altCfg = await readAllConfigs(`${this.app.bajo.dir.data}/config/${this.ns}`)
+      cfg = defaultsDeep({}, altCfg, cfg)
+    } catch (err) {}
+    const cfgEnv = get(this, `app.env.${this.ns}`, {})
+    const cfgArgv = get(this, `app.argv.${this.ns}`, {})
+    const envArgv = defaultsDeep({}, cfgEnv, cfgArgv)
+    cfg = pick(defaultsDeep({}, envArgv ?? {}, cfg ?? {}, this.config ?? {}), defKeys)
+    this.title = this.title ?? cfg.title ?? this.alias
+    this.config = parseObject(cfg, { parseValue: true })
+  }
+
+  /**
+   * After config is read, plugin will be initialized. You can still change your config here,
+   * because after plugin is initialized, config will be deep frozen.
+   *
+   * @method
+   * @async
+   */
+  init = async () => {
+  }
+
+  /**
+   * This method will be called after plugin's init
+   *
+   * @method
+   * @async
+   */
+  start = async () => {
+  }
+
+  stop = async () => {
+  }
+
+  /**
+   * Upon app termination, this method will be called first. Mostly useful for system cleanup,
+   * delete temporary files, freeing resources etc.
+   *
+   * @method
+   * @async
+   */
+  exit = async () => {
+  }
+}
+
+export default Base

package/class/helper/bajo.js

@@ -1,6 +1,7 @@
-import readAllConfigs from '../../lib/read-all-configs.js'
 import currentLoc from '../../lib/current-loc.js'
 import resolvePath from '../../lib/resolve-path.js'
+import Print from '../misc/print.js'
+import Log from '../misc/log.js'
 import omitDeep from 'omit-deep'
 import os from 'os'
 import fs from 'fs-extra'
@@ -12,7 +13,7 @@ import {
   attachMethods,
   collectHooks,
   run
-} from './plugin.js'
+} from './base.js'
 
 const {
   reduce,
@@ -27,24 +28,32 @@ const {
   keys,
   set,
   get,
-  isString,
   filter,
   trim,
   without,
   uniq,
   camelCase,
-  isEmpty,
-  omit
+  isEmpty
 } = lodash
 
 const omitted = ['spawn', 'cwd', 'name', 'alias', 'applet', 'a', 'plugins']
 
 const defConfig = {
+  env: 'dev',
   log: {
-    dateFormat: 'YYYY-MM-DDTHH:MM:ss.SSS[Z]',
-    plain: false,
+    timeTaken: false,
+    dateFormat: 'YYYY-MM-DDTHH:mm:ss.SSS',
+    useUtc: false,
+    pretty: false,
     applet: false,
-    traceHook: false
+    traceHook: false,
+    save: false,
+    rotation: {
+      cycle: 'none', // none, daily, weekly, monthly
+      compressOld: true,
+      byPlugin: false,
+      retain: 5
+    }
   },
   lang: Intl.DateTimeFormat().resolvedOptions().lang ?? 'en-US',
   intl: {
@@ -69,83 +78,97 @@ const defConfig = {
   exitHandler: true
 }
 
+const defMain = `async function factory (pkgName) {
+  const me = this
+
+  return class Main extends this.app.pluginClass.base {
+    constructor () {
+      super(pkgName, me.app)
+      this.config = {}
+    }
+  }
+}
+
+export default factory
+`
+
 /**
- * @module
+ * Internal helpers called by Bajo that only used once for bootstrapping. It should remains
+ * hidden and not to be imported by any program.
+ *
+ * @module Helper/Bajo
  */
 
 /**
  * Building bajo base config. Mostly dealing with directory setups:
  * - determine base directory
- * - check whether data directory is valid
+ * - check whether data directory is valid. If not exist, create one inside app dir
  * - ensure data config directory is there
+ * - ensure tmp dir is there
+ * - read the list of plugins from ```.plugins``` file
  *
  * @async
  */
 export async function buildBaseConfig () {
-  const { defaultsDeep } = this.lib.aneka
-  this.applet = this.app.argv._.applet
-  this.config = defaultsDeep({}, this.app.env._, this.app.argv._)
-  this.alias = this.name
+  // dirs
+  const { defaultsDeep } = this.app.lib.aneka
+  this.config = defaultsDeep({}, this.app.envVars._, this.app.argv._)
   set(this, 'dir.base', this.app.dir)
   const path = currentLoc(import.meta).dir + '/../..'
   set(this, 'dir.pkg', this.resolvePath(path))
+  if (get(this, 'config.dir.data')) set(this, 'dir.data', this.config.dir.data)
   if (!get(this, 'dir.data')) set(this, 'dir.data', `${this.dir.base}/data`)
   this.dir.data = this.resolvePath(this.dir.data)
-  if (!fs.existsSync(this.dir.data)) {
-    console.log('Data directory (%s) doesn\'t exist yet', this.dir.data)
-    process.exit(1)
-  }
   fs.ensureDirSync(`${this.dir.data}/config`)
   if (!this.dir.tmp) {
-    this.dir.tmp = `${this.resolvePath(os.tmpdir())}/${this.name}`
+    this.dir.tmp = `${this.resolvePath(os.tmpdir())}/${this.ns}`
     fs.ensureDirSync(this.dir.tmp)
   }
-  this.app.addPlugin(this)
+  // collect list of plugins
+  let pluginPkgs = []
+  const pluginsFile = `${this.dir.data}/config/.plugins`
+  if (fs.existsSync(pluginsFile)) {
+    pluginPkgs = pluginPkgs.concat(filter(map(trim(fs.readFileSync(pluginsFile, 'utf8')).split('\n'), p => trim(p)), b => !isEmpty(b)))
+  }
+  this.app.pluginPkgs = map(filter(without(uniq(pluginPkgs), this.app.mainNs), p => {
+    return p[0] !== '#'
+  }), p => {
+    return trim(p.split('#')[0])
+  })
+  this.app.pluginPkgs.push(this.app.mainNs)
 }
 
 /**
  * Building all plugins:
- * - read the list of plugins from ```.plugins``` file
+ * - load from app's pluginPkgs
  * - iterate through the list and build related plugins
+ * - making sure main plugin is there. If not, create from template
  * - attach these plugins to the app instance
  *
  * @async
  */
 export async function buildPlugins () {
-  let pluginPkgs = this.config.plugins ?? []
-  if (isString(pluginPkgs)) pluginPkgs = [pluginPkgs]
-  const pluginsFile = `${this.dir.data}/config/.plugins`
-  if (fs.existsSync(pluginsFile)) {
-    pluginPkgs = pluginPkgs.concat(filter(map(trim(fs.readFileSync(pluginsFile, 'utf8')).split('\n'), p => trim(p)), b => !isEmpty(b)))
-  }
-  this.pluginPkgs = map(filter(without(uniq(pluginPkgs), this.mainNs), p => {
-    return p[0] !== '#'
-  }), p => {
-    return trim(p.split('#')[0])
-  })
-  this.pluginPkgs.push(this.mainNs)
-  for (const pkg of this.pluginPkgs) {
+  this.log.trace('buildPluginsStart')
+  for (const pkg of this.app.pluginPkgs) {
     const ns = camelCase(pkg)
     let dir
     if (ns === 'main') {
-      dir = `${this.dir.base}/${this.mainNs}`
+      dir = `${this.dir.base}/${this.app.mainNs}`
       fs.ensureDirSync(dir)
-      fs.ensureDirSync(`${dir}/plugin`)
+      if (!fs.existsSync(`${dir}/index.js`)) {
+        fs.writeFileSync(`${dir}/index.js`, defMain, 'utf8')
+      }
     } else dir = this.getModuleDir(pkg)
-    let plugin
     const factory = `${dir}/index.js`
-    if (fs.existsSync(factory)) {
-      const { default: builder } = await import(resolvePath(factory, true))
-      const FactoryClass = await builder.call(this, pkg)
-      plugin = new FactoryClass()
-      if (!(plugin instanceof this.lib.Plugin)) throw new Error(`Plugin package '${pkg}' should be an instance of BajoPlugin`)
-    } else {
-      plugin = new this.lib.Plugin(pkg, this.app)
-    }
-    this.pluginNames.push(plugin.name)
-    this.app.addPlugin(plugin)
+    if (!fs.existsSync(factory)) throw this.error('pluginPackageNotFound%s', pkg)
+    const { default: builder } = await import(resolvePath(factory, true))
+    const ClassDef = await builder.call(this, pkg)
+    const plugin = new ClassDef()
+    if (!(plugin instanceof this.app.pluginClass.base)) throw this.error('pluginPackageInvalid%s', pkg)
+    this.app.addPlugin(plugin, ClassDef)
+    this.log.trace('- ' + pkg)
   }
-  this.config = omit(this.config, this.pluginNames)
+  this.log.debug('buildPluginsComplete')
 }
 
 /**
@@ -154,7 +177,7 @@ export async function buildPlugins () {
  * @async
  */
 export async function collectConfigHandlers () {
-  for (const pkg of this.pluginPkgs) {
+  for (const pkg of this.app.pluginPkgs) {
     let dir
     try {
       dir = this.getModuleDir(pkg)
@@ -165,8 +188,9 @@ export async function collectConfigHandlers () {
     if (!mod) continue
     if (isFunction(mod)) mod = await mod.call(this.app[camelCase(pkg)])
     if (isPlainObject(mod)) mod = [mod]
-    this.configHandlers = this.configHandlers.concat(mod)
+    this.app.configHandlers = this.app.configHandlers.concat(mod)
   }
+  this.app.log = new Log(this.app)
 }
 
 /**
@@ -179,26 +203,31 @@ export async function collectConfigHandlers () {
  */
 export async function buildExtConfig () {
   // config merging
-  const { defaultsDeep } = this.lib.aneka
-  let resp = await readAllConfigs.call(this.app, `${this.dir.data}/config/${this.name}`)
+  const { defaultsDeep } = this.app.lib.aneka
+  let resp = await this.readAllConfigs(`${this.dir.data}/config/${this.ns}`)
   resp = omitDeep(pick(resp, ['log', 'exitHandler', 'env']), omitted)
+  const envs = this.app.constructor.envs
   this.config = defaultsDeep({}, this.config, resp, defConfig)
-  this.config.env = (this.config.env ?? 'dev').toLowerCase()
-  if (values(this.envs).includes(this.config.env)) this.config.env = this.lib.aneka.getKeyByValue(this.envs, this.config.env)
-  if (!keys(this.envs).includes(this.config.env)) throw new Error(`Unknown environment '${this.config.env}'. Supported: ${this.join(keys(this.envs))}`)
-  process.env.NODE_ENV = this.envs[this.config.env]
+  // language
+  this.config.lang = (this.config.lang ?? '').split('.')[0]
+  this.app.loadIntl(this.ns)
+  this.print = new Print(this)
+  // environment
+  if (values(envs).includes(this.config.env)) this.config.env = this.app.lib.aneka.getKeyByValue(envs, this.config.env)
+  if (!keys(envs).includes(this.config.env)) throw this.error('unknownEnv%s%s', this.config.env, this.join(keys(envs), { lastSeparator: this.t('or') }))
+  process.env.NODE_ENV = envs[this.config.env]
   if (!this.config.log.level) this.config.log.level = this.config.env === 'dev' ? 'debug' : 'info'
-  if (this.config.silent) this.config.log.level = 'silent'
-  if (this.applet) {
-    if (!this.pluginPkgs.includes('bajo-cli')) throw new Error('Applet needs to have \'bajo-cli\' loaded first')
+  // misc
+  const obj = this.app.applet ? this.config : pick(this.config, keys(defConfig))
+  this.config = this.parseObject(obj, { parseValue: true })
+  const exts = this.app.getConfigFormats()
+  if (this.app.applet) {
+    if (!this.app.pluginPkgs.includes('bajo-cli')) throw this.error('appletNeedsBajoCli')
     if (!this.config.log.applet) this.config.log.level = 'silent'
     this.config.exitHandler = false
   }
-  const exts = map(this.configHandlers, 'ext')
-  this.initPrint()
-  this.initLog()
+  this.log.trace('dataDir%s', this.dir.data)
   this.log.debug('configHandlers%s', this.join(exts))
-  this.config = this.parseObject(this.config, { parseValue: true })
 }
 
 /**
@@ -208,17 +237,17 @@ export async function buildExtConfig () {
  */
 export async function bootOrder () {
   this.log.debug('setupBootOrder')
-  const order = reduce(this.pluginPkgs, (o, k, i) => {
+  const order = reduce(this.app.pluginPkgs, (o, k, i) => {
     const key = map(k.split(':'), m => trim(m))
     if (key[1] && !isNaN(Number(key[1]))) o[key[0]] = Number(key[1])
     else o[key[0]] = 10000 + i
     return o
   }, {})
   const norder = {}
-  for (let n of this.pluginPkgs) {
+  for (let n of this.app.pluginPkgs) {
     n = map(n.split(':'), m => trim(m))[0]
-    const dir = n === this.mainNs ? (`${this.dir.base}/${this.mainNs}`) : this.getModuleDir(n)
-    if (n !== this.mainNs && !fs.existsSync(dir)) throw this.error('packageNotFoundOrNotBajo%s', n)
+    const dir = n === this.app.mainNs ? (`${this.dir.base}/${this.app.mainNs}`) : this.getModuleDir(n)
+    if (n !== this.app.mainNs && !fs.existsSync(dir)) throw this.error('packageNotFoundOrNotBajo%s', n)
     norder[n] = NaN
     try {
       norder[n] = Number(trim(await fs.readFile(`${dir}/.bootorder`, 'utf8')))
@@ -229,20 +258,21 @@ export async function bootOrder () {
     const item = { k, v: isNaN(norder[k]) ? v : norder[k] }
     result.push(item)
   })
-  this.pluginPkgs = map(orderBy(result, ['v']), 'k')
-  this.log.info('runInEnv%s', this.print.write(this.envs[this.config.env]))
+  this.app.pluginPkgs = map(orderBy(result, ['v']), 'k')
+  this.log.debug('runInEnv%s', this.t(this.app.constructor.envs[this.config.env]))
   // misc
   this.freeze(this.config)
 }
 
 /**
  * Iterate through all plugins loaded and do:
- * 1. {@link module:class/helper/bajo-plugin.buildConfigs|build configs}
- * 2. {@link module:class/helper/bajo-plugin.checkNameAliases|ensure names & aliases uniqueness}
- * 3. {@link module:class/helper/bajo-plugin.checkDependencies|ensure dependencies are met}
- * 4. {@link module:class/helper/bajo-plugin.attachMethods|build and attach dynamic methods}
- * 5. {@link module:class/helper/bajo-plugin.collectHooks|collect hooks}
- * 6. {@link module:class/helper/bajo-plugin.run|run plugins}
+ *
+ * 1. {@link module:Helper/Base.buildConfigs|build configs}
+ * 2. {@link module:Helper/Base.checkNameAliases|ensure names & aliases uniqueness}
+ * 3. {@link module:Helper/Base.checkDependencies|ensure dependencies are met}
+ * 4. {@link module:Helper/Base.attachMethods|build and attach dynamic methods}
+ * 5. {@link module:Helper/Base.collectHooks|collect hooks}
+ * 6. {@link module:Helper/Base.run|run plugins}
  *
  * @async
  */
@@ -265,10 +295,10 @@ export async function exitHandler () {
 
   async function exit (signal) {
     const { eachPlugins } = this
-    this.log.warn('signalReceived%s', signal)
-    await eachPlugins(async function () {
+    if (signal) this.log.warn('signalReceived%s', signal)
+    await eachPlugins(async function ({ ns }) {
       try {
-        await this.stop()
+        await this.exit()
       } catch (err) {}
       this.log.trace('exited')
     })
@@ -284,6 +314,10 @@ export async function exitHandler () {
     await exit.call(this, 'SIGTERM')
   })
 
+  process.on('beforeExit', async () => {
+    await exit.call(this)
+  })
+
   process.on('uncaughtException', (error, origin) => {
     setTimeout(() => {
       console.error(error)
@@ -316,29 +350,51 @@ export async function exitHandler () {
  * If app is in ```applet``` mode, this little helper should take care plugin's applet boot process
  *
  * @async
+ * @fires {ns}:beforeAppletRun
+ * @fires {ns}:afterAppletRun
  */
 export async function runAsApplet () {
-  const { isString, map, find } = this.lib._
+  const { isString, map, find } = this.app.lib._
   await this.eachPlugins(async function ({ file }) {
-    const { name: ns, alias } = this
-    this.app.bajo.applets.push({ ns, file, alias })
+    const { ns } = this
+    const { alias } = this.constructor
+    this.app.applets.push({ ns, file, alias })
   }, { glob: 'applet.js', prefix: 'bajoCli' })
 
   this.log.debug('appletModeActivated')
   this.print.info('appRunningAsApplet')
-  if (this.applets.length === 0) this.print.fatal('noAppletLoaded')
-  let name = this.applet
-  if (!isString(this.applet)) {
+  if (this.app.applets.length === 0) this.print.fatal('noAppletLoaded')
+  let name = this.app.applet
+  if (!isString(name)) {
     const select = await this.importPkg('bajoCli:@inquirer/select')
     name = await select({
-      message: this.print.write('Please select:'),
-      choices: map(this.applets, t => ({ value: t.ns }))
+      message: this.t('Please select:'),
+      choices: map(this.app.applets, t => ({ value: t.ns }))
     })
   }
   const [ns, path] = name.split(':')
-  const applet = find(this.applets, a => (a.ns === ns || a.alias === ns))
-  if (!applet) this.print.fatal('notFound%s%s', this.print.write('applet'), name)
-  await this.runHook(`${this.app[applet.ns]}:beforeAppletRun`)
+  const applet = find(this.app.applets, a => (a.ns === ns || a.alias === ns))
+  if (!applet) this.print.fatal('notFound%s%s', this.app.t('applet'), name)
+
+  /**
+   * Run before applet is run. ```[ns]``` is applet's namespace
+   *
+   * @global
+   * @event {ns}:beforeAppletRun
+   * @param {...any} params
+   * @see {@tutorial hook}
+   * @see module:Helper/Bajo.runAsApplet
+   */
+  await this.runHook(`${this.app[applet.ns]}:beforeAppletRun`, ...this.app.args)
   await this.app.bajoCli.runApplet(applet, path, ...this.app.args)
-  await this.runHook(`${this.app[applet.ns]}:afterAppletRun`)
+  /**
+   * Run after applet is run. ```[ns]``` is applet's namespace
+   *
+   * @global
+   * @event {ns}:afterAppletRun
+   * @param {...any} params
+   * @see {@tutorial hook}
+   * @see module:Helper/Bajo.runAsApplet
+   */
+  await this.runHook(`${this.app[applet.ns]}:afterAppletRun`, ...this.app.args)
 }