Fix Windows file locking error when rendering with --output-dir

When --output-dir is used without a project file, Quarto creates a
synthetic project context with a temporary .quarto directory to manage
the render. This fix ensures file handles are closed before attempting
to remove the directory, preventing Windows "os error 32" (file in use
by another process).

The synthetic project pattern:
- Triggered when: quarto render file.qmd --output-dir output/ (no _quarto.yml)
- Creates temporary .quarto directory in current directory
- Uses full renderProject() path (not singleFileProjectContext())
- forceClean flag in RenderOptions signals cleanup needed
- After render: close handles (context.cleanup()) then remove directory

Improved comments to explain the synthetic project pattern, the dual
purpose of the forceClean flag, and critical ordering requirements to
avoid file locking issues on Windows.

Fixes #13625

Author: cderv

news/changelog-1.9.md

@@ -59,3 +59,4 @@ All changes included in 1.9:
 - ([#13402](https://github.com/quarto-dev/quarto-cli/issues/13402)): `nfpm` (<https://nfpm.goreleaser.com/>) is now used to create the `.deb` package, and new `.rpm` package. Both Linux packages are also now built for `x86_64` (`amd64`) and `aarch64` (`arm64`) architectures.
 - ([#13528](https://github.com/quarto-dev/quarto-cli/pull/13528)): Adds support for table specification using nested lists and the `list-table` class.
 - ([#13575](https://github.com/quarto-dev/quarto-cli/pull/13575)): Improve CPU architecture detection/reporting in macOS to allow quarto to run in virtualized environments such as OpenAI's `codex`.
+- ([#13625](https://github.com/quarto-dev/quarto-cli/issues/13625)): Fix Windows file locking error (os error 32) when rendering with `--output-dir` flag. Context cleanup now happens before removing the temporary `.quarto` directory, ensuring file handles are properly closed.

src/command/render/project.ts

@@ -886,13 +886,20 @@ export async function renderProject(
     );
   }
 
-  // in addition to the cleanup above, if forceClean is set, we need to clean up the project scratch dir
-  // entirely. See options.forceClean in render-shared.ts
-  // .quarto is really a fiction created because of `--output-dir` being set on non-project
-  // renders
+  // Clean up synthetic project created for --output-dir
+  // When --output-dir is used without a project file, we create a temporary
+  // project context with a .quarto directory (see render-shared.ts).
+  // After rendering completes, we must remove this directory to avoid leaving
+  // debris in non-project directories (#9745).
   //
-  // cf https://github.com/quarto-dev/quarto-cli/issues/9745#issuecomment-2125951545
+  // Critical ordering for Windows: Close file handles BEFORE removing directory
+  // to avoid "The process cannot access the file because it is being used by
+  // another process" (os error 32) (#13625).
   if (projectRenderConfig.options.forceClean) {
+    // 1. Close all file handles (KV database, temp context, etc.)
+    context.cleanup();
+
+    // 2. Remove the temporary .quarto directory
     const scratchDir = join(projDir, kQuartoScratch);
     if (existsSync(scratchDir)) {
       safeRemoveSync(scratchDir, { recursive: true });

src/command/render/render-shared.ts

@@ -48,12 +48,14 @@ export async function render(
   // determine target context/files
   let context = await projectContext(path, nbContext, options);
 
-  // if there is no project parent and an output-dir was passed, then force a project
+  // Create a synthetic project when --output-dir is used without a project file
+  // This creates a temporary .quarto directory to manage the render, which must
+  // be fully cleaned up afterward to avoid leaving debris (see #9745)
   if (!context && options.flags?.outputDir) {
-    // recompute context
     context = await projectContextForDirectory(path, nbContext, options);
 
-    // force clean as --output-dir implies fully overwrite the target
+    // forceClean signals this is a synthetic project that needs full cleanup
+    // including removing the .quarto scratch directory after rendering (#13625)
     options.forceClean = options.flags.clean !== false;
   }