feat: polish release v2 experience (#6800)

scripts/check-openapi-schema.mts

@@ -1,11 +1,34 @@
 import assert from "node:assert/strict";
-import { readFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
 
 import { openApiDocument } from "../packages/api/src/open-api";
 
 const baseUrl = "http://localhost:3000";
-const generated = JSON.parse(JSON.stringify(openApiDocument(baseUrl))) as unknown;
-const checkedIn = JSON.parse(await readFile("apps/docs/static/api/open-api-schema.json", "utf8")) as unknown;
+const schemaPath = "apps/docs/static/api/open-api-schema.json";
+const writeMode = process.argv.slice(2).includes("--write");
+const serialized = `${JSON.stringify(openApiDocument(baseUrl), null, 2)}\n`;
+const generated = JSON.parse(serialized) as unknown;
+
+function assertOpenApiDocument(value: unknown): asserts value is { openapi: string; paths: Record<string, unknown> } {
+  assert.ok(typeof value === "object" && value !== null && !Array.isArray(value), "OpenAPI document must be an object");
+  assert.equal(typeof Reflect.get(value, "openapi"), "string", "OpenAPI document must declare its version");
+
+  const paths = Reflect.get(value, "paths");
+  assert.ok(
+    typeof paths === "object" && paths !== null && !Array.isArray(paths),
+    "OpenAPI document must contain paths",
+  );
+}
+
+assertOpenApiDocument(generated);
+
+if (writeMode) {
+  await writeFile(schemaPath, serialized, "utf8");
+  console.log(`OpenAPI schema updated (${Object.keys(generated.paths).length} paths)`);
+}
+
+const checkedIn = JSON.parse(await readFile(schemaPath, "utf8")) as unknown;
+assertOpenApiDocument(checkedIn);
 
 try {
   assert.deepStrictEqual(checkedIn, generated);
@@ -13,5 +36,8 @@ try {
   console.error(
     "The checked-in OpenAPI schema is stale. Regenerate it from openApiDocument and update apps/docs/static/api/open-api-schema.json.",
   );
-  process.exitCode = 1;
+  process.exit(1);
 }
+
+// The API import graph owns background handles that are irrelevant to this one-shot script.
+process.exit(0);