@memlab/cli 1.0.3 → 1.0.4

package/dist/BaseCommand.d.ts

@@ -30,6 +30,7 @@ export default class BaseCommand extends Command {
     getPrerequisites(): BaseCommand[];
     isInternalCommand(): boolean;
     getOptions(): BaseOption[];
+    getExcludedOptions(): BaseOption[];
     getSubCommands(): BaseCommand[];
     run(_options: CLIOptions): Promise<void>;
 }

package/dist/BaseCommand.js

@@ -55,21 +55,23 @@ class Command {
         const uniqueOptions = new Map();
         const visitedCommands = new Set();
         const queue = [self];
+        const excludedOptions = new Set(self.getExcludedOptions().map(option => option.getOptionName()));
         while (queue.length > 0) {
             const cur = queue.shift();
-            if (cur) {
-                const options = cur.getOptions();
-                for (const option of options) {
-                    const optionName = option.getOptionName();
-                    if (!uniqueOptions.has(optionName)) {
-                        uniqueOptions.set(optionName, option);
-                    }
+            const options = cur.getOptions();
+            for (const option of options) {
+                const optionName = option.getOptionName();
+                if (excludedOptions.has(optionName)) {
+                    continue;
                 }
-                visitedCommands.add(cur.getCommandName());
-                for (const prereq of cur.getPrerequisites()) {
-                    if (!visitedCommands.has(prereq.getCommandName())) {
-                        queue.push(prereq);
-                    }
+                if (!uniqueOptions.has(optionName)) {
+                    uniqueOptions.set(optionName, option);
+                }
+            }
+            visitedCommands.add(cur.getCommandName());
+            for (const prereq of cur.getPrerequisites()) {
+                if (!visitedCommands.has(prereq.getCommandName())) {
+                    queue.push(prereq);
                 }
             }
         }
@@ -112,6 +114,13 @@ class BaseCommand extends Command {
     getOptions() {
         return [];
     }
+    // commands from getPrerequisites may propagate
+    // options that does not make sense for the
+    // current command, this returns the list of
+    // options that should be excluded from helper text
+    getExcludedOptions() {
+        return [];
+    }
     // get subcommands of this command
     // for example command 'A' has two sub-commands 'B' and 'C'
     // CLI supports running in terminal: `memlab A B` or `memlab A C`

package/dist/CommandLoader.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @emails oncall+ws_labs
+ * @format
+ */
+import BaseCommand from './BaseCommand';
+export default class CommandLoader {
+    private isLoaded;
+    private OSSModules;
+    private modules;
+    private modulePaths;
+    getModules(): Map<string, BaseCommand>;
+    getModulePaths(): Map<string, string>;
+    registerCommands(): void;
+    private registerCommandsFromDir;
+    private postRegistration;
+}
+//# sourceMappingURL=CommandLoader.d.ts.map

package/dist/CommandLoader.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @emails oncall+ws_labs
+ * @format
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const core_1 = require("@memlab/core");
+const BaseCommand_1 = __importDefault(require("./BaseCommand"));
+const GenerateCLIDocCommand_1 = __importDefault(require("./commands/helper/GenerateCLIDocCommand"));
+class CommandLoader {
+    constructor() {
+        this.isLoaded = false;
+        this.OSSModules = new Map();
+        this.modules = new Map();
+        this.modulePaths = new Map();
+    }
+    getModules() {
+        if (!this.isLoaded) {
+            this.registerCommands();
+        }
+        return this.modules;
+    }
+    getModulePaths() {
+        if (!this.isLoaded) {
+            this.registerCommands();
+        }
+        return this.modulePaths;
+    }
+    registerCommands() {
+        const modulesDir = path_1.default.resolve(__dirname, 'commands');
+        this.registerCommandsFromDir(modulesDir);
+        this.postRegistration();
+    }
+    registerCommandsFromDir(modulesDir) {
+        const moduleFiles = fs_1.default.readdirSync(modulesDir);
+        for (const moduleFile of moduleFiles) {
+            const modulePath = path_1.default.join(modulesDir, moduleFile);
+            // recursively import modules from subdirectories
+            if (fs_1.default.lstatSync(modulePath).isDirectory()) {
+                this.registerCommandsFromDir(modulePath);
+                continue;
+            }
+            // only import modules files ends with with Command.js
+            if (!moduleFile.endsWith('Command.js')) {
+                continue;
+            }
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const module = require(modulePath);
+            const moduleConstructor = typeof module.default === 'function' ? module.default : module;
+            const moduleInstance = new moduleConstructor();
+            if (!(moduleInstance instanceof BaseCommand_1.default)) {
+                core_1.utils.haltOrThrow('loading a command that does not extend BaseCommand');
+            }
+            const commandName = moduleInstance.getCommandName();
+            const loadingOssCommand = !core_1.fileManager.isWithinInternalDirectory(modulePath);
+            // reigster OSS commands
+            if (loadingOssCommand) {
+                this.OSSModules.set(commandName, moduleInstance);
+            }
+            // register all commands
+            if (this.modules.has(commandName)) {
+                // resolve conflict
+                const ossCommandLoaded = !core_1.fileManager.isWithinInternalDirectory(this.modulePaths.get(commandName));
+                if (ossCommandLoaded === loadingOssCommand) {
+                    // when both commands are open source or neither are open source
+                    core_1.info.midLevel(`MemLab command ${commandName} is already registered`);
+                }
+                else if (!ossCommandLoaded && loadingOssCommand) {
+                    // when open source command tries to overwrite non-open source command
+                    continue;
+                }
+            }
+            this.modules.set(commandName, moduleInstance);
+            this.modulePaths.set(commandName, modulePath);
+        }
+    }
+    postRegistration() {
+        const cliDocCommand = new GenerateCLIDocCommand_1.default();
+        const instance = this.modules.get(cliDocCommand.getCommandName());
+        if (instance) {
+            instance.setModulesMap(this.OSSModules);
+        }
+    }
+}
+exports.default = CommandLoader;

package/dist/Dispatcher.d.ts

@@ -8,7 +8,7 @@
  * @format
  */
 import type { ParsedArgs } from 'minimist';
-import { MemLabConfig, AnyRecord } from '@memlab/core';
+import type { AnyRecord, MemLabConfig } from '@memlab/core';
 import BaseCommand from './BaseCommand';
 declare type RunCommandOptions = {
     isPrerequisite?: boolean;
@@ -17,7 +17,6 @@ declare type RunCommandOptions = {
 };
 declare class CommandDispatcher {
     private modules;
-    private modulePaths;
     private executedCommands;
     private executingCommandStack;
     constructor();
@@ -26,9 +25,6 @@ declare class CommandDispatcher {
     private runCommand;
     runSubCommandIfAny(command: BaseCommand, args: ParsedArgs, runCmdOpt: RunCommandOptions): Promise<void>;
     private helper;
-    private registerBuiltInCommands;
-    private registerCommands;
-    private registerCommandsFromDir;
 }
 declare const _default: CommandDispatcher;
 export default _default;

package/dist/Dispatcher.js

@@ -22,40 +22,23 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@memlab/core");
-const fs_1 = __importDefault(require("fs"));
-const path_1 = __importDefault(require("path"));
-const core_2 = require("@memlab/core");
-const BaseCommand_1 = __importDefault(require("./BaseCommand"));
 const HelperCommand_1 = __importDefault(require("./commands/helper/HelperCommand"));
-const VerboseOption_1 = __importDefault(require("./options/VerboseOption"));
-const SetContinuousTestOption_1 = __importDefault(require("./options/SetContinuousTestOption"));
-const DebugOption_1 = __importDefault(require("./options/DebugOption"));
-const SilentOption_1 = __importDefault(require("./options/SilentOption"));
-const HelperOption_1 = __importDefault(require("./options/HelperOption"));
-const universalOptions = [
-    new HelperOption_1.default(),
-    new VerboseOption_1.default(),
-    new SetContinuousTestOption_1.default(),
-    new DebugOption_1.default(),
-    new SilentOption_1.default(),
-];
+const UniversalOptions_1 = __importDefault(require("./options/lib/UniversalOptions"));
+const CommandLoader_1 = __importDefault(require("./CommandLoader"));
 const helperCommand = new HelperCommand_1.default();
-helperCommand.setUniversalOptions(universalOptions);
 class CommandDispatcher {
     constructor() {
         this.executedCommands = new Set();
         this.executingCommandStack = [];
         // auto load all command modules
-        this.modules = new Map();
-        this.modulePaths = new Map();
-        this.registerBuiltInCommands();
-        this.registerCommands();
+        const commandLoader = new CommandLoader_1.default();
+        this.modules = commandLoader.getModules();
     }
     dispatch(args) {
         return __awaiter(this, void 0, void 0, function* () {
             // triggered by `memlab` (without specific command)
             if (!args._ || !(args._.length >= 1)) {
-                core_2.info.error('\n  command argument missing');
+                core_1.info.error('\n  command argument missing');
                 yield this.helper(args);
                 return;
             }
@@ -83,7 +66,7 @@ class CommandDispatcher {
     }
     parseOptions(command, config, args) {
         return __awaiter(this, void 0, void 0, function* () {
-            const options = [...universalOptions, ...command.getOptions()];
+            const options = [...UniversalOptions_1.default, ...command.getOptions()];
             const configFromOptions = Object.create(null);
             for (const option of options) {
                 const ret = yield option.run(config, args);
@@ -113,7 +96,7 @@ class CommandDispatcher {
                 yield this.runCommand(prereq, args, Object.assign({ isPrerequisite: true }, runCmdOpt));
             }
             // parse command line options
-            const c = yield this.parseOptions(command, core_2.config, args);
+            const c = yield this.parseOptions(command, core_1.config, args);
             Object.assign(runCmdOpt.configFromOptions, c);
             const { configFromOptions } = runCmdOpt;
             // execute command
@@ -142,7 +125,7 @@ class CommandDispatcher {
                     return;
                 }
             }
-            core_2.info.error(`Invalid sub-command \`${args._[subCommandIndex]}\` of \`${command.getCommandName()}\`\n`);
+            core_1.info.error(`Invalid sub-command \`${args._[subCommandIndex]}\` of \`${command.getCommandName()}\`\n`);
             yield this.helper(args, command);
         });
     }
@@ -156,50 +139,5 @@ class CommandDispatcher {
             });
         });
     }
-    registerBuiltInCommands() {
-        // TBA
-    }
-    registerCommands() {
-        const modulesDir = path_1.default.resolve(__dirname, 'commands');
-        this.registerCommandsFromDir(modulesDir);
-    }
-    registerCommandsFromDir(modulesDir) {
-        const moduleFiles = fs_1.default.readdirSync(modulesDir);
-        for (const moduleFile of moduleFiles) {
-            const modulePath = path_1.default.join(modulesDir, moduleFile);
-            // recursively import modules from subdirectories
-            if (fs_1.default.lstatSync(modulePath).isDirectory()) {
-                this.registerCommandsFromDir(modulePath);
-                continue;
-            }
-            // only import modules files ends with with Command.js
-            if (!moduleFile.endsWith('Command.js')) {
-                continue;
-            }
-            // eslint-disable-next-line @typescript-eslint/no-var-requires
-            const module = require(modulePath);
-            const moduleConstructor = typeof module.default === 'function' ? module.default : module;
-            const moduleInstance = new moduleConstructor();
-            if (!(moduleInstance instanceof BaseCommand_1.default)) {
-                core_1.utils.haltOrThrow('loading a command that does not extend BaseCommand');
-            }
-            const commandName = moduleInstance.getCommandName();
-            if (this.modules.has(commandName)) {
-                // resolve conflict
-                const ossCommandLoaded = !core_2.fileManager.isWithinInternalDirectory(this.modulePaths.get(commandName));
-                const loadingOssCommand = !core_2.fileManager.isWithinInternalDirectory(modulePath);
-                if (ossCommandLoaded === loadingOssCommand) {
-                    // when both commands are open source or neither are open source
-                    core_2.info.midLevel(`MemLab command ${commandName} is already registered`);
-                }
-                else if (!ossCommandLoaded && loadingOssCommand) {
-                    // when open source command tries to overwrite non-open source command
-                    continue;
-                }
-            }
-            this.modules.set(commandName, moduleInstance);
-            this.modulePaths.set(commandName, modulePath);
-        }
-    }
 }
 exports.default = new CommandDispatcher();

package/dist/commands/MemLabRunCommand.d.ts

@@ -8,13 +8,15 @@
  * @format
  */
 import type { BaseOption, CLIOptions } from '@memlab/core';
-import BaseCommand from '../BaseCommand';
+import BaseCommand, { CommandCategory } from '../BaseCommand';
 export default class MemLabRunCommand extends BaseCommand {
     getCommandName(): string;
     getDescription(): string;
     getExamples(): string[];
     getPrerequisites(): BaseCommand[];
     getOptions(): BaseOption[];
+    getExcludedOptions(): BaseOption[];
+    getCategory(): CommandCategory;
     run(options: CLIOptions): Promise<void>;
 }
 //# sourceMappingURL=MemLabRunCommand.d.ts.map

package/dist/commands/MemLabRunCommand.js

@@ -8,6 +8,29 @@
  * @emails oncall+ws_labs
  * @format
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -24,11 +47,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const core_1 = require("@memlab/core");
-const BaseCommand_1 = __importDefault(require("../BaseCommand"));
+const BaseCommand_1 = __importStar(require("../BaseCommand"));
 const CheckLeakCommand_1 = __importDefault(require("./heap/CheckLeakCommand"));
 const InitDirectoryCommand_1 = __importDefault(require("./InitDirectoryCommand"));
 const TakeSnapshotCommand_1 = __importDefault(require("./snapshot/TakeSnapshotCommand"));
 const SetWorkingDirectoryOption_1 = __importDefault(require("../options/SetWorkingDirectoryOption"));
+const AppOption_1 = __importDefault(require("../options/AppOption"));
+const InteractionOption_1 = __importDefault(require("../options/InteractionOption"));
+const SkipSnapshotOption_1 = __importDefault(require("../options/SkipSnapshotOption"));
+const RunningModeOption_1 = __importDefault(require("../options/RunningModeOption"));
+const BaselineFileOption_1 = __importDefault(require("../options/heap/BaselineFileOption"));
+const TargetFileOption_1 = __importDefault(require("../options/heap/TargetFileOption"));
+const FinalFileOption_1 = __importDefault(require("../options/heap/FinalFileOption"));
+const SnapshotDirectoryOption_1 = __importDefault(require("../options/heap/SnapshotDirectoryOption"));
+const JSEngineOption_1 = __importDefault(require("../options/heap/JSEngineOption"));
 class MemLabRunCommand extends BaseCommand_1.default {
     getCommandName() {
         return 'run';
@@ -37,7 +69,11 @@ class MemLabRunCommand extends BaseCommand_1.default {
         return 'find memory leaks in web apps';
     }
     getExamples() {
-        return ['--app=comet --interaction=watch'];
+        return [
+            '--scenario <TEST_SCENARIO_FILE>',
+            '--scenario /tmp/test-scenario.js',
+            '--scenario /tmp/test-scenario.js --work-dir /tmp/test-1/',
+        ];
     }
     getPrerequisites() {
         return [
@@ -49,6 +85,22 @@ class MemLabRunCommand extends BaseCommand_1.default {
     getOptions() {
         return [new SetWorkingDirectoryOption_1.default()];
     }
+    getExcludedOptions() {
+        return [
+            new AppOption_1.default(),
+            new InteractionOption_1.default(),
+            new SkipSnapshotOption_1.default(),
+            new RunningModeOption_1.default(),
+            new BaselineFileOption_1.default(),
+            new TargetFileOption_1.default(),
+            new FinalFileOption_1.default(),
+            new SnapshotDirectoryOption_1.default(),
+            new JSEngineOption_1.default(),
+        ];
+    }
+    getCategory() {
+        return BaseCommand_1.CommandCategory.COMMON;
+    }
     run(options) {
         var _a;
         return __awaiter(this, void 0, void 0, function* () {

package/dist/commands/RunMeasureCommand.d.ts

@@ -14,6 +14,7 @@ export default class RunMeasureCommand extends BaseCommand {
     getCommandName(): string;
     getDescription(): string;
     getPrerequisites(): BaseCommand[];
+    getExamples(): string[];
     getOptions(): BaseOption[];
     run(options: CLIOptions): Promise<void>;
 }

package/dist/commands/RunMeasureCommand.js

@@ -50,6 +50,13 @@ class RunMeasureCommand extends BaseCommand_1.default {
     getPrerequisites() {
         return [new CleanRunDataCommand_1.default(), new InitDirectoryCommand_1.default()];
     }
+    getExamples() {
+        return [
+            '--scenario <TEST_SCENARIO_FILE>',
+            '--scenario /tmp/test-scenario.js',
+            '--scenario /tmp/test-scenario.js --work-dir /tmp/test-1/',
+        ];
+    }
     getOptions() {
         return [
             new NumberOfRunsOption_1.default(),

package/dist/commands/WarmupAppCommand.d.ts

@@ -14,6 +14,7 @@ export default class FBWarmupAppCommand extends BaseCommand {
     getCommandName(): string;
     getDescription(): string;
     getPrerequisites(): BaseCommand[];
+    getExamples(): string[];
     getOptions(): BaseOption[];
     run(_options: CLIOptions): Promise<void>;
 }

package/dist/commands/WarmupAppCommand.js

@@ -43,6 +43,12 @@ class FBWarmupAppCommand extends BaseCommand_1.default {
     getPrerequisites() {
         return [new InitDirectoryCommand_1.default(), new CheckXvfbSupportCommand_1.default()];
     }
+    getExamples() {
+        return [
+            '--scenario <TEST_SCENARIO_FILE>',
+            '--scenario /tmp/test-scenario.js',
+        ];
+    }
     getOptions() {
         return [
             new AppOption_1.default(),

package/dist/commands/heap/GetRetainerTraceCommand.js

@@ -69,7 +69,11 @@ class GetRetainerTraceCommand extends BaseCommand_1.default {
         return BaseCommand_1.CommandCategory.COMMON;
     }
     getExamples() {
-        return ['--node-id=@3123123'];
+        return [
+            '--node-id=<HEAP_OBJECT_ID>',
+            '--node-id=@3123123',
+            '--node-id=128127',
+        ];
     }
     getOptions() {
         return [

package/dist/commands/helper/GenerateCLIDocCommand.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @emails oncall+ws_labs
+ * @format
+ */
+import type { CLIOptions } from '@memlab/core';
+import BaseCommand from '../../BaseCommand';
+export default class GenerateCLIDocCommand extends BaseCommand {
+    private modules;
+    private generatedCommandInIndex;
+    private universalOptions;
+    getCommandName(): string;
+    getDescription(): string;
+    isInternalCommand(): boolean;
+    setModulesMap(modules: Map<string, BaseCommand>): void;
+    run(options: CLIOptions): Promise<void>;
+    private generateDocs;
+    private writeCommandCategories;
+    private writeCategory;
+    private writeCategoryHeader;
+    private writeCommand;
+    private writeTextWithNewLine;
+    private touchFile;
+    private writeCodeBlock;
+    private writeCommandOptions;
+}
+//# sourceMappingURL=GenerateCLIDocCommand.d.ts.map

package/dist/commands/helper/GenerateCLIDocCommand.js

@@ -0,0 +1,207 @@
+"use strict";
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @emails oncall+ws_labs
+ * @format
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const BaseCommand_1 = __importStar(require("../../BaseCommand"));
+const core_1 = require("@memlab/core");
+const UniversalOptions_1 = __importDefault(require("../../options/lib/UniversalOptions"));
+class GenerateCLIDocCommand extends BaseCommand_1.default {
+    constructor() {
+        super(...arguments);
+        this.modules = new Map();
+        this.generatedCommandInIndex = new Set();
+        this.universalOptions = UniversalOptions_1.default;
+    }
+    getCommandName() {
+        return 'gen-cli-doc';
+    }
+    getDescription() {
+        return 'generate CLI markdown documentations';
+    }
+    isInternalCommand() {
+        return true;
+    }
+    setModulesMap(modules) {
+        this.modules = modules;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    run(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const docsDir = core_1.fileManager.getDocDir();
+            const cliDocsDir = path_1.default.join(docsDir, 'cli');
+            this.generateDocs(cliDocsDir);
+        });
+    }
+    generateDocs(cliDocsDir) {
+        // first clean up the dir
+        fs_extra_1.default.removeSync(cliDocsDir);
+        fs_extra_1.default.mkdirSync(cliDocsDir);
+        // create index markdown file
+        const indexFile = path_1.default.join(cliDocsDir, 'CLI-commands.md');
+        this.writeCommandCategories(indexFile);
+    }
+    writeCommandCategories(docFile) {
+        this.writeTextWithNewLine(docFile, '# Command Line Interface');
+        for (const category in BaseCommand_1.CommandCategory) {
+            const commandsToPrintFirst = [];
+            this.writeCategory(docFile, category, commandsToPrintFirst);
+        }
+    }
+    writeCategory(docFile, category, commandsToPrintFirst) {
+        // commands defined in commandsToPrintFirst
+        const commands = [];
+        for (const command of commandsToPrintFirst) {
+            const name = command.getCommandName();
+            if (this.generatedCommandInIndex.has(name)) {
+                continue;
+            }
+            commands.push(command);
+        }
+        // other commands in this category
+        for (const moduleEntries of this.modules) {
+            const command = moduleEntries[1];
+            if (category !== command.getCategory()) {
+                continue;
+            }
+            if (command.isInternalCommand() && !core_1.config.verbose) {
+                continue;
+            }
+            const name = command.getCommandName();
+            if (this.generatedCommandInIndex.has(name)) {
+                continue;
+            }
+            commands.push(command);
+        }
+        if (commands.length === 0) {
+            return;
+        }
+        this.writeCategoryHeader(docFile, category);
+        for (const command of commands) {
+            this.writeCommand(docFile, command);
+            this.generatedCommandInIndex.add(command.getCommandName());
+        }
+        this.writeTextWithNewLine(docFile, '');
+    }
+    writeCategoryHeader(docFile, category) {
+        const categoryName = category.toUpperCase();
+        this.writeTextWithNewLine(docFile, `\n## ${categoryName} Commands\n`);
+    }
+    writeCommand(docFile, command, indent = '') {
+        const name = command.getFullCommand();
+        const desc = core_1.utils.upperCaseFirstCharacter(command.getDescription());
+        // write command title
+        this.writeTextWithNewLine(docFile, `\n###${indent} memlab ${name}\n`);
+        // write description
+        this.writeTextWithNewLine(docFile, `${desc}\n`);
+        // get example
+        const examples = command.getExamples();
+        let example = '';
+        if (examples.length > 0) {
+            example = examples[0].trim();
+        }
+        // write command synopsis
+        const cmd = `memlab ${name} ${example}`;
+        this.writeCodeBlock(docFile, cmd, 'bash');
+        // write command examples if there is any
+        const exampleBlock = examples
+            .slice(1)
+            .map(example => `memlab ${name} ${example.trim()}`)
+            .join('\n');
+        if (exampleBlock.length > 0) {
+            this.writeTextWithNewLine(docFile, '\n#### examples\n');
+            this.writeCodeBlock(docFile, exampleBlock, 'bash');
+        }
+        // write options
+        this.writeCommandOptions(docFile, command);
+        const subCommands = command.getSubCommands();
+        for (const subCommand of subCommands) {
+            this.writeCommand(docFile, subCommand, indent + '#');
+        }
+    }
+    writeTextWithNewLine(docFile, content) {
+        this.touchFile(docFile);
+        fs_extra_1.default.appendFileSync(docFile, `${content}\n`, 'UTF-8');
+    }
+    touchFile(docFile) {
+        if (!fs_extra_1.default.existsSync(docFile)) {
+            fs_extra_1.default.writeFileSync(docFile, '', 'UTF-8');
+        }
+    }
+    writeCodeBlock(docFile, code, codeType = '') {
+        let normalizedCode = code;
+        while (normalizedCode.endsWith('\n')) {
+            normalizedCode = normalizedCode.slice(0, normalizedCode.length - 1);
+        }
+        this.touchFile(docFile);
+        fs_extra_1.default.appendFileSync(docFile, '```' + codeType + '\n' + normalizedCode + '\n```\n', 'UTF-8');
+    }
+    writeCommandOptions(docFile, command) {
+        const options = [
+            ...command.getFullOptionsFromPrerequisiteChain(),
+            ...this.universalOptions,
+        ];
+        if (options.length === 0) {
+            return;
+        }
+        this.writeTextWithNewLine(docFile, '\n**Options**:');
+        const optionsText = [];
+        for (const option of options) {
+            let header = `**\`--${option.getOptionName()}\`**`;
+            if (option.getOptionShortcut()) {
+                header += `, **\`-${option.getOptionShortcut()}\`**`;
+            }
+            const desc = option.getDescription();
+            optionsText.push({ header, desc });
+        }
+        for (const optionText of optionsText) {
+            const header = optionText.header;
+            const msg = ` * ${header}: ${optionText.desc}`;
+            this.writeTextWithNewLine(docFile, msg);
+        }
+    }
+}
+exports.default = GenerateCLIDocCommand;

package/dist/commands/helper/HelperCommand.js

@@ -50,11 +50,12 @@ const string_width_1 = __importDefault(require("string-width"));
 const core_1 = require("@memlab/core");
 const CommandOrder_1 = __importDefault(require("./lib/CommandOrder"));
 const BaseCommand_1 = __importStar(require("../../BaseCommand"));
+const UniversalOptions_1 = __importDefault(require("../../options/lib/UniversalOptions"));
 class HelperCommand extends BaseCommand_1.default {
     constructor() {
         super(...arguments);
         this.printedCommand = new Set();
-        this.universalOptions = [];
+        this.universalOptions = UniversalOptions_1.default;
     }
     // The following terminal command will initiate with this command
     // `memlab <command-name>`

package/dist/commands/snapshot/TakeSnapshotCommand.d.ts

@@ -14,6 +14,7 @@ export default class TakeSnapshotCommand extends BaseCommand {
     getCommandName(): string;
     getDescription(): string;
     getPrerequisites(): BaseCommand[];
+    getExamples(): string[];
     getOptions(): BaseOption[];
     run(_options: CLIOptions): Promise<void>;
 }

package/dist/commands/snapshot/TakeSnapshotCommand.js

@@ -53,6 +53,13 @@ class TakeSnapshotCommand extends BaseCommand_1.default {
             new CheckXvfbSupportCommand_1.default(),
         ];
     }
+    getExamples() {
+        return [
+            '--scenario <TEST_SCENARIO_FILE>',
+            '--scenario /tmp/test-scenario.js',
+            '--scenario /tmp/test-scenario.js --work-dir /tmp/test-1/',
+        ];
+    }
     getOptions() {
         return [
             new AppOption_1.default(),

package/dist/options/lib/UniversalOptions.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @emails oncall+ws_labs
+ * @format
+ */
+import DebugOption from '../DebugOption';
+import HelperOption from '../HelperOption';
+import SetContinuousTestOption from '../SetContinuousTestOption';
+import SilentOption from '../SilentOption';
+import VerboseOption from '../VerboseOption';
+declare const universalOptions: (DebugOption | HelperOption | SetContinuousTestOption | SilentOption | VerboseOption)[];
+export default universalOptions;
+//# sourceMappingURL=UniversalOptions.d.ts.map

package/dist/options/lib/UniversalOptions.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @emails oncall+ws_labs
+ * @format
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const DebugOption_1 = __importDefault(require("../DebugOption"));
+const HelperOption_1 = __importDefault(require("../HelperOption"));
+const SetContinuousTestOption_1 = __importDefault(require("../SetContinuousTestOption"));
+const SilentOption_1 = __importDefault(require("../SilentOption"));
+const VerboseOption_1 = __importDefault(require("../VerboseOption"));
+const universalOptions = [
+    new HelperOption_1.default(),
+    new VerboseOption_1.default(),
+    new SetContinuousTestOption_1.default(),
+    new DebugOption_1.default(),
+    new SilentOption_1.default(),
+];
+exports.default = universalOptions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memlab/cli",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "license": "MIT",
   "description": "command line interface for memlab",
   "author": "Liang Gong <lgong@fb.com>",
@@ -55,6 +55,7 @@
   },
   "scripts": {
     "build-pkg": "tsc",
+    "publish-patch": "npm version patch --force && npm publish",
     "clean-pkg": "rm -rf ./dist && rm -rf ./node_modules && rm -f ./tsconfig.tsbuildinfo"
   },
   "bugs": {