feat: add help text for most ctrls (#17)

Makefile

@@ -63,8 +63,8 @@ help: ## print this help
 		| awk 'BEGIN {FS = ":[^:]*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
 
 git-push: ## push to both gitlab and github (this assumes you have both remotes set up)
-	git push gitlab ${GIT_BRANCH}
 	git push github ${GIT_BRANCH}
+	git push gitlab ${GIT_BRANCH}
 
 # from https://gist.github.com/amitchhajer/4461043#gistcomment-2349917
 git-stats: ## print git contributor line counts (approx, for fun)

src/Bot.ts

@@ -375,9 +375,6 @@ export class Bot extends BaseService<BotData> implements Service {
 
   /**
    * Log an otherwise-unhandled but non-fatal error (typically leaked from one of the observables).
-   *
-   * Note: this method is already bound, so it can be passed with `this.looseError`. Using that requires
-   * `tslint:disable:no-unbound-method` as well.
    */
   protected looseError(err: Error) {
     this.logger.error(err, 'bot stream did not handle error');

src/controller/AccountController.ts

@@ -80,6 +80,11 @@ export class AccountController extends BaseController<AccountControllerData> imp
     return this.reply(ctx, results);
   }
 
+  @Handler(NOUN_GRANT, CommandVerb.Help)
+  public async getGrantHelp(cmd: Command, ctx: Context): Promise<void> {
+    return this.reply(ctx, this.defaultHelp(cmd));
+  }
+
   @Handler(NOUN_ACCOUNT, CommandVerb.Create)
   public async createAccount(cmd: Command, ctx: Context): Promise<void> {
     if (!this.data.join.allow && !this.checkGrants(ctx, 'account:create')) {
@@ -89,7 +94,7 @@ export class AccountController extends BaseController<AccountControllerData> imp
     const name = cmd.getHeadOrDefault('name', ctx.name);
     const existing = await this.userRepository.count({ name });
     if (existing > 0) {
-      return this.reply(ctx, this.locale.translate('service.controller.account.account.create.exists', {
+      return this.reply(ctx, this.translate('account-create.exists', {
         name,
       }));
     }
@@ -106,7 +111,7 @@ export class AccountController extends BaseController<AccountControllerData> imp
     }));
 
     const jwt = await this.createToken(user);
-    return this.reply(ctx, this.locale.translate('service.controller.account.account.create.success', {
+    return this.reply(ctx, this.translate('account-create.success', {
       jwt,
       name,
     }));
@@ -119,7 +124,7 @@ export class AccountController extends BaseController<AccountControllerData> imp
     const name = user.name;
 
     if (cmd.getHeadOrDefault('confirm', 'no') !== 'yes') {
-      const completion = createCompletion(cmd, 'confirm', this.locale.translate('service.controller.account.account.delete.confirm', {
+      const completion = createCompletion(cmd, 'confirm', this.translate('account-delete.confirm', {
         name,
       }));
       await this.bot.executeCommand(completion);
@@ -131,12 +136,17 @@ export class AccountController extends BaseController<AccountControllerData> imp
     });
 
     const jwt = await this.createToken(user);
-    return this.reply(ctx, this.locale.translate('service.controller.account.account.delete.success', {
+    return this.reply(ctx, this.translate('account-delete.success', {
       jwt,
       name,
     }));
   }
 
+  @Handler(NOUN_ACCOUNT, CommandVerb.Help)
+  public async getAccountHelp(cmd: Command, ctx: Context): Promise<void> {
+    return this.reply(ctx, this.defaultHelp(cmd));
+  }
+
   @Handler(NOUN_SESSION, CommandVerb.Create)
   public async createSession(cmd: Command, ctx: Context): Promise<void> {
     const jwt = cmd.getHead('token');
@@ -155,7 +165,7 @@ export class AccountController extends BaseController<AccountControllerData> imp
     const source = this.getSourceOrFail(ctx);
     const session = await source.createSession(ctx.uid, user);
     this.logger.debug({ session, user }, 'created session');
-    return this.reply(ctx, this.locale.translate('service.controller.account.session.create.success'));
+    return this.reply(ctx, this.translate('session-create.success'));
   }
 
   @Handler(NOUN_SESSION, CommandVerb.Get)
@@ -171,6 +181,11 @@ export class AccountController extends BaseController<AccountControllerData> imp
     return this.reply(ctx, session.toString());
   }
 
+  @Handler(NOUN_SESSION, CommandVerb.Help)
+  public async getSessionHelp(cmd: Command, ctx: Context): Promise<void> {
+    return this.reply(ctx, this.defaultHelp(cmd));
+  }
+
   protected async createToken(user: User): Promise<string> {
     const issued = this.clock.getSeconds();
     const expires = issued + this.data.token.duration;

src/controller/BaseController.ts

@@ -6,11 +6,11 @@ import { BotService, INJECT_LOCALE } from 'src/BotService';
 import { getHandlerOptions, HandlerOptions } from 'src/controller';
 import { Controller, ControllerData, ControllerOptions } from 'src/controller/Controller';
 import { User } from 'src/entity/auth/User';
-import { Command } from 'src/entity/Command';
+import { Command, CommandVerb } from 'src/entity/Command';
 import { Context } from 'src/entity/Context';
 import { Message } from 'src/entity/Message';
 import { Listener } from 'src/listener/Listener';
-import { Locale } from 'src/locale';
+import { Locale, TranslateOptions } from 'src/locale';
 import { ServiceModule } from 'src/module/ServiceModule';
 import { ServiceDefinition } from 'src/Service';
 import { applyTransforms } from 'src/transform/helpers';
@@ -181,4 +181,23 @@ export abstract class BaseController<TData extends ControllerData> extends BotSe
     }
     return user;
   }
+
+  protected translate(key: string, options: TranslateOptions = {}): string {
+    return this.locale.translate(`service.${this.kind}.${key}`, options);
+  }
+
+  protected defaultHelp(cmd: Command): string {
+    const data = {
+      data: this.data,
+    };
+    const desc = this.translate('help.desc', data);
+
+    if (cmd.has('topic')) {
+      const topic = cmd.getHead('topic');
+      const topicDesc = this.translate(`help.${topic}`, data);
+      return `${desc}\n${topicDesc}`;
+    }
+
+    return desc;
+  }
 }

src/controller/CompletionController.ts

@@ -62,7 +62,7 @@ export class CompletionController extends BaseController<CompletionControllerDat
     }));
 
     this.logger.debug({ context, fragment }, 'creating fragment for later completion');
-    return this.reply(context, this.locale.translate('service.controller.completion.fragment.prompt', {
+    return this.reply(context, this.translate('create.prompt', {
       id: fragment.id,
       key,
       msg,
@@ -77,7 +77,7 @@ export class CompletionController extends BaseController<CompletionControllerDat
 
     const fragment = await this.getFragment(ctx, id);
     if (isNil(fragment)) {
-      return this.reply(ctx, this.locale.translate('service.controller.completion.fragment.missing'));
+      return this.reply(ctx, this.translate('update.missing'));
     }
 
     this.logger.debug({ fragment, parserId: fragment.parserId }, 'attempting to complete fragment');
@@ -93,6 +93,11 @@ export class CompletionController extends BaseController<CompletionControllerDat
     await this.bot.executeCommand(...commands);
   }
 
+  @Handler(NOUN_FRAGMENT, CommandVerb.Help)
+  public async getHelp(cmd: Command, ctx: Context): Promise<void> {
+    return this.reply(ctx, this.defaultHelp(cmd));
+  }
+
   protected async createContext(maybeCtx?: Context) {
     const ctx = mustExist(maybeCtx);
     if (isNil(ctx.target)) {

src/controller/CountController.ts

@@ -69,6 +69,11 @@ export class CountController extends BaseController<CountControllerData> impleme
     await this.counterRepository.save(counter);
   }
 
+  @Handler(NOUN_COUNTER, CommandVerb.Help)
+  public async getHelp(cmd: Command, ctx: Context): Promise<void> {
+    return this.reply(ctx, this.defaultHelp(cmd));
+  }
+
   public async findOrCreateCounter(name: string, roomId: string): Promise<Counter> {
     const counter = await this.counterRepository.findOne({
       where: {

src/controller/DiceController.ts

@@ -6,6 +6,7 @@ import { CheckRBAC, Handler } from 'src/controller';
 import { BaseController } from 'src/controller/BaseController';
 import { Controller, ControllerData, ControllerOptions } from 'src/controller/Controller';
 import { Command, CommandVerb } from 'src/entity/Command';
+import { Context } from 'src/entity/Context';
 import { mustExist } from 'src/utils';
 
 const DICE_MINIMUM = 1;
@@ -41,9 +42,14 @@ export class DiceController extends BaseController<DiceControllerData> implement
     this.logger.debug({ count, sides }, 'handling dice results');
     const sum = results.reduce((a, b) => a + b, 0);
 
-    return this.reply(mustExist(cmd.context), this.locale.translate('service.controller.dice.roll.create', {
+    return this.reply(mustExist(cmd.context), this.translate('create.success', {
       results,
       sum,
     }));
   }
+
+  @Handler(NOUN_ROLL, CommandVerb.Help)
+  public async getHelp(cmd: Command, ctx: Context): Promise<void> {
+    return this.reply(ctx, this.defaultHelp(cmd));
+  }
 }

src/controller/EchoController.ts

@@ -4,6 +4,7 @@ import { CheckRBAC, Handler } from 'src/controller';
 import { BaseController } from 'src/controller/BaseController';
 import { Controller, ControllerData, ControllerOptions } from 'src/controller/Controller';
 import { Command, CommandVerb } from 'src/entity/Command';
+import { Context } from 'src/entity/Context';
 
 export const NOUN_ECHO = 'echo';
 
@@ -18,8 +19,13 @@ export class EchoController extends BaseController<EchoControllerData> implement
 
   @Handler(NOUN_ECHO, CommandVerb.Create)
   @CheckRBAC()
-  public async createEcho(cmd: Command): Promise<void> {
+  public async createEcho(cmd: Command, ctx: Context): Promise<void> {
     this.logger.debug({ cmd }, 'echoing command');
     return this.transformJSON(cmd, {});
   }
+
+  @Handler(NOUN_ECHO, CommandVerb.Help)
+  public async getHelp(cmd: Command, ctx: Context): Promise<void> {
+    return this.reply(ctx, this.defaultHelp(cmd));
+  }
 }

src/controller/LearnController.ts

@@ -62,7 +62,7 @@ export class LearnController extends BaseController<LearnControllerData> impleme
     }
 
     await this.keywordRepository.save(keyword);
-    return this.reply(ctx, this.locale.translate('service.controller.learn.keyword.create', {
+    return this.reply(ctx, this.translate('create.success', {
       key,
     }));
   }
@@ -83,7 +83,7 @@ export class LearnController extends BaseController<LearnControllerData> impleme
       id: keyword.id,
       key,
     });
-    return this.reply(ctx, this.locale.translate('service.controller.learn.keyword.delete', {
+    return this.reply(ctx, this.translate('delete.success', {
       key,
     }));
   }
@@ -115,4 +115,9 @@ export class LearnController extends BaseController<LearnControllerData> impleme
     await this.bot.executeCommand(merged);
     return;
   }
+
+  @Handler(NOUN_KEYWORD, CommandVerb.Help)
+  public async getHelp(cmd: Command, ctx: Context): Promise<void> {
+    return this.reply(ctx, this.defaultHelp(cmd));
+  }
 }

src/controller/MathController.ts

@@ -49,14 +49,19 @@ export class MathController extends BaseController<MathControllerData> implement
     return this.reply(ctx, body);
   }
 
+  @Handler(NOUN_MATH, CommandVerb.Help)
+  public async getHelp(cmd: Command, ctx: Context): Promise<void> {
+    return this.reply(ctx, this.defaultHelp(cmd));
+  }
+
   protected solve(expr: string, scope: object): string {
     try {
       const body = this.math.eval(expr, scope);
       this.logger.debug({ body, expr }, 'evaluated expression');
 
       return formatResult(body, scope, this.data.format);
     } catch (err) {
-      return this.locale.translate('service.controller.math.math.error', {
+      return this.translate('create.error', {
         msg: err.message,
       });
     }

src/controller/PickController.ts

@@ -42,4 +42,9 @@ export class PickController extends BaseController<PickControllerData> implement
     this.logger.debug({ count, data, list, puck }, 'picking item');
     return this.reply(ctx, puck.join(','));
   }
+
+  @Handler(NOUN_PICK, CommandVerb.Help)
+  public async getHelp(cmd: Command, ctx: Context): Promise<void> {
+    return this.reply(ctx, this.defaultHelp(cmd));
+  }
 }

src/controller/SearchController.ts

@@ -54,4 +54,9 @@ export class SearchController extends BaseController<SearchControllerData> imple
 
     return this.transformJSON(cmd, response);
   }
+
+  @Handler(NOUN_SEARCH, CommandVerb.Help)
+  public async getHelp(cmd: Command, ctx: Context): Promise<void> {
+    return this.reply(ctx, this.defaultHelp(cmd));
+  }
 }

src/controller/SedController.ts

@@ -30,7 +30,7 @@ export class SedController extends BaseController<SedControllerData> implements
     const parts = expr.match(/\/((?:[^\\]|\\.)*)\/((?:[^\\]|\\.)*)\/([gmiuy]*)/);
     if (isNil(parts)) {
       this.logger.debug({ expr }, 'invalid input.');
-      return this.reply(ctx, this.locale.translate('service.controller.sed.invalid'));
+      return this.reply(ctx, this.translate('create.invalid'));
     }
 
     this.logger.debug({ parts }, 'fetching messages');
@@ -47,12 +47,17 @@ export class SedController extends BaseController<SedControllerData> implements
         }
       }
 
-      return this.reply(ctx, this.locale.translate('service.controller.sed.missing'));
+      return this.reply(ctx, this.translate('create.missing'));
     } catch (error) {
       this.logger.error('Failed to fetch messages.');
     }
   }
 
+  @Handler(NOUN_SED, CommandVerb.Help)
+  public async getHelp(cmd: Command, ctx: Context): Promise<void> {
+    return this.reply(ctx, this.defaultHelp(cmd));
+  }
+
   private async processMessage(message: Message, command: Command, parts: RegExpMatchArray): Promise<boolean> {
     if (doesExist(message.context) && doesExist(command.context) && message.context.channel.thread === command.context.channel.thread) {
       return false;

src/controller/TimeController.ts

@@ -36,8 +36,13 @@ export class TimeController extends BaseController<TimeControllerData> implement
     const zone = cmd.getHeadOrDefault('zone', this.data.zone);
 
     this.logger.debug({ locale, time, zone }, 'handling time');
-    return this.reply(ctx, this.locale.translate('service.controller.time.get', {
+    return this.reply(ctx, this.translate('get.success', {
       time,
     }));
   }
+
+  @Handler(NOUN_TIME, CommandVerb.Help)
+  public async getHelp(cmd: Command, ctx: Context): Promise<void> {
+    return this.reply(ctx, this.defaultHelp(cmd));
+  }
 }

src/controller/TokenController.ts

@@ -70,7 +70,7 @@ export class TokenController extends BaseController<TokenControllerData> impleme
     const user = this.getUserOrFail(ctx);
     const before = cmd.getHeadOrNumber('before', this.clock.getSeconds());
     if (cmd.getHeadOrDefault('confirm', 'no') !== 'yes') {
-      const completion = createCompletion(cmd, 'confirm', this.locale.translate('service.controller.token.delete.confirm', {
+      const completion = createCompletion(cmd, 'confirm', this.translate('delete.confirm', {
         before,
         name: user.name,
       }));
@@ -83,7 +83,7 @@ export class TokenController extends BaseController<TokenControllerData> impleme
       subject: Equal(mustExist(user.id)),
     });
 
-    return this.reply(ctx, `tokens deleted`);
+    return this.reply(ctx, this.translate('delete.success'));
   }
 
   @Handler(NOUN_TOKEN, CommandVerb.Get)
@@ -97,13 +97,13 @@ export class TokenController extends BaseController<TokenControllerData> impleme
         });
         return this.reply(ctx, JSON.stringify(data));
       } catch (err) {
-        return this.reply(ctx, this.locale.translate('service.controller.token.get.invalid', {
+        return this.reply(ctx, this.translate('get.invalid', {
           msg: err.message,
         }));
       }
     } else {
       if (isNil(ctx.token)) {
-        return this.reply(ctx, this.locale.translate('service.controller.token.get.missing'));
+        return this.reply(ctx, this.translate('get.missing'));
       } else {
         return this.reply(ctx, ctx.token.toString());
       }
@@ -122,4 +122,9 @@ export class TokenController extends BaseController<TokenControllerData> impleme
 
     return this.reply(ctx, JSON.stringify(tokens));
   }
+
+  @Handler(NOUN_TOKEN, CommandVerb.Help)
+  public async getHelp(cmd: Command, ctx: Context): Promise<void> {
+    return this.reply(ctx, this.defaultHelp(cmd));
+  }
 }