mdat-plugin-cli-help 2.1.2 → 3.0.0

package/dist/index.d.ts

@@ -7,7 +7,7 @@ import { ILogBasic, ILogLayer } from "lognow";
  * Export this for library consumers to inject their own logger.
  * @param logger - Accepts either a LogLayer instance or a Console- or Stream-like log target
  */
-declare function setLogger(logger?: ILogBasic | ILogLayer): void;
+declare function setLogger(logger?: ILogBasic | ILogLayer<unknown>): void;
 //#endregion
 //#region src/index.d.ts
 declare const _default: _$mdat.Config;

package/dist/index.js

@@ -382,25 +382,25 @@ var CliHelpToObjectVisitor$2 = class extends parser$2.getBaseCstVisitorConstruct
 	* Clean a Commander default value: strip `(default: ...)` wrapper, env info, and quotes.
 	*/
 	cleanDefault(text) {
-		if (text === void 0) return void 0;
+		if (text === void 0) return;
 		let cleaned = text.replaceAll(/^\(default:\s*/g, "").replaceAll(/\)$/g, "").trim();
 		cleaned = cleaned.replaceAll(/,\s*env:\s*\S+$/g, "").trim();
 		cleaned = cleaned.replaceAll(/^["']|["']$/g, "");
 		return cleaned || void 0;
 	}
 	getArray(context) {
-		if (context === void 0) return void 0;
+		if (context === void 0) return;
 		return context.map((entry) => entry.image);
 	}
 	getString(context) {
-		if (context === void 0) return void 0;
+		if (context === void 0) return;
 		return context.map((entry) => entry.image).join(" ");
 	}
 	/**
 	* Trim leading/trailing whitespace from description text.
 	*/
 	trimDescription(text) {
-		if (text === void 0) return void 0;
+		if (text === void 0) return;
 		return text.trim() || void 0;
 	}
 };
@@ -647,11 +647,11 @@ var CliHelpToObjectVisitor$1 = class extends parser$1.getBaseCstVisitorConstruct
 		return text.replaceAll(/^[\s[]*(default:)?\s*|[\s\]]*$/g, "");
 	}
 	getArray(context) {
-		if (context === void 0) return void 0;
+		if (context === void 0) return;
 		return context.map((entry) => entry.image);
 	}
 	getString(context, clean = false) {
-		if (context === void 0) return void 0;
+		if (context === void 0) return;
 		return context.map((entry) => clean ? this.clean(entry.image) : entry.image).join(" ");
 	}
 };
@@ -950,11 +950,11 @@ var CliHelpToObjectVisitor = class extends parser.getBaseCstVisitorConstructor()
 		return text.replaceAll(/^[\s[]*(default:)?\s*|[\s\]]*$/g, "");
 	}
 	getArray(context) {
-		if (context === void 0) return void 0;
+		if (context === void 0) return;
 		return context.map((entry) => entry.image);
 	}
 	getString(context, clean = false) {
-		if (context === void 0) return void 0;
+		if (context === void 0) return;
 		return context.map((entry) => clean ? this.clean(entry.image) : entry.image).join(" ");
 	}
 	positionalParentCommandToArguments(object) {
@@ -966,7 +966,7 @@ var CliHelpToObjectVisitor = class extends parser.getBaseCstVisitorConstructor()
 		};
 	}
 	splitChoices(text) {
-		if (text === void 0) return void 0;
+		if (text === void 0) return;
 		return this.clean(text.replaceAll(/^\[choices:\s/g, "")).split(", ");
 	}
 };
@@ -1073,12 +1073,15 @@ function helpStringToObject(helpString) {
 /**
 * Get help output from a CLI command and return it as markdown
 *
-* @param cliCommand - The executable path (may contain spaces, e.g. on Windows)
+* @param command - The executable path (may contain spaces, e.g. on Windows)
 * @param helpFlag - The flag to pass to get help output
 * @param depth - Max recursion depth for subcommands
+* @param subcommands - Initial subcommand path to invoke before the help flag
+*   (e.g. `['remote', 'add']` produces `command remote add --help`).
+*   Discovered subcommands are appended to this path during recursion.
 */
-async function getHelpMarkdown(cliCommand, helpFlag = "--help", depth) {
-	return getHelpMarkdownInternal(cliCommand, [], helpFlag, depth ?? Number.MAX_SAFE_INTEGER);
+async function getHelpMarkdown(command, helpFlag = "--help", depth, subcommands = []) {
+	return getHelpMarkdownInternal(command, subcommands, helpFlag, depth ?? Number.MAX_SAFE_INTEGER);
 }
 async function getHelpMarkdownInternal(executable, subcommands, helpFlag, depth) {
 	const rawHelpString = await getHelpString(executable, [...subcommands, helpFlag]);
@@ -1152,16 +1155,16 @@ async function isExecutable(filePath, strictExtensions = false) {
 //#region src/utilities/infer-command.ts
 /**
 * Accommodate missing or sloppy cli help command input
-* @param cliCommand - Can be nothing, a command name on the path like `git`, or a path to an executable like `./bin/cli.js`
+* @param command - Can be nothing, a command name on the path like `git`, or a path to an executable like `./bin/cli.js`
 * @returns The path to a verified executable
 * @throws {Error} If nothing can be inferred or resolved
 */
-async function inferCommand(cliCommand) {
-	cliCommand ??= await getFirstBinFromPackage();
-	return ensureExecutable(cliCommand);
+async function inferCommand(command) {
+	command ??= await getFirstBinFromPackage();
+	return ensureExecutable(command);
 }
 function firstOf(value) {
-	if (value === void 0) return void 0;
+	if (value === void 0) return;
 	return Array.isArray(value) ? value[0] : value;
 }
 async function getFirstBinFromPackage() {
@@ -1176,7 +1179,7 @@ async function getFirstBinFromPackage() {
 			return binPath;
 		}
 	}
-	throw new Error(`Could not infer which command to run for the <!-- cli-help --> rule. Please pass a "cliCommand" option to the expansion comment, e.g. <!-- cli-help({cliCommand: './dist/bin.js'}) -->`);
+	throw new Error(`Could not infer which command to run for the <!-- cli-help --> rule. Please pass a "command" option to the expansion comment, e.g. <!-- cli-help({command: './dist/bin.js'}) -->`);
 }
 function looksLikePath(maybePath) {
 	const parsed = path.parse(maybePath);
@@ -1202,13 +1205,17 @@ async function getCommandPathFromPackage(commandName) {
 }
 //#endregion
 //#region src/index.ts
+const WHITESPACE_REGEX = /\s+/;
 const cliHelpRule = defineConfig({ cli: { async content(options, _context) {
 	const validOptions = z.object({
-		cliCommand: z.string().optional(),
+		command: z.string().optional(),
 		depth: z.number().optional(),
-		helpFlag: z.string().optional()
-	}).optional().parse(options);
-	return getHelpMarkdown(await inferCommand(validOptions?.cliCommand), validOptions?.helpFlag, validOptions?.depth);
+		helpFlag: z.string().optional(),
+		subcommand: z.string().optional()
+	}).strict().optional().parse(options);
+	const resolvedCommand = await inferCommand(validOptions?.command);
+	const subcommands = validOptions?.subcommand?.split(WHITESPACE_REGEX).filter(Boolean) ?? [];
+	return getHelpMarkdown(resolvedCommand, validOptions?.helpFlag, validOptions?.depth, subcommands);
 } } });
 var src_default = defineConfig({
 	cli: cliHelpRule.cli,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdat-plugin-cli-help",
-  "version": "2.1.2",
+  "version": "3.0.0",
   "description": "Mdat plugin to generate tabular help documentation for CLI tools in Markdown files.",
   "keywords": [
     "markdown",
@@ -39,21 +39,22 @@
     "chevrotain": "^12.0.0",
     "execa": "^9.6.1",
     "lognow": "^0.6.1",
-    "type-fest": "^5.5.0",
+    "type-fest": "^5.6.0",
     "which": "^6.0.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@kitschpatrol/shared-config": "^7.1.0",
+    "@kitschpatrol/shared-config": "^7.5.0",
     "@types/node": "~22.17.2",
     "@types/yargs": "^17.0.35",
     "bumpp": "^11.0.1",
     "commander": "^14.0.3",
-    "mdat": "^2.2.1",
+    "mdat": "^2.3.0",
     "meow": "^14.1.0",
-    "tsdown": "^0.21.7",
+    "shx": "^0.4.0",
+    "tsdown": "^0.21.10",
     "typescript": "~5.9.3",
-    "vitest": "^4.1.3",
+    "vitest": "^4.1.5",
     "yargs": "^18.0.0"
   },
   "peerDependencies": {
@@ -72,10 +73,10 @@
     "bench": "vitest bench --run --no-file-parallelism --compare test/benchmarks/baseline.json",
     "bench:baseline": "vitest bench --run --no-file-parallelism --outputJson test/benchmarks/baseline.json",
     "build": "tsdown --no-fixed-extension --tsconfig tsconfig.build.json",
-    "clean": "git rm -f pnpm-lock.yaml ; git clean -fdX",
+    "clean": "shx rm -f pnpm-lock.yaml && git clean -fdX -e !.claude/",
     "fix": "ksc fix",
     "lint": "ksc lint",
-    "release": "bumpp --commit 'Release: %s' && pnpm run build && NPM_AUTH_TOKEN=$(op read 'op://Personal/npm/token') && pnpm publish",
+    "release": "bumpp --commit 'Release: %s' && pnpm build && NPM_AUTH_TOKEN=$(op read 'op://Personal/npm/token') && pnpm publish",
     "test": "vitest run --no-file-parallelism"
   }
 }

package/readme.md

@@ -58,13 +58,13 @@ export default defineConfig({
 Assuming you have an executable with a `--help` flag on your path or in your project's scope:
 
 ```markdown
-<!-- cli-help({ cliCommand: "mdat", depth: 1 }) -->
+<!-- cli-help({ command: "mdat", depth: 1 }) -->
 ```
 
 Then run the `mdat` CLI command on your Markdown file to expand the rule and embed the tabular help output:
 
 ````markdown
-<!-- cli-help({ cliCommand: "mdat", depth: 1 }) -->
+<!-- cli-help({ command: "mdat", depth: 1 }) -->
 
 #### Command: `mdat`
 
@@ -105,12 +105,20 @@ mdat [command]
 <!-- /cli-help -->
 ````
 
+To generate help for a specific subcommand, pass `subcommand`. Whitespace-separated for nested paths:
+
+```markdown
+<!-- cli-help({ command: "mdat", subcommand: "readme", depth: 1 }) -->
+```
+
+This invokes `mdat readme --help`. Discovered sub-subcommands are appended to this path during recursion.
+
 The command is also aliased under the `<!-- cli -->` keyword.
 
 This would have equivalent output to the above:
 
 ```markdown
-<!-- cli({ cliCommand: "mdat", depth: 1 }) -->
+<!-- cli({ command: "mdat", depth: 1 }) -->
 ```
 
 If you embed the rule without any arguments, it will look for the binary file listed in the closest `package.json` file and run it with `--help`. This is what you want if you're documenting a package's CLI options in its readme.md file:
@@ -157,13 +165,17 @@ Currently, the parser implementation lives in this repository because I really o
 
 ## Maintainers
 
-[@kitschpatrol](https://github.com/kitschpatrol)
+[kitschpatrol](https://github.com/kitschpatrol)
 
 <!-- contributing -->
 
 ## Contributing
 
-[Issues](https://github.com/kitschpatrol/mdat-plugin-cli-help/issues) and pull requests are welcome.
+[Issues](https://github.com/kitschpatrol/mdat-plugin-cli-help/issues) are welcome and appreciated.
+
+Please open an issue to discuss changes before submitting a pull request. Unsolicited PRs (especially AI-generated ones) are unlikely to be merged.
+
+This repository uses [@kitschpatrol/shared-config](https://github.com/kitschpatrol/shared-config) (via its `ksc` CLI) for linting and formatting, plus [MDAT](https://github.com/kitschpatrol/mdat) for readme placeholder expansion.
 
 <!-- /contributing -->
 
@@ -171,6 +183,6 @@ Currently, the parser implementation lives in this repository because I really o
 
 ## License
 
-[MIT](license.txt) © Eric Mika
+[MIT](license.txt) © [Eric Mika](https://ericmika.com)
 
 <!-- /license -->