📝 CLI: better dev documentation and argument description (#438)

.gitignore

@@ -0,0 +1,13 @@
+
+# Devenv
+.devenv*
+devenv.local.nix
+
+# direnv
+.direnv
+
+# pre-commit
+.pre-commit-config.yaml
+
+docker-data
+node_modules

tdrive/backend/node/README.md

@@ -68,16 +68,6 @@ choices (or we're using it wrong).
 eval "$(bin/twake-cli completion)"
 ```
 
-#### Bash completion
-
-It's a bit awkward to do real completion from a configuration since this isn't really a node module we recommend to install globally.
-This should setup a shell if you're in the right path however. It's yarg's auto generated completion though; so eg: it mixes up commands and
-choices (or we're using it wrong).
-
-```sh
-eval "$(bin/twake-cli completion)"
-```
-
 ### Component Framework
 
 The backend is developed using a software component approach in order to compose and adapt the platform based on needs and constraints.

tdrive/backend/node/src/cli/cmds/search_cmds/index_all.ts

@@ -22,6 +22,7 @@ type Options = {
   repairEntities: boolean;
 };
 
+const repairEntitiesArgumentDetails = [];
 const waitTimeoutMS = (ms: number) => ms > 0 && new Promise(r => setTimeout(r, ms));
 const defaultPageSize = "100";
 
@@ -41,6 +42,9 @@ async function iterateOverRepoPages<Entity>(
   } while (page.page_token);
 }
 
+/** This is an abstract base class for re-index cli commands; it stores runtime options
+ *  into fields; runs repair first if request and re-indexes generically from the database
+ *  to search services. */
 abstract class ReindexerCLICommand<Entity> {
   protected readonly database: DatabaseServiceAPI;
   protected readonly search: SearchServiceAPI;
@@ -80,6 +84,9 @@ abstract class ReindexerCLICommand<Entity> {
     this.options.spinner.info(`${this.table} > ${info}`);
   }
 
+  /** Override in sub-classes to translate a page from database to search entities.
+   * This is called by `reindexFromDBToSearch` so if that is overriden; this won't be called.
+   */
   protected async repairEntities(): Promise<void> {
     this.statusWarn(`repairEntities > No repair action for ${this.table}`);
   }
@@ -88,6 +95,11 @@ abstract class ReindexerCLICommand<Entity> {
     return entities;
   }
 
+  /** Override in a sub-class to completely replace the re-indexing logic.
+   * - Iterates over pages of the entity from the database repository
+   *     - calls `mapEntitiesToReIndexFromDBToSearch` to convert each page to a search entity
+   *     - and upserts the result into the search repository
+   */
   protected async reindexFromDBToSearch(): Promise<void> {
     const repository = await this.dbRepository();
     this.statusStart("Start indexing...");
@@ -105,6 +117,8 @@ abstract class ReindexerCLICommand<Entity> {
     await waitTimeoutMS(giveFlushAChanceDurationMS);
     this.statusSucceed("Done!");
   }
+
+  /** Run both operations: repair if requested and re-index */
   public async run(): Promise<void> {
     if (this.options.repairEntities) await this.repairEntities();
     await this.reindexFromDBToSearch();
@@ -149,6 +163,9 @@ RepositoryNameToCTOR.set(
   "users",
   (platform, options) => new UserReindexerCLICommand(platform, options),
 );
+repairEntitiesArgumentDetails.push(
+  "users: Rebuild cache.companies and save to database if changed",
+);
 
 class DocumentsReindexerCLICommand extends ReindexerCLICommand<DriveFile> {
   constructor(platform: TdrivePlatform, options: Options) {
@@ -159,6 +176,9 @@ RepositoryNameToCTOR.set(
   "documents",
   (platform, options) => new DocumentsReindexerCLICommand(platform, options),
 );
+repairEntitiesArgumentDetails.push(
+  "documents: Download and re-extract keywords before re-indexing",
+);
 
 const reindexingArgumentGroupTitle = "Re-indexing options";
 const repositoryArgumentName = "repository";
@@ -176,7 +196,9 @@ const command: yargs.CommandModule<unknown, unknown> = {
     repairEntities: {
       default: false,
       type: "boolean",
-      description: "Repair entities too when possible",
+      description: ["Repair entities too when possible", ...repairEntitiesArgumentDetails].join(
+        "\n- ",
+      ),
       group: reindexingArgumentGroupTitle,
     },
   },