feat(cli): add ability to read/write stdin/stdout

Author: freakyfelt

README.md

@@ -309,6 +309,31 @@ operations:
         404: { $ref: '#/components/schemas/NotFound' }
 ```
 
+## Generating the resulting OpenAPI specification
+
+The CLI includes a `yarpc-cli` that can be used to generate the resulting OpenAPI 3.1 specification. This works by transforming your queries and mutations and then merging them with any paths that may have been specified in the input YARPC specification.
+
+```sh
+npx @freakyfelt/yarpc-cli --input yarpc.json --output openapi.json
+```
+
+### Emitting YAML
+
+By default the CLI will emit JSON, but `--format yaml` can be used to emit YAML instead
+
+```
+npx @freakyfelt/yarpc-cli --input yarpc.json --output openapi.yaml --format yaml
+```
+
+### Using stdin and stdout
+
+The CLI can also read from `stdin` and write to `stdout` by using `-` instead of a file name
+
+```sh
+# read the YARPC spec from stdin and write the OpenAPI spec to stdout
+cat yarpc.json | npx @freakyfelt/yarpc-cli --input - --output - | ./build-tool.sh
+```
+
 ## Customizations
 
 The goal of the builder is to be a lightweight abstraction on top of OpenAPI, injecting in defaults where it doesn't really matter for services vending an SDK. That being said, the builder does allow you to provide any OpenAPI 3.1 operation definitions you want.

packages/cli/examples/widgets.oas.json

@@ -125,7 +125,10 @@
                     "$ref": "#/components/schemas/WidgetStatus"
                   }
                 },
-                "required": ["name", "status"]
+                "required": [
+                  "name",
+                  "status"
+                ]
               }
             }
           }
@@ -168,7 +171,9 @@
                     "$ref": "#/components/schemas/WidgetID"
                   }
                 },
-                "required": ["id"]
+                "required": [
+                  "id"
+                ]
               }
             }
           }
@@ -274,7 +279,10 @@
             "type": "object"
           }
         },
-        "required": ["code", "message"]
+        "required": [
+          "code",
+          "message"
+        ]
       },
       "WidgetID": {
         "type": "string",
@@ -283,7 +291,10 @@
       "WidgetStatus": {
         "description": "The status of a widget",
         "type": "string",
-        "enum": ["active", "inactive"]
+        "enum": [
+          "active",
+          "inactive"
+        ]
       },
       "Widget": {
         "type": "object",
@@ -307,7 +318,13 @@
             "description": "The date and time the widget was last updated"
           }
         },
-        "required": ["id", "name", "status", "createdAt", "updatedAt"]
+        "required": [
+          "id",
+          "name",
+          "status",
+          "createdAt",
+          "updatedAt"
+        ]
       },
       "GetWidgetInput": {
         "type": "object",
@@ -316,7 +333,9 @@
             "$ref": "#/components/schemas/WidgetID"
           }
         },
-        "required": ["id"]
+        "required": [
+          "id"
+        ]
       },
       "ListWidgetsInput": {
         "type": "object",
@@ -355,7 +374,9 @@
             }
           }
         },
-        "required": ["items"]
+        "required": [
+          "items"
+        ]
       },
       "CreateWidgetInput": {
         "type": "object",
@@ -368,7 +389,10 @@
             "$ref": "#/components/schemas/WidgetStatus"
           }
         },
-        "required": ["name", "status"]
+        "required": [
+          "name",
+          "status"
+        ]
       },
       "DeactivateWidgetInput": {
         "type": "object",
@@ -377,7 +401,9 @@
             "$ref": "#/components/schemas/WidgetID"
           }
         },
-        "required": ["id"]
+        "required": [
+          "id"
+        ]
       }
     }
   }

packages/cli/examples/widgets.oas.yaml

@@ -263,3 +263,4 @@ components:
           $ref: "#/components/schemas/WidgetID"
       required:
         - id
+

packages/cli/src/cli.ts

@@ -1,4 +1,5 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
 import { parseArgs } from "node:util";
 import pino from "pino";
 import YAML from "yaml";
@@ -14,8 +15,8 @@ function showHelp() {
 Usage: yarpc-cli [options]
 
 Options:
-  -i, --input  [string]     Input RPC file path
-  -o, --output [string]     Output OpenAPI file path (default: openapi.json)
+  -i, --input  [string]     Input RPC file path or "-" for stdin
+  -o, --output [string]     Output OpenAPI file path or "-" for stdout (default: openapi.json)
   -f, --format [yaml|json]  Output format (default: json)
 
   -h, --help     Show help and exit
@@ -34,20 +35,29 @@ type EmitOpenAPIParams = {
 async function emitOpenAPI(params: EmitOpenAPIParams) {
 	const { input, output, format, logger } = params;
 
-	const source = YAML.parse(await readFile(input, "utf8")) as RPCDocument;
+	const text =
+		input === "-"
+			? readFileSync(process.stdin.fd, "utf8")
+			: readFileSync(input, "utf8");
+	const source = YAML.parse(text.toString()) as RPCDocument;
 
 	const transformed = await DocumentTransformer.transform(source, { logger });
 	let contents;
 
 	if (format === "yaml") {
-		contents = YAML.stringify(transformed, { aliasDuplicateObjects: false });
+		contents =
+			YAML.stringify(transformed, { aliasDuplicateObjects: false }) + "\n";
 	} else if (format === "json") {
-		contents = JSON.stringify(transformed, null, 2);
+		contents = JSON.stringify(transformed, null, 2) + "\n";
 	} else {
 		throw new Error(`Unsupported format: ${String(format)}`);
 	}
 
-	await writeFile(output, contents, "utf8");
+	if (output === "-") {
+		process.stdout.write(contents);
+	} else {
+		await writeFile(output, contents, "utf8");
+	}
 }
 
 export async function main() {
@@ -66,6 +76,9 @@ export async function main() {
 		level: args.values.verbose ? "debug" : "info",
 		transport: {
 			target: "pino-pretty",
+			options: {
+				destination: process.stderr.fd,
+			},
 		},
 	});