feat(generators): add cli-output

docs/1.guide/1.index.md

@@ -25,3 +25,20 @@ npx automd@latest
 By default, the `README.md` file in the current working directory will be used as the target.
 
 You can use `--dir` and `--input` arguments to customize the default behavior to operate on any other markdown file.
+
+<!-- automd:cli-output usage -->
+
+```sh
+[log] Your automated markdown maintainer! (automd v0.4.0)
+
+USAGE `automd [OPTIONS] `
+
+OPTIONS
+
+                `--dir`    current working directory                             
+  `--input="README.md"`    name or path the markdown input to update             
+             `--output`    name or path the markdown output (defaults to input)  
+              `--watch`    watch for changes in input files and regenerate output
+```
+
+<!-- /automd -->

docs/2.generators/cli-output.md

@@ -0,0 +1,42 @@
+# cli-output
+
+The `cli-output` generator run a CLI command with `npx` inlines the output as Markdown code block.
+
+Use `command` argument to specify the command to run, by default it will use the `name` field in `package.json`.
+
+## Example
+
+<!-- automd:example generator=cli-output command="automd" args="--help" -->
+
+### Input
+
+    <!-- automd:cli-output command="automd" args="--help" -->
+    <!-- /automd -->
+
+### Output
+
+    <!-- automd:cli-output command="automd" args="--help" -->
+
+    ```sh
+
+    ```
+
+    <!-- /automd -->
+
+<!-- /automd -->
+
+## Arguments
+
+::field-group
+
+::field{name="command" type="string"}
+The command to run with `npx` (by default it will use the `name` field in `package.json`).
+::
+
+::field{name="args" type="string"}
+The arguments to pass to the command. (defaults to `""`).
+::
+
+::field{name="usage" type="boolean"}
+Show usage information. (defaults to `false`), shortcut for `args="--help"`.
+::

package.json

@@ -45,6 +45,7 @@
     "perfect-debounce": "^2.0.0",
     "pkg-types": "^2.3.0",
     "scule": "^1.3.0",
+    "tinyexec": "^1.0.1",
     "tinyglobby": "^0.2.15",
     "untyped": "^2.0.0"
   },

src/cli.ts

@@ -18,6 +18,7 @@ const main = defineCommand({
     dir: {
       description: "current working directory",
       type: "string",
+      default: ".",
     },
     input: {
       description: "name or path the markdown input to update",

src/generators/cli-output.ts

@@ -0,0 +1,34 @@
+import * as md from "mdbox";
+import { defineGenerator } from "../generator";
+import { getPkg } from "../_utils";
+import { x } from "tinyexec";
+
+export const cliOutput = defineGenerator({
+  name: "cli-output",
+  async generate({ config, args }) {
+    const pkg = await getPkg(config.dir, args);
+    const command: string = args.command || pkg.name;
+    const argsArray = args.args?.split(" ") || [];
+
+    if (args.usage) {
+      argsArray.push("--help");
+    }
+
+    try {
+      const result = await x("npx", [command, ...argsArray], {
+        nodeOptions: {
+          env: {
+            NO_COLOR: "1",
+          },
+        },
+      });
+      const stdout = result.stdout.trim();
+
+      return {
+        contents: md.codeBlock(stdout, "sh"),
+      };
+    } catch (error_) {
+      throw new Error(`[cli-usage] Could not execute ${command}: ${error_}`);
+    }
+  },
+});

src/generators/index.ts

@@ -7,6 +7,7 @@ import { jsimport } from "./jsimport";
 import { withAutomd } from "./with-automd";
 import { file } from "./file";
 import { contributors } from "./contributors";
+import { cliOutput } from "./cli-output";
 
 export default {
   jsdocs,
@@ -19,4 +20,5 @@ export default {
   jsimport,
   "with-automd": withAutomd,
   contributors,
+  "cli-output": cliOutput,
 } as Record<string, Generator>;

test/fixture/INPUT.md

@@ -47,3 +47,8 @@
 
 <!-- automd:contributors author=pi0 license=MIT provider=markupgo  -->
 <!-- /automd -->
+
+## `cli-output`
+
+<!-- automd:cli-output command="srvx" usage -->
+<!-- /automd -->

test/fixture/OUTPUT.md

@@ -224,3 +224,58 @@ Made by [@pi0](https://github.com/pi0) and [community](https://github.com/unjs/a
 </a>
 
 <!-- /automd -->
+
+## `cli-output`
+
+<!-- automd:cli-output command="srvx" usage -->
+
+```sh
+srvx - Start an HTTP server with the specified entry path.
+
+USAGE
+
+// server.ts
+export default {
+  fetch(req: Request) {
+    return new Response("Hello, World!");
+  }
+}
+
+# srvx [options] [entry]
+$ srvx ./server.ts            # Start development server
+$ srvx --prod                 # Start production  server
+$ srvx --port=8080            # Listen on port 8080
+$ srvx --host=localhost       # Bind to localhost only
+$ srvx --import=jiti/register # Enable [jiti](https://github.com/unjs/jiti) loader
+$ srvx --tls --cert=cert.pem --key=key.pem  # Enable TLS (HTTPS/HTTP2)
+
+
+ARGUMENTS
+
+  <entry>                  Server entry path to serve.
+                           Default: server, index, src/server, src/index, server/index (.mts,.ts,.cts,.js,.mjs,.cjs,.jsx,.tsx)
+
+OPTIONS
+
+  -p, --port <port>        Port to listen on (default: 3000)
+  --host <host>            Host to bind to (default: all interfaces)
+  -s, --static <dir>       Serve static files from the specified directory (default: public)
+  --prod                   Run in production mode (no watch, no debug)
+  --import <loader>        ES module to preload
+  --tls                    Enable TLS (HTTPS/HTTP2)
+  --cert <file>            TLS certificate file
+  --key  <file>            TLS private key file
+  -h, --help               Show this help message
+  -v, --version            Show server and runtime versions
+
+ENVIRONMENT
+
+  PORT                     Override port
+  HOST                     Override host
+  NODE_ENV                 Set to production for production mode.
+
+➤ [Documentation](https://srvx.h3.dev)
+➤ [Report issues](https://github.com/h3js/srvx/issues)
+```
+
+<!-- /automd -->