@writedocs/generator 0.4.0 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writedocs/generator",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Static site generator for docs — a writedocs.json + MDX folder in, a static site out.",
   "type": "module",
   "bin": {
@@ -45,7 +45,7 @@
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^12.1.0",
-    "@astrojs/markdown-remark": "7.2.2",
+    "@astrojs/markdown-remark": "7.2.4",
     "@astrojs/mdx": "^7.0.5",
     "@astrojs/react": "^6.0.2",
     "@astrojs/sitemap": "^3.7.3",
@@ -61,7 +61,7 @@
     "@iconify-json/tabler": "^1.2.35",
     "@shikijs/transformers": "^4.3.1",
     "@tailwindcss/vite": "^4.3.2",
-    "astro": "7.2.2",
+    "astro": "7.2.9",
     "astro-icon": "^1.1.5",
     "commander": "^15.0.0",
     "dotenv": "^17.4.2",

package/src/cli/build-auth.js

@@ -1,53 +1,69 @@
-/**
- * `writedocs build` produces the artifact that actually gets deployed, so
- * unlike `dev`/`init` it isn't freely runnable by anyone who installs the
- * package - it's gated behind a key that a separate service (`key-server/`
- * in this repo) actually decides the validity of.
- *
- * This deliberately isn't a local check. An earlier version compared the
- * supplied key against an env var set on the same machine
- * (WRITEDOCS_BUILD_SECRET) - but since writedocs ships its full source to
- * everyone who installs it, anyone could read that check and satisfy it
- * with a value they made up themselves. Calling out to a server that
- * actually holds the set of issued keys means a key's validity is decided
- * by whoever runs that server, not by whoever is running `build`.
- *
- * See docs/dev/docs/deploy.mdx for how to deploy key-server/ and issue
- * keys, and key-server/README.md for the service's own endpoints.
- */
-export async function requireBuildKey(providedKey) {
-  const serverUrl = process.env.WRITEDOCS_KEY_SERVER_URL;
-  if (!serverUrl) {
-    console.error('[writedocs] build is not available.');
-    process.exit(1);
-  }
-  if (!providedKey) {
-    console.error('[writedocs] build requires a valid --key (or WRITEDOCS_API_KEY).');
-    process.exit(1);
-  }
-
-  let valid = false;
-  try {
-    const res = await fetch(new URL('/v1/validate', serverUrl), {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ key: providedKey }),
-      signal: AbortSignal.timeout(10_000),
-    });
-    if (res.ok) {
-      const body = await res.json();
-      valid = body?.valid === true;
-    }
-  } catch (err) {
-    // Fails closed on a network error/timeout too, same as an explicit
-    // rejection - an unreachable authorization server is not treated as
-    // "no opinion, let it through".
-    console.error(`[writedocs] Could not reach the build authorization server: ${err.message}`);
-    process.exit(1);
-  }
-
-  if (!valid) {
-    console.error('[writedocs] build requires a valid --key (or WRITEDOCS_API_KEY) - the server rejected this one.');
-    process.exit(1);
-  }
-}
+/**
+ * `writedocs build` produces the artifact that actually gets deployed, so
+ * unlike `dev`/`init` it isn't freely runnable by anyone who installs the
+ * package - it's gated behind a key that a separate service (`key-server/`
+ * in this repo) actually decides the validity of.
+ *
+ * This deliberately isn't a local check. An earlier version compared the
+ * supplied key against an env var set on the same machine
+ * (WRITEDOCS_BUILD_SECRET) - but since writedocs ships its full source to
+ * everyone who installs it, anyone could read that check and satisfy it
+ * with a value they made up themselves. Calling out to a server that
+ * actually holds the set of issued keys means a key's validity is decided
+ * by whoever runs that server, not by whoever is running `build`.
+ *
+ * See docs/dev/docs/deploy.mdx for how to deploy key-server/ and issue
+ * keys, and key-server/README.md for the service's own endpoints.
+ */
+export const EX_TEMPFAIL = 75;
+
+export async function requireBuildKey(providedKey) {
+  const serverUrl = process.env.WRITEDOCS_KEY_SERVER_URL;
+  if (!serverUrl) {
+    console.error('[writedocs] build is not available.');
+    process.exit(1);
+  }
+  if (!providedKey) {
+    console.error('[writedocs] build requires a valid --key (or WRITEDOCS_API_KEY).');
+    process.exit(1);
+  }
+
+  // The exit code is a contract with whoever runs `build` - the WriteDocs
+  // platform retries on it, never on the message text:
+  //   1  - the key was not accepted: missing URL/key, a 4xx, `valid: false`.
+  //        Trying again with the same key gives the same answer.
+  //   75 - EX_TEMPFAIL (sysexits.h): the authorization server couldn't be
+  //        asked - network error, timeout or 5xx. Still fails closed (no build
+  //        happens); it only tells the caller that trying later may work.
+  let res;
+  try {
+    res = await fetch(new URL('/v1/validate', serverUrl), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ key: providedKey }),
+      signal: AbortSignal.timeout(10_000),
+    });
+  } catch (err) {
+    // Fails closed on a network error/timeout too, same as an explicit
+    // rejection - an unreachable authorization server is not treated as
+    // "no opinion, let it through".
+    console.error(`[writedocs] Could not reach the build authorization server: ${err.message}`);
+    process.exit(EX_TEMPFAIL);
+  }
+
+  if (res.status >= 500) {
+    console.error(`[writedocs] The build authorization server failed (HTTP ${res.status}) - try again later.`);
+    process.exit(EX_TEMPFAIL);
+  }
+
+  let valid = false;
+  if (res.ok) {
+    const body = await res.json().catch(() => null);
+    valid = body?.valid === true;
+  }
+
+  if (!valid) {
+    console.error('[writedocs] build requires a valid --key (or WRITEDOCS_API_KEY) - the server rejected this one.');
+    process.exit(1);
+  }
+}