mdat-plugin-cli-help 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/dist/index.d.ts +13 -0
  2. package/dist/index.js +15397 -0
  3. package/license.txt +21 -0
  4. package/package.json +72 -0
  5. package/readme.md +149 -0
package/license.txt ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Eric Mika
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/package.json ADDED
@@ -0,0 +1,72 @@
1
+ {
2
+ "name": "mdat-plugin-cli-help",
3
+ "version": "1.0.0",
4
+ "description": "Mdat plugin to generate tabular CLI tool documentation in Markdown files.",
5
+ "keywords": [
6
+ "markdown",
7
+ "mdat-plugin",
8
+ "mdat",
9
+ "cli",
10
+ "npm-package"
11
+ ],
12
+ "homepage": "https://github.com/kitschpatrol/mdat-plugin-cli-help",
13
+ "bugs": "https://github.com/kitschpatrol/mdat-plugin-cli-help/issues",
14
+ "repository": {
15
+ "type": "git",
16
+ "url": "git+https://github.com/kitschpatrol/mdat-plugin-cli-help.git"
17
+ },
18
+ "license": "MIT",
19
+ "author": {
20
+ "name": "Eric Mika",
21
+ "email": "eric@ericmika.com",
22
+ "url": "https://ericmika.com"
23
+ },
24
+ "type": "module",
25
+ "exports": {
26
+ ".": {
27
+ "types": "./dist/index.d.ts",
28
+ "import": "./dist/index.js"
29
+ }
30
+ },
31
+ "main": "./dist/index.js",
32
+ "module": "./dist/index.js",
33
+ "files": [
34
+ "dist/*"
35
+ ],
36
+ "dependencies": {
37
+ "@types/which": "^3.0.4",
38
+ "execa": "^9.6.0",
39
+ "read-pkg": "^9.0.1",
40
+ "type-fest": "^5.2.0",
41
+ "which": "^5.0.0"
42
+ },
43
+ "devDependencies": {
44
+ "@kitschpatrol/shared-config": "^5.7.4",
45
+ "@types/node": "^20.19.24",
46
+ "bumpp": "^10.3.1",
47
+ "chevrotain": "^11.0.3",
48
+ "meow": "^14.0.0",
49
+ "tsdown": "^0.15.12",
50
+ "typescript": "~5.9.3",
51
+ "vitest": "^4.0.6",
52
+ "zod": "^3.25.76"
53
+ },
54
+ "peerDependencies": {
55
+ "mdat": "^1.1.0",
56
+ "remark-mdat": "^1.1.0"
57
+ },
58
+ "engines": {
59
+ "node": ">=20.19.0"
60
+ },
61
+ "publishConfig": {
62
+ "access": "public"
63
+ },
64
+ "scripts": {
65
+ "build": "tsdown --tsconfig tsconfig.build.json",
66
+ "clean": "git rm -f pnpm-lock.yaml ; git clean -fdX",
67
+ "fix": "ksc fix",
68
+ "lint": "ksc lint",
69
+ "release": "bumpp --commit 'Release: %s' && pnpm run build && NPM_AUTH_TOKEN=$(op read 'op://Personal/npm/token') && pnpm publish",
70
+ "test": "vitest --no-file-parallelism"
71
+ }
72
+ }
package/readme.md ADDED
@@ -0,0 +1,149 @@
1
+ <!--+ Warning: Content inside HTML comment blocks was generated by mdat and may be overwritten. +-->
2
+
3
+ <!-- title -->
4
+
5
+ # mdat-plugin-cli-help
6
+
7
+ <!-- /title -->
8
+
9
+ <!-- badges -->
10
+
11
+ [![NPM Package mdat-plugin-cli-help](https://img.shields.io/npm/v/mdat-plugin-cli-help.svg)](https://npmjs.com/package/mdat-plugin-cli-help)
12
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
13
+
14
+ <!-- /badges -->
15
+
16
+ <!-- short-description -->
17
+
18
+ **Mdat plugin to generate tabular CLI tool documentation in Markdown files.**
19
+
20
+ <!-- /short-description -->
21
+
22
+ ## Overview
23
+
24
+ _**This is a plugin for the [mdat CLI tool](https://github.com/kitschpatrol/mdat), which is a simple Markdown templating system optimized for embedding dynamic content in repository readmes and the like.**_
25
+
26
+ This plugin automatically transforms a CLI command's `--help` output into nicely formatted Markdown tables.
27
+
28
+ The rule also recursively calls `--help` on any subcommands found for inclusion in the output.
29
+
30
+ Currently, the rule can only parse help output in the format provided by [Yargs](https://yargs.js.org)- and [Meow](https://github.com/sindresorhus/meow)-based tools. If parsing fails, the rule will fall back to show the raw help output in a regular code block instead.
31
+
32
+ ## Getting started
33
+
34
+ ### Dependencies
35
+
36
+ We'll assume you have [mdat](https://github.com/kitschpatrol/mdat) installed either globally or in your local project.
37
+
38
+ ### Installation
39
+
40
+ Install the plugin as a development dependency:
41
+
42
+ ```bash
43
+ pnpm add -D mdat-plugin-cli-help
44
+ ```
45
+
46
+ Register the plugin in your mdat config file, e.g. `mdat.config.ts`:
47
+
48
+ ```ts
49
+ import type { Config } from 'mdat'
50
+ import cliHelp from 'mdat-plugin-cli-help'
51
+
52
+ export default {
53
+ rules: {
54
+ ...cliHelp,
55
+ },
56
+ } satisfies Config
57
+ ```
58
+
59
+ ## Usage
60
+
61
+ Assuming you have an executable with a `--help` flag on your path or in your project's scope:
62
+
63
+ ```markdown
64
+ <!-- cli-help { cliCommand: "mdat", depth: 1 } -->
65
+ ```
66
+
67
+ Then run the `mdat` CLI command on your Markdown file to expand the rule and embed the tabular help output:
68
+
69
+ ````markdown
70
+ <!-- cli-help { cliCommand: "mdat", depth: 1 } -->
71
+
72
+ #### Command: `mdat`
73
+
74
+ Work with MDAT placeholder comments in any Markdown file.
75
+
76
+ If no command is provided, `mdat expand` is run by default.
77
+
78
+ Usage:
79
+
80
+ ```txt
81
+ mdat [command]
82
+ ```
83
+
84
+ | Positional Argument | Description | Type |
85
+ | ------------------- | ------------------------------------------------ | -------- |
86
+ | `files` | Markdown file(s) with MDAT placeholder comments. | `string` |
87
+
88
+ | Command | Argument | Description |
89
+ | ---------- | ----------------------- | -------------------------------------------------------------- |
90
+ | `expand` | `<files..>` `[options]` | Expand MDAT placeholder comments. _(Default command.)_ |
91
+ | `check` | `<files..>` `[options]` | Validate a Markdown file containing MDAT placeholder comments. |
92
+ | `collapse` | `<files..>` `[options]` | Collapse MDAT placeholder comments. |
93
+ | `readme` | `[command]` | Work with MDAT comments in your readme.md. |
94
+
95
+ | Option | Description | Type | Default |
96
+ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
97
+ | `--config` | Path(s) to files containing MDAT configuration. | `array` | Configuration is loaded if found from the usual places, or defaults are used. |
98
+ | `--rules`<br>`-r` | Path(s) to files containing MDAT comment expansion rules. | `array` | |
99
+ | `--output`<br>`-o` | Output file directory. | `string` | Same directory as input file. |
100
+ | `--name`<br>`-n` | Output file name. | `string` | Same name as input file. Overwrites the input file. |
101
+ | `--meta`<br>`-m` | Embed an extra comment at the top of the generated Markdown warning editors that certain sections of the document have been generated dynamically. | `boolean` | |
102
+ | `--prefix` | Require a string prefix before all comments to be considered for expansion. Useful if you have a bunch of non-MDAT comments in your Markdown file, or if you're willing to trade some verbosity for safety. | `string` | |
103
+ | `--print` | Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options. | `boolean` | |
104
+ | `--verbose` | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
105
+ | `--help`<br>`-h` | Show help | `boolean` | |
106
+ | `--version`<br>`-v` | Show version number | `boolean` | |
107
+
108
+ <!-- /cli-help -->
109
+ ````
110
+
111
+ The command is also aliased under the `<!-- cli -->` keyword.
112
+
113
+ This would have equivalent output to the above:
114
+
115
+ ```markdown
116
+ <!-- cli { cliCommand: "mdat", depth: 1 } -->
117
+ ```
118
+
119
+ 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:
120
+
121
+ ```markdown
122
+ <!-- cli-help -->
123
+ ```
124
+
125
+ ## Development notes
126
+
127
+ Parsing arbitrary `--help` output is a bit tricky. The [jc](https://github.com/kellyjonbrazil/jc) project is a heroic collection of output parsers, but does not currently implement help output parsing. It might be interesting to try to contribute mdat's help parsing implementations to jc.
128
+
129
+ Currently, the parser implementation lives in this repository because I really only use it in the context of my CLI tool readme files. In theory, it really belongs in a separate package.
130
+
131
+ ## Maintainers
132
+
133
+ [@kitschpatrol](https://github.com/kitschpatrol)
134
+
135
+ <!-- contributing -->
136
+
137
+ ## Contributing
138
+
139
+ [Issues](https://github.com/kitschpatrol/mdat-plugin-cli-help/issues) and pull requests are welcome.
140
+
141
+ <!-- /contributing -->
142
+
143
+ <!-- license -->
144
+
145
+ ## License
146
+
147
+ [MIT](license.txt) © Eric Mika
148
+
149
+ <!-- /license -->