chore(mage): pin python requirements, update docs+mage

.devcontainer/Dockerfile.AZL-3.0

@@ -2,12 +2,12 @@ FROM mcr.microsoft.com/azurelinux/base/core:3.0
 
 # Install required packages
 RUN tdnf -y update && \
-    tdnf -y install ca-certificates dnf dnf-utils which gh git golang gawk tar shadow-utils sudo tree bash-completion moby-engine moby-cli build-essential python3-pip nodejs && \
+    tdnf -y install ca-certificates dnf dnf-utils which gh git golang gawk tar shadow-utils sudo tree bash-completion moby-engine moby-cli build-essential python3-pip && \
     tdnf clean all
 
-# Install ruff and pyright for Python linting/formatting/type-checking
-# (used by 'mage check python' / 'mage fix python'). pyright requires node (installed above).
-RUN pip3 install --no-cache-dir ruff pyright
+# Install the pinned Python lint tools.
+COPY requirements-lint.txt /tmp/requirements-lint.txt
+RUN pip3 install --no-cache-dir -r /tmp/requirements-lint.txt
 
 # Define the 'll' alias for all users
 RUN echo 'alias ll="ls -lah"' >> /etc/profile.d/aliases.sh && \
@@ -22,10 +22,10 @@ RUN useradd -m azldev && \
     usermod -aG docker azldev
 
 # Copy Docker daemon configuration
-COPY daemon.json /etc/docker/daemon.json
+COPY .devcontainer/daemon.json /etc/docker/daemon.json
 
 # Copy Docker start script
-COPY start-docker.sh /usr/local/bin/start-docker.sh
+COPY .devcontainer/start-docker.sh /usr/local/bin/start-docker.sh
 
 USER azldev
 

.devcontainer/README.md

@@ -9,7 +9,7 @@ The dev container uses the `azl_dev_3.0` image defined in `Dockerfile.AZL-3.0`.
 - Go development tools,
 - Mage build system,
 - golangci-lint,
-- ruff and pyright (plus Node.js, required by pyright) for Python linting/formatting/type-checking,
+- ruff and pyright from the repository's pinned [`requirements-lint.txt`](../requirements-lint.txt) for Python linting/formatting/type-checking,
 - required development dependencies for VS Code.
 
 ## Getting Started

.devcontainer/devcontainer.json

@@ -2,7 +2,7 @@
   "name": "AZL Dev 3.0",
   "build": {
     "dockerfile": "Dockerfile.AZL-3.0",
-    "context": "."
+    "context": ".."
   },
   "runArgs": [
     "--privileged"

.github/copilot-instructions.md

@@ -23,7 +23,8 @@ The `azldev-mage-builder` MCP server can run build commands without requesting p
 
 **ALWAYS start with `mage fix all`** when fixing linter issues - it automatically handles most formatting and simple fixes. Only manually fix the remaining issues that the auto-fixer cannot handle (both check and fix may take > 30 seconds the first time they run).
 
-Run `mage all` to verify changes pass all checks, this runs the scenario tests so it will be SLOW.
+Run `mage all` to verify Go changes and scenario tests. Run `mage check all` as well when
+changing Python or to include the optional Python lint and type checks.
 
 Project structure: `cmd/` (entry points), `internal/` (business logic), `magefiles/` (build config).
 

.github/dependabot.yml

@@ -36,6 +36,19 @@ updates:
         update-types:
           - "major"
 
+  # Python lint tools
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 7
+    groups:
+      dependabot-pip-python-tools:
+        applies-to: version-updates
+        patterns:
+          - "*"
+
   # Tools go.mod files
   - package-ecosystem: "gomod"
     directories:

.github/workflows/python.yml

@@ -28,8 +28,7 @@ jobs:
           persist-credentials: false
       - name: Get go tools
         uses: ./.github/getgotools
-      - name: Install ruff and pyright
-        # ubuntu-latest ships Python and Node.js; pyright requires Node.
-        run: pip install ruff pyright
+      - name: Install Python lint tools
+        run: pip install -r requirements-lint.txt
       - name: Run mage check python
         run: mage -v check python

.gitignore

@@ -30,6 +30,10 @@ go.work.sum
 # env file
 .env
 
+# python venv
+venv/
+.venv/
+
 # From https://github.com/github/gitignore/blob/main/Global/Archives.gitignore
 
 # It's better to unpack these files and commit the raw source because

docs/developer/how-to/dev-workflow.md

@@ -18,15 +18,15 @@
 Before submitting, ensure your changes pass all checks:
 
 ```bash
-mage all  # Comprehensive validation (will also invoke scenario tests, which will be slow)
+mage all  # Default Go validation (also invokes slow scenario tests)
 ```
 
 For faster iteration during development:
 
 ```bash
 mage build     # Rebuild the tool
 mage unit      # Fast unit tests
-mage check all # Code quality checks
+mage check all # All quality checks, including optional Python checks
 mage fix all   # Auto-fix issues
 ```
 

docs/developer/how-to/get-started.md

@@ -12,16 +12,23 @@
   go install github.com/magefile/mage@latest
   ```
 
-- **ruff** and **pyright** *(only if you touch Python code)* - Python linter/formatter
-  and type checker, used by `mage check python` / `mage fix python`. pyright requires
-  Node.js. The dev container installs all of these for you.
+- **Python and pip** *(only if you touch Python code)* - The repository pins
+   the `ruff` linter/formatter and `pyright` type checker in
+   [`requirements-lint.txt`](../../../requirements-lint.txt). They are used by `mage check python`
+   and `mage fix python`. Create and activate a virtual environment before installing the tools:
 
   ```bash
   # On Azure Linux
-  tdnf install -y python3-pip nodejs
-  pip3 install ruff pyright
+   tdnf install -y python3-pip
+
+   python3 -m venv .venv
+   source .venv/bin/activate
+   pip install -r requirements-lint.txt
   ```
 
+   Activate `.venv` in each shell before running `mage check python`, `mage fix python`,
+   or `mage check all`. The dev container installs the pinned tools for you.
+
 ## Initial Setup
 
 1. Fork the repository (strongly recommended for all contributors)

docs/developer/reference/build.md

@@ -2,9 +2,12 @@
 
 All code in this repo is written in `golang`. The `golang` package is required to build and run the tools.
 
-The build system uses mage, which can be installed with `go install github.com/magefile/mage@latest`. Alternatively, a zero-install approach is available through `go run magefile.go` or `./magefile.go`, which automatically downloads the required dependencies without manual installation. All additional build tools are managed automatically by go, and no manual tool installation is required.
+The build system uses mage, which can be installed with `go install github.com/magefile/mage@latest`. Alternatively, a zero-install approach is available through `go run magefile.go` or `./magefile.go`, which automatically downloads the required dependencies without manual installation. Go build tools are managed automatically by go.
 
-All other tooling dependencies are handled by `go tool`, which will automatically get the required tools when using `mage`. See [the tools section](../../../tools/README.md) for more information.
+
+All core tooling dependencies are handled by `go tool`, which will automatically get the required tools when using `mage`. See [the tools section](../../../tools/README.md) for more information.
+
+Optional Python lint tools are pinned in [`requirements-lint.txt`](../../../requirements-lint.txt). Before using a Mage target that runs Python checks, follow the virtual environment setup in [Getting Started](../how-to/get-started.md#prerequisites) so that `ruff` and `pyright` are on your `PATH`.
 
 This repo contains configs for the `golangci-lint` linter. It is installed as part of the [VSCode go extension](https://marketplace.visualstudio.com/items?itemName=golang.go). It's also optionally available as a [binary release](https://golangci-lint.run/docs/welcome/install/local/#binaries).
 
@@ -13,15 +16,16 @@ This repo contains configs for the `golangci-lint` linter. It is installed as pa
 | Command | Description | When to Use |
 |---------|-------------|-------------|
 | `mage -l` | List all available targets | To see all options |
-| `mage all` | Full build, test, and check pipeline | Before submitting PR |
+| `mage all` | Build, test, default checks, and scenario pipeline | Before submitting PR |
 | `mage build` | Build Go binaries | After code changes |
 | `mage install` | Build Go binaries and install | Outer-loop testing |
 | `mage unit` | Run unit tests | After writing tests |
 | `mage scenario` | Run scenario tests (SLOW) | For major changes |
 | `mage scenarioUpdate` | Update test snapshots | When test expectations change |
 | `mage mutation <path>` | Run mutation testing on a package; writes `out/mutation-report.json` | To assess test quality of a package |
 | `mage mutationDiff <ref>` | Run mutation testing on lines changed vs a git ref | To check test quality of a branch's changes |
-| `mage check all` | Run all quality checks | Before committing |
+| `mage check default` | Run default Go checks (lint, static analysis, license) | Before committing |
+| `mage check all` | Run all quality checks, including Python | Before committing or after Python changes |
 | `mage fix all` | Auto-fix code issues | When linting fails |
 | `mage generate` | Run `go generate ./...` (mockgen, stringer, etc.) | Seldom needed directly; runs automatically with build/test |
 | `mage docs` | Build binary + regenerate CLI docs and JSON schema | After changing config structs or CLI commands |

docs/developer/reference/coding-standards.md

@@ -59,6 +59,8 @@ Go binary).
   Run `mage check python` to lint and `mage fix python` to auto-format and apply fixes.
 - **Type checking**: All Python must pass `pyright` (config: [`pyrightconfig.json`](../../../pyrightconfig.json)).
   This is also run by `mage check python`.
+- **Tool installation**: Install the pinned versions from [`requirements-lint.txt`](../../../requirements-lint.txt)
+  in the virtual environment described in [Getting Started](../how-to/get-started.md#prerequisites).
 - Both checks are part of `mage check all`.
 
 ## Logging Guidelines

internal/app/azldev/core/sources/render_process.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-# Copyright (c) Microsoft Corporation.
+# Copyright (c) 2026 Microsoft Corporation.
 # Licensed under the MIT License.
 
 r"""Run rpmautospec and spectool for each component inside a mock chroot.

magefiles/magecheckfix/checkfix.go

@@ -20,6 +20,7 @@ import (
 // Meta targets for the checks and fixes.
 const (
 	TargetAll      = "all"
+	TargetDefault  = "default"
 	TargetMod      = "mod"
 	TargetLint     = "lint"
 	TargetStatic   = "static"
@@ -37,7 +38,7 @@ var (
 	ErrTypeCheck     = errors.New("type check failed")
 )
 
-// Check one of: [all, mod, lint, static, licenses, python].
+// Check one of: [all, default, mod, lint, static, licenses, python].
 // BASH-COMPLETION: This is scanned by the bash completion script, keep it in sync with the script.
 func Check(target string) error {
 	mg.SerialDeps(magesrc.Generate)
@@ -46,7 +47,9 @@ func Check(target string) error {
 
 	switch target {
 	case TargetAll:
-		mg.SerialDeps(modCheck, lintCheck, static, licenseCheck, pythonCheck)
+		mg.SerialDeps(defaultCheck, pythonCheck)
+	case TargetDefault:
+		mg.SerialDeps(defaultCheck)
 	case TargetMod:
 		mg.SerialDeps(modCheck)
 	case TargetLint:
@@ -59,14 +62,28 @@ func Check(target string) error {
 		mg.SerialDeps(pythonCheck)
 	default:
 		return fmt.Errorf("%w: unknown check target '%s'. Available targets: %v",
-			ErrCheck, target, []string{TargetAll, TargetMod, TargetLint, TargetStatic, TargetLicenses, TargetPython})
+			ErrCheck, target, []string{
+				TargetAll,
+				TargetDefault,
+				TargetMod,
+				TargetLint,
+				TargetStatic,
+				TargetLicenses,
+				TargetPython,
+			})
 	}
 
 	mageutil.MagePrintln(mageutil.MsgSuccess, "Done checking.")
 
 	return nil
 }
 
+func defaultCheck() error {
+	mg.SerialDeps(modCheck, lintCheck, static, licenseCheck)
+
+	return nil
+}
+
 // Fix one of: [all, mod, lint, python].
 // BASH-COMPLETION: This is scanned by the bash completion script, keep it in sync with the script.
 func Fix(target string) error {

magefiles/magefile.go

@@ -48,8 +48,8 @@ func init() {
 	}
 }
 
-// All runs the tests, builds the code, and checks for any issues.
+// All runs the tests, builds the code, and runs the default checks.
 func All() error {
-	mg.SerialDeps(magebuild.Build, magebuild.Unit, mg.F(magecheckfix.Check, magecheckfix.TargetAll), magescenario.Scenario, magebuild.Docs)
+	mg.SerialDeps(magebuild.Build, magebuild.Unit, mg.F(magecheckfix.Check, magecheckfix.TargetDefault), magescenario.Scenario, magebuild.Docs)
 	return nil
 }

requirements-lint.txt

@@ -0,0 +1,2 @@
+ruff==0.16.0
+pyright==1.1.411