@writedocs/generator 0.4.1 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writedocs/generator",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Static site generator for docs — a writedocs.json + MDX folder in, a static site out.",
   "type": "module",
   "bin": {
@@ -84,4 +84,4 @@
   "devDependencies": {
     "esbuild": "0.28.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);
+  }
+}

package/src/layout/components/AskAiWidget.astro

@@ -25,11 +25,17 @@ interface Props {
 const { config } = Astro.props as Props;
 
 const askAiLoaderScript = `window.DocsBotAI=window.DocsBotAI||{},DocsBotAI.init=function(e){return new Promise((t,r)=>{var n=document.createElement("script");n.type="text/javascript",n.async=!0,n.src="https://widget.docsbot.ai/chat.js";let o=document.getElementsByTagName("script")[0];o.parentNode.insertBefore(n,o),n.addEventListener("load",()=>{let n;Promise.all([new Promise((t,r)=>{window.DocsBotAI.mount(Object.assign({}, e)).then(t).catch(r)}),(n=function e(t){return new Promise(e=>{if(document.querySelector(t))return e(document.querySelector(t));let r=new MutationObserver(n=>{if(document.querySelector(t))return e(document.querySelector(t)),r.disconnect()});r.observe(document.body,{childList:!0,subtree:!0})})})("#docsbotai-root"),]).then(()=>t()).catch(r)}),n.addEventListener("error",e=>{r(e.message)})})};`;
-const askAiInitScript = config.integrations.askAi
-  ? `DocsBotAI.init(${JSON.stringify({ id: config.integrations.askAi.id })});`
+// WRITEDOCS_ASK_AI_ID tem precedência sobre o writedocs.json, pelo mesmo
+// motivo do WRITEDOCS_DISABLE_WATERMARK em Sidebar.astro: quem roda o build
+// (CI, env da hospedagem) define o bot sem mexer no conteúdo versionado.
+// Não é segredo - o id sai em texto puro no HTML de toda página. String
+// vazia conta como não definida e cai no valor do JSON.
+const askAiId = process.env.WRITEDOCS_ASK_AI_ID || config.integrations.askAi?.id;
+const askAiInitScript = askAiId
+  ? `DocsBotAI.init(${JSON.stringify({ id: askAiId })});`
   : null;
 ---
-{config.integrations.askAi && (
+{askAiId && (
   <>
     <script is:inline set:html={askAiLoaderScript} />
     {askAiInitScript && <script is:inline set:html={askAiInitScript} />}