Use website scripts as the source of truth

Generate embedded examples and manual script pages from the website
checkout. Drop local copies and skip examples without the checkout.

prompt: Use website scripts as source of truth and update agents.md

Author: kjk

agents.md

@@ -360,6 +360,8 @@ To add a new cmd-line flag:
 
 User docs live in the sumatra-website repo, in `../hack/webapps/sumatra-website/www/docs` (called `www/docs` below); it is the source of truth. `bun cmd/gen-docs.ts` copies the pages reachable from `SumatraPDF-documentation.md` into `.work/docs` for the in-app manual; without a website checkout (CI) it skips and the exe ships without the manual. `cmd/gen-settings.ts` and `cmd/gen-js-reference-md.ts` write their generated pages there. Commit doc changes in the website repo.
 
+PDF example scripts live only in `sumatra-website/www/docs/scripts`. Edit and commit them in the website repo; do not keep copies in `docs/scripts` here. `cmd/gen-pdf-scripts.ts` bundles them into `.work/scripts.js` for embedding, and `cmd/gen-docs.ts` stages the scripts listed in `Tool-run-javascript-examples.md` into `.work/docs/scripts`. Without the website checkout, builds omit both the manual and example scripts.
+
 When writing or restructuring a feature page in `www/docs`, follow `docs/writing-docs.md`.
 
 ## Version history (www/docs/Version-history.md)

cmd/gen-docs.ts

@@ -158,7 +158,7 @@ function copyScriptExamples(outDir: string, pages: string[]): void {
       throw new Error(`${kScriptExamplesPage}: duplicate script ${name}`);
     }
     names.add(name);
-    copyFileNormalized(join(outDir, "scripts", name), join(docsDir, "scripts", name));
+    copyFileNormalized(join(outDir, "scripts", name), join(scriptsDir, name));
   }
   for (const file of readdirSync(scriptsDir, { withFileTypes: true })) {
     if (file.isFile() && file.name.endsWith(".js") && !names.has(file.name)) {

cmd/gen-pdf-scripts.ts

@@ -1,12 +1,19 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { websiteDocsDir } from "./util";
 
 const root = resolve(import.meta.dir, "..");
 const kDefaultScript = "load-a-pdf.js";
 const kScriptSeparator = "// ---";
 
-export function genPDFScripts(inputRoot = root): string {
-  const scriptsDir = join(inputRoot, "docs/scripts");
+export function genPDFScripts(inputRoot = root): string | null {
+  const scriptsDir = join(inputRoot, relative(root, websiteDocsDir), "scripts");
+  const output = join(inputRoot, ".work/scripts.js");
+  if (!existsSync(scriptsDir)) {
+    rmSync(output, { force: true });
+    console.log(`gen-pdf-scripts: skipping, '${scriptsDir}' missing (needs sumatra-website checkout)`);
+    return null;
+  }
   const names = readdirSync(scriptsDir, { withFileTypes: true })
     .filter((file) => file.isFile() && file.name.endsWith(".js"))
     .map((file) => file.name)
@@ -21,12 +28,12 @@ export function genPDFScripts(inputRoot = root): string {
   });
   if (!scripts.length) throw new Error("No PDF scripts found");
   const bundle = scripts.join(`\n${kScriptSeparator}\n`) + "\n";
-  const output = join(inputRoot, ".work/scripts.js");
   mkdirSync(join(inputRoot, ".work"), { recursive: true });
   if (!existsSync(output) || readFileSync(output, "utf8") !== bundle) writeFileSync(output, bundle);
   return output;
 }
 
 if (import.meta.main) {
-  console.log(genPDFScripts());
+  const output = genPDFScripts();
+  if (output) console.log(output);
 }

cmd/helper/embedded.ts

@@ -76,7 +76,8 @@ export async function packEmbedded(
   const staging = join(dir, "embedded");
   const archive = join(dir, "embedded.lzsa");
   const inputs = new Map<string, string>();
-  inputs.set("scripts.js", genPDFScripts(inputRoot));
+  const scripts = genPDFScripts(inputRoot);
+  if (scripts) inputs.set("scripts.js", scripts);
   const docs = join(inputRoot, ".work/docs");
   if (opts.manual) {
     for (const src of filesUnder(docs)) inputs.set(relative(docs, src), src);

cmd/pack-embedded-prebuild.cmd

@@ -73,7 +73,11 @@ if exist "%WORK%\docs\" (
 )
 if not exist "%STAGING%\" mkdir "%STAGING%"
 copy /y "%WORK%\translations.txt" "%STAGING%\translations.txt" >nul || exit /b 1
-copy /y "%WORK%\scripts.js" "%STAGING%\scripts.js" >nul || exit /b 1
+if exist "%WORK%\scripts.js" (
+  copy /y "%WORK%\scripts.js" "%STAGING%\scripts.js" >nul || exit /b 1
+) else (
+  if exist "%STAGING%\scripts.js" del /q "%STAGING%\scripts.js"
+)
 copy /y "%ROOT%\ext\marked.min.js" "%STAGING%\marked.min.js" >nul || exit /b 1
 copy /y "%ROOT%\ext\mermaid.min.js" "%STAGING%\mermaid.min.js" >nul || exit /b 1