Improve pre/post render script logging and add output control env vars (#12444)

Add `Running script` prefix to script execution logging for clearer output.

Pass two new environment variables to pre/post render scripts so they can
adapt their output:
- QUARTO_PROJECT_SCRIPT_PROGRESS: "1" when progress can be shown, "0" otherwise
- QUARTO_PROJECT_SCRIPT_QUIET: "1" when --quiet is active, "0" otherwise

Consolidate handler/non-handler code paths in runScripts using a default
handler with nullish coalescing, and move environment initialization before
the loop.

Author: cderv

llm-docs/testing-patterns.md

@@ -88,6 +88,62 @@ testQuartoCmd(
 - Use absolute paths with `join()` for file verification
 - Clean up output directories in teardown
 
+### Pre/Post Render Script Tests
+
+For testing pre-render or post-render scripts that run during project rendering:
+
+```typescript
+import { docs } from "../../utils.ts";
+import { join } from "../../../src/deno_ral/path.ts";
+import { existsSync } from "../../../src/deno_ral/fs.ts";
+import { testQuartoCmd } from "../../test.ts";
+import { noErrors, validJsonWithFields } from "../../verify.ts";
+import { safeRemoveIfExists } from "../../../src/core/path.ts";
+
+const projectDir = docs("project/prepost/my-test");
+const projectDirAbs = join(Deno.cwd(), projectDir);
+const dumpPath = join(projectDirAbs, "output.json");
+const outDir = join(projectDirAbs, "_site");
+
+testQuartoCmd(
+  "render",
+  [projectDir],
+  [
+    noErrors,
+    validJsonWithFields(dumpPath, {
+      expected: "value",
+    }),
+  ],
+  {
+    teardown: async () => {
+      safeRemoveIfExists(dumpPath);
+      if (existsSync(outDir)) {
+        await Deno.remove(outDir, { recursive: true });
+      }
+    },
+  },
+);
+```
+
+**Fixture structure:**
+
+```
+tests/docs/project/prepost/my-test/
+├── _quarto.yml       # project config with pre-render/post-render scripts
+├── index.qmd         # minimal page (website needs at least one)
+├── check-env.ts      # pre/post-render script (Deno TypeScript)
+└── .gitignore        # exclude .quarto/ and *.quarto_ipynb
+```
+
+**Key points:**
+- Pre/post-render scripts run as subprocesses with `cwd` set to the project directory
+- Scripts access environment variables via `Deno.env.get()` and can write files for verification
+- Use `validJsonWithFields` for JSON file verification (parses and compares field values exactly)
+- Use `ensureFileRegexMatches` for non-JSON files or when regex matching is needed
+- The file dump pattern (script writes JSON, test reads it) is useful for verifying env vars and other runtime state
+- Clean up both the dump file and the output directory in teardown
+- Existing fixtures: `tests/docs/project/prepost/` (mutate-render-list, invalid-mutate, extension, issue-10828, script-env-vars)
+
 ### Extension Template Tests
 
 For testing `quarto use template`:
@@ -164,6 +220,43 @@ folderExists(path: string)
 directoryEmptyButFor(dir: string, allowedFiles: string[])
 ```
 
+### Content Verifiers
+
+```typescript
+// Regex match on file contents (matches required, noMatches must be absent)
+ensureFileRegexMatches(file: string, matches: (string | RegExp)[], noMatches?: (string | RegExp)[])
+
+// Regex match on CSS files linked from HTML
+ensureCssRegexMatches(file: string, matches: (string | RegExp)[], noMatches?: (string | RegExp)[])
+
+// Check HTML elements exist or don't exist (CSS selectors)
+ensureHtmlElements(file: string, noElements: string[], elements: string[])
+
+// Verify JSON structure has expected fields (parses JSON, compares values with deep equality)
+validJsonWithFields(file: string, fields: Record<string, unknown>)
+
+// Check output message at specific log level
+printsMessage(options: { level: string, regex: RegExp })
+```
+
+### Assertion Helpers
+
+```typescript
+// Assert path exists (throws if missing)
+verifyPath(path: string)
+
+// Assert path does NOT exist (throws if present)
+verifyNoPath(path: string)
+```
+
+### Cleanup Helpers
+
+```typescript
+// Safe file removal (no error if missing) - from src/core/path.ts
+import { safeRemoveIfExists } from "../../../src/core/path.ts";
+safeRemoveIfExists(path: string)
+```
+
 ### Path Helpers
 
 ```typescript

news/changelog-1.9.md

@@ -109,6 +109,7 @@ All changes included in 1.9:
 
 ## Projects
 
+- ([#12444](https://github.com/quarto-dev/quarto-cli/pull/12444)): Improve pre/post render script logging with `Running script` prefix and add `QUARTO_PROJECT_SCRIPT_PROGRESS` and `QUARTO_PROJECT_SCRIPT_QUIET` environment variables so scripts can adapt their output.
 - ([#13892](https://github.com/quarto-dev/quarto-cli/issues/13892)): Fix `output-dir: ./` deleting entire project directory. `output-dir` must be a subdirectory of the project directory and check is now better to avoid deleting the project itself when it revolves to the same path.
 
 ### `website`

src/command/render/project.ts

@@ -78,6 +78,7 @@ import { Format } from "../../config/types.ts";
 import { fileExecutionEngine } from "../../execute/engine.ts";
 import { projectContextForDirectory } from "../../project/project-context.ts";
 import { ProjectType } from "../../project/types/types.ts";
+import { RunHandlerOptions } from "../../core/run/types.ts";
 
 const noMutationValidations = (
   projType: ProjectType,
@@ -937,52 +938,61 @@ async function runScripts(
   quiet: boolean,
   env?: { [key: string]: string },
 ) {
+  // initialize the environment if needed
+  if (env) {
+    env = {
+      ...env,
+    };
+  } else {
+    env = {};
+  }
+  if (!env) throw new Error("should never get here");
+
+  // Pass some argument as environment
+  env["QUARTO_PROJECT_SCRIPT_PROGRESS"] = progress ? "1" : "0";
+  env["QUARTO_PROJECT_SCRIPT_QUIET"] = quiet ? "1" : "0";
+
   for (let i = 0; i < scripts.length; i++) {
     const args = parseShellRunCommand(scripts[i]);
     const script = args[0];
 
     if (progress && !quiet) {
-      info(colors.bold(colors.blue(`${script}`)));
+      info(colors.bold(colors.blue(`Running script '${script}'`)));
     }
 
-    const handler = handlerForScript(script);
-    if (handler) {
-      if (env) {
-        env = {
-          ...env,
-        };
-      } else {
-        env = {};
-      }
-      if (!env) throw new Error("should never get here");
-      const input = Deno.env.get("QUARTO_USE_FILE_FOR_PROJECT_INPUT_FILES");
-      const output = Deno.env.get("QUARTO_USE_FILE_FOR_PROJECT_OUTPUT_FILES");
-      if (input) {
-        env["QUARTO_USE_FILE_FOR_PROJECT_INPUT_FILES"] = input;
-      }
-      if (output) {
-        env["QUARTO_USE_FILE_FOR_PROJECT_OUTPUT_FILES"] = output;
-      }
+    const handler = handlerForScript(script) ?? {
+      run: async (
+        script: string,
+        args: string[],
+        _stdin?: string,
+        options?: RunHandlerOptions,
+      ) => {
+        return await execProcess({
+          cmd: script,
+          args: args,
+          cwd: options?.cwd,
+          stdout: options?.stdout,
+          env: options?.env,
+        });
+      },
+    };
 
-      const result = await handler.run(script, args.splice(1), undefined, {
-        cwd: projDir,
-        stdout: quiet ? "piped" : "inherit",
-        env,
-      });
-      if (!result.success) {
-        throw new Error();
-      }
-    } else {
-      const result = await execProcess({
-        cmd: args[0],
-        args: args.slice(1),
-        cwd: projDir,
-        stdout: quiet ? "piped" : "inherit",
-        env,
-      });
-      if (!result.success) {
-        throw new Error();
-      }
+    const input = Deno.env.get("QUARTO_USE_FILE_FOR_PROJECT_INPUT_FILES");
+    const output = Deno.env.get("QUARTO_USE_FILE_FOR_PROJECT_OUTPUT_FILES");
+    if (input) {
+      env["QUARTO_USE_FILE_FOR_PROJECT_INPUT_FILES"] = input;
+    }
+    if (output) {
+      env["QUARTO_USE_FILE_FOR_PROJECT_OUTPUT_FILES"] = output;
+    }
+
+    const result = await handler.run(script, args.slice(1), undefined, {
+      cwd: projDir,
+      stdout: quiet ? "piped" : "inherit",
+      env,
+    });
+    if (!result.success) {
+      throw new Error();
     }
   }
   if (scripts.length > 0) {

tests/docs/project/prepost/extension/.gitignore

@@ -0,0 +1,2 @@
+/.quarto/
+**/*.quarto_ipynb

tests/docs/project/prepost/invalid-mutate/.gitignore

@@ -1 +1,3 @@
 /.quarto/
+
+**/*.quarto_ipynb

tests/docs/project/prepost/issue-10828/.gitignore

@@ -1 +1,3 @@
 /.quarto/
+
+**/*.quarto_ipynb

tests/docs/project/prepost/mutate-render-list/.gitignore

@@ -1 +1,3 @@
 /.quarto/
+
+**/*.quarto_ipynb

tests/docs/project/prepost/script-env-vars/.gitignore

@@ -0,0 +1,2 @@
+/.quarto/
+**/*.quarto_ipynb

tests/docs/project/prepost/script-env-vars/_quarto.yml

@@ -0,0 +1,10 @@
+project:
+  type: website
+  pre-render: check-env.ts
+
+website:
+  title: "script-env-vars"
+
+format:
+  html:
+    theme: cosmo

tests/docs/project/prepost/script-env-vars/about.qmd

@@ -0,0 +1,5 @@
+---
+title: About
+---
+
+About page