Add the deno_ral fs, temp and errors layer and the Deno.* codemod

.claude/rules/typescript/deno-essentials.md

@@ -49,19 +49,15 @@ import { join } from "jsr:/@std/path";
 
 ## Deno APIs vs Node.js
 
-Use Deno APIs directly:
+Import from the runtime layer (`src/deno_ral/`) instead of calling `Deno.*` directly:
 
 ```typescript
-// Correct - Deno APIs
-Deno.env.get("PATH");
-Deno.cwd();
-Deno.readTextFileSync(path);
-Deno.writeTextFileSync(path, content);
-Deno.makeTempDirSync({ prefix: "quarto" });
+// Correct - runtime layer
+import { readTextFileSync, writeTextFileSync } from "../deno_ral/fs.ts";
+import { makeTempDirSync } from "../deno_ral/temp.ts";
 
-// Wrong - Node.js patterns
-process.env.PATH;
-fs.readFileSync(path);
+// Wrong - direct runtime calls (the CI ratchet counts these)
+Deno.readTextFileSync(path);
 ```
 
 ## Sync vs Async
@@ -86,6 +82,7 @@ if (isWindows) {
 ## Lint Directives
 
 Common directives (use sparingly):
+
 - `no-explicit-any` - For Cliffy options, JSON parsing
 - `no-control-regex` - For regex with control characters
 

.claude/rules/typescript/deno-ral.md

@@ -9,14 +9,16 @@ The `deno_ral/` directory provides a runtime abstraction layer over Deno's stand
 
 ## Available Modules
 
-| Module | Purpose | Key exports |
-|--------|---------|-------------|
-| `fs.ts` | File system | `existsSync`, `ensureDirSync`, `copySync`, `safeMoveSync`, `safeRemoveSync` |
-| `path.ts` | Path utilities | `join`, `dirname`, `basename`, `extname` |
-| `log.ts` | Logging | `debug`, `info`, `warning`, `error` |
-| `kv.ts` | Deno KV cache stores | `openKv`, `getKv`, `kvOp`, `KvDamagedError` |
-| `platform.ts` | Platform detection | `isWindows` |
-| `process.ts` | Process execution | Process utilities |
+| Module        | Purpose                                  | Key exports                                                                                                                                                                                                                                                                                  |
+| ------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fs.ts`       | File system                              | `readTextFileSync`, `writeTextFileSync`, `statSync`, `readDirSync` (sorted), `removeSync`, `mkdirSync`, `copyFileSync`, `open`, `canonicalPathSync` (resolves symlinks), `existsSync`, `ensureDirSync`, `copySync`, `safeMoveSync`, `safeRemoveSync`; types `FileInfo`, `DirEntry`, `FsFile` |
+| `temp.ts`     | Temp files/dirs (retry on AlreadyExists) | `makeTempDirSync`, `makeTempDir`, `makeTempFileSync`, `makeTempFile`; type `TempOptions`                                                                                                                                                                                                     |
+| `errors.ts`   | Runtime-neutral error predicates         | `isNotFound`, `isAlreadyExists`, `isPermissionDenied`, `isAddrInUse`, `isConnectionRefused`, `isConnectionError`, `errorWithPath`                                                                                                                                                            |
+| `path.ts`     | Path utilities                           | `join`, `dirname`, `basename`, `extname`                                                                                                                                                                                                                                                     |
+| `log.ts`      | Logging                                  | `debug`, `info`, `warning`, `error`                                                                                                                                                                                                                                                          |
+| `kv.ts`       | Deno KV cache stores                     | `openKv`, `getKv`, `kvOp`, `KvDamagedError`                                                                                                                                                                                                                                                  |
+| `platform.ts` | Platform detection                       | `isWindows`                                                                                                                                                                                                                                                                                  |
+| `process.ts`  | Process execution                        | Process utilities                                                                                                                                                                                                                                                                            |
 
 ## Why Use deno_ral
 
@@ -28,6 +30,7 @@ The `deno_ral/` directory provides a runtime abstraction layer over Deno's stand
 ## Common Utilities
 
 **Temp files** (`src/core/temp.ts`):
+
 ```typescript
 import { createTempContext } from "../core/temp.ts";
 
@@ -40,6 +43,7 @@ try {
 ```
 
 **Process execution** (`src/core/process.ts`):
+
 ```typescript
 import { execProcess } from "../core/process.ts";
 
@@ -60,8 +64,18 @@ const result = await execProcess({
 ## Module Loading Order
 
 `src/quarto.ts` loads monkey patches first:
+
 ```typescript
-import "./core/deno/monkey-patch.ts";  // Must be first!
+import "./core/deno/monkey-patch.ts"; // Must be first!
 ```
 
 This ensures compatibility shims load before any code runs.
+
+## Moving code off `Deno.*`
+
+Outside `deno_ral/`, never add new `Deno.*` calls; import the equivalent from `deno_ral/`. The `deno_ral/` modules themselves implement those functions with `Deno.*`. To migrate existing files mechanically:
+
+    quarto run --dev tools/codemod-deno-ral.ts --rules fs,temp --dir src/<dir> --dry-run
+    quarto run --dev tools/codemod-deno-ral.ts --rules fs,temp --dir src/<dir>
+
+The tool reports local-name collisions (left as `Deno.*`; fix with an alias import such as `import { stat as fsStat } ...`, which later runs reuse) and skips files that assign to `Deno.*`, `src/core/lib` and the standalone scripts. Replace `instanceof Deno.errors.X` with the predicates in `deno_ral/errors.ts`. After a rebase conflict in a codemodded file, reset the file to `main` and re-run the codemod; never resolve by hand. `--reverse` produces the `Deno.*` form for backports (`dev-docs/checklist-backport-a-pr.md`).

.gitattributes

@@ -32,6 +32,8 @@ src/resources/library/dayjs/** linguist-vendored
 
 # use lf line-endings for source files
 src/** text eol=lf
+# codemod fixtures and tests compare file bytes verbatim
+tools/codemod/** text eol=lf
 
 # Denote all files that are truly binary and should not be modified.
 *.png binary

.github/workflows/runtime-boundary.yml

@@ -21,6 +21,8 @@ on:
       - "tests/**"
       - "tools/check-runtime-boundary.ts"
       - "tools/runtime-boundary-baseline.json"
+      - "tools/codemod-deno-ral.ts"
+      - "tools/codemod/**"
       - ".github/workflows/runtime-boundary.yml"
   push:
     branches: [main]
@@ -30,6 +32,8 @@ on:
       - "tests/**"
       - "tools/check-runtime-boundary.ts"
       - "tools/runtime-boundary-baseline.json"
+      - "tools/codemod-deno-ral.ts"
+      - "tools/codemod/**"
       - ".github/workflows/runtime-boundary.yml"
 
 permissions:
@@ -52,6 +56,9 @@ jobs:
       - name: Configure Quarto
         uses: ./.github/workflows/actions/quarto-dev
 
+      - name: Codemod contract test (tools/codemod)
+        run: package/dist/bin/tools/x86_64/deno test --allow-all --import-map=src/import_map.json tools/codemod/
+
       - name: Check runtime boundary
         shell: bash
         env:

dev-docs/checklist-backport-a-pr.md

@@ -8,6 +8,29 @@ We backport development PRs to the stable branch using the following steps:
 - Cherry-pick the commits from the development branch:
   - `git cherry-pick <commit>` for every commit identified above.
   - Resolve conflicts as needed.
+- If the stable branch predates the runtime-layer codemods (v1.10 and earlier: `src/deno_ral/fs.ts` there has no `readTextFileSync`) and a commit touches TypeScript, cherry-picking conflicts wherever its context lines were codemodded. Build the patch in the stable branch's `Deno.*` form instead, from the `main` checkout:
+
+  ```bash
+  c=<commit>
+  w=$(mktemp -d)/bp
+  git worktree add --detach "$w" "$c^"
+  changed() { git diff -z --no-renames --name-only --diff-filter="$1" "$c^" "$c" -- "${@:2}"; }
+  rev() {
+    changed "$1" '*.ts' | while IFS= read -r -d '' f; do
+      quarto run --dev tools/codemod-deno-ral.ts --reverse --rules fs,temp,env,process,platform \
+        --ral-dir "$w/src/deno_ral" --file "$w/$f"
+    done
+  }
+  rev MD && git -C "$w" commit -qam "reversed base" --allow-empty
+  changed AM | while IFS= read -r -d '' f; do git -C "$w" checkout "$c" -- "$f"; done
+  changed D | while IFS= read -r -d '' f; do git -C "$w" rm -q -- "$f"; done
+  rev AM
+  git -C "$w" add -A && git -C "$w" diff --cached HEAD > "$w.patch"
+  git worktree remove --force "$w"
+  ```
+
+  Then, on the stable branch: `git apply -3 "$w.patch" && git commit -C "$c"`. The tool prints `left:` for any layer name it cannot express (for example `args` used without a call) and never rewrites `deno_ral/errors.ts` predicates: grep the patch for `deno_ral/errors.ts` and `isNotFound(` and turn them into `instanceof Deno.errors.X` by hand. The tool reports `canonicalPathSync` as `left` (stable branches patch `Deno.realPathSync`): import `originalRealPathSync` from `deno_ral/original-real-path.ts` there.
+
 - Revert the changelog file changes if they were included in the original commits (the dev-branch `changelog-1.(x+1).md` does not exist on the stable branch, so the cherry-pick shows a modify/delete conflict — drop that hunk).
 - Add the new changelog entries to `news/changelog-1.x.md`, under `# v1.(x+1) backports` > `## In this release` at the top of the file.
   There are change categories in the development release but not in the backport release, so just add them chronologically to the section.