diff --git a/docs/1.guide/1.index.md b/docs/1.guide/1.index.md index 01fab63..2577cac 100644 --- a/docs/1.guide/1.index.md +++ b/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. + + + +```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 +``` + + diff --git a/docs/2.generators/cli-output.md b/docs/2.generators/cli-output.md new file mode 100644 index 0000000..308a293 --- /dev/null +++ b/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 + + + +### Input + + + + +### Output + + + + ```sh + + ``` + + + + + +## 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"`. +:: diff --git a/package.json b/package.json index 51e4067..7eabf4f 100644 --- a/package.json +++ b/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" }, diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 8fe4b99..52dfc22 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -53,6 +53,9 @@ importers: scule: specifier: ^1.3.0 version: 1.3.0 + tinyexec: + specifier: ^1.0.1 + version: 1.0.1 tinyglobby: specifier: ^0.2.15 version: 0.2.15 diff --git a/src/cli.ts b/src/cli.ts index 69e3762..f0bd63a 100644 --- a/src/cli.ts +++ b/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", diff --git a/src/generators/cli-output.ts b/src/generators/cli-output.ts new file mode 100644 index 0000000..a66feb1 --- /dev/null +++ b/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_}`); + } + }, +}); diff --git a/src/generators/index.ts b/src/generators/index.ts index 1c7f6a7..3b6c99f 100644 --- a/src/generators/index.ts +++ b/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; diff --git a/test/fixture/INPUT.md b/test/fixture/INPUT.md index 615003d..083f875 100644 --- a/test/fixture/INPUT.md +++ b/test/fixture/INPUT.md @@ -47,3 +47,8 @@ + +## `cli-output` + + + diff --git a/test/fixture/OUTPUT.md b/test/fixture/OUTPUT.md index a80411d..7b0c32e 100644 --- a/test/fixture/OUTPUT.md +++ b/test/fixture/OUTPUT.md @@ -224,3 +224,58 @@ Made by [@pi0](https://github.com/pi0) and [community](https://github.com/unjs/a + +## `cli-output` + + + +```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 + + 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 to listen on (default: 3000) + --host Host to bind to (default: all interfaces) + -s, --static Serve static files from the specified directory (default: public) + --prod Run in production mode (no watch, no debug) + --import ES module to preload + --tls Enable TLS (HTTPS/HTTP2) + --cert TLS certificate file + --key 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) +``` + +