Merge pull request #111 from flypythoncom/fix/review-defects-20261022

chore: align engineering configuration and CI entry points

Author: xxg1413

.gitattributes

@@ -0,0 +1,3 @@
+# Stable LF checkouts keep generated JSON, source checksums and solution hashes
+# identical across contributor platforms, independent of core.autocrlf.
+* text=auto eol=lf

.github/workflows/validate.yml

@@ -1,6 +1,7 @@
 name: Validate
 
 on:
+  workflow_dispatch:
   pull_request:
   push:
     branches:
@@ -11,7 +12,8 @@ permissions:
 
 concurrency:
   group: validate-${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
+  # Preserve a complete default-branch validation; superseded PR runs can stop.
+  cancel-in-progress: ${{ github.ref != 'refs/heads/master' }}
 
 jobs:
   # Lowest and latest supported CPython; the universal lock already resolves

AGENTS.md

@@ -76,6 +76,16 @@ reviewed catalog data, and stable public JSON contracts.
 - After merge, verify the immutable raw `catalog.json`. Verify flypython.com only
   after a separate, deliberate consumer-version update.
 
+## Engineering entry points
+
+- `make help` lists the existing validation and generation tools.
+- `make setup` installs the locked dev environment; use
+  `make check PYTHON=.venv/bin/python` afterwards.
+- `make generated-check` is read-only; `make generate` rewrites derived content
+  in dependency order. Neither publishes or changes the website content pin.
+- Keep agent rules here; `CLAUDE.md` imports this file rather than copying it.
+- Engineering configuration rationale is in `docs/ENGINEERING_CONFIG.md`.
+
 ## Review priorities
 
 1. Content accuracy and source quality.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

CONTRIBUTING.md

@@ -84,6 +84,18 @@ and path folders that ship their own `requirements.txt` must pin exactly the
 versions in `requirements-dev.lock.txt` (`tests/test_dependency_pins.py`), so
 CI tests the stack learners install.
 
+With `uv` installed, `make setup` is an alternative to the manual setup above:
+it uses `.python-version` and synchronizes the exact dev lock into `.venv`.
+Then use `make check PYTHON=.venv/bin/python`; Make otherwise defaults to
+`python3`. The Make aliases assume a POSIX shell (Windows contributors can use
+the direct Python commands below or WSL). Run from this repository or use
+`make -C path/to/python`, not `make -f path/to/Makefile` from another directory.
+
+`make generated-check` checks derived content without rewriting it, including
+course solution hashes. `make generate` regenerates exports, README indexes,
+the content manifest and solution hashes in order; `make all` then runs checks.
+Both preserve ordering even when invoked with `make -j`.
+
 After changing catalog sources, regenerate the public export:
 
 ```bash
@@ -101,6 +113,7 @@ python tools/validate_catalog.py
 python tools/export_catalog.py --check --target both
 python tools/render_readmes.py --check
 python tools/build_content_manifest.py --check
+python tools/build_solution_hashes.py --check
 python tools/verify_examples.py
 python tools/verify_courses.py
 python tools/verify_paths.py

Makefile

@@ -1,4 +1,11 @@
-.PHONY: help check export render manifest test verify courses paths lint lock lock-check all
+# Recipes use repository-relative paths. Like Magpie's Makefile, fail closed
+# when invoked with `make -f path/to/Makefile` from an unrelated directory.
+ifeq ($(and $(wildcard pyproject.toml),$(wildcard tools/validate_catalog.py),$(wildcard catalog/catalog.yml)),)
+  $(error run make in the Python repository (make -C path/to/python))
+endif
+
+.DEFAULT_GOAL := help
+.PHONY: help setup check generated-check generate export render manifest solutions test verify courses paths lint lock lock-check all
 
 PYTHON ?= python3
 UV ?= uv
@@ -15,10 +22,14 @@ endef
 
 help:
 	@echo "FlyPython Development Workflow:"
-	@echo "  make check      - Run the same checks as CI: lint, tests, catalog, radar, export, readme, manifest, example, course, and path checks"
+	@echo "  make setup      - Create .venv using .python-version and install locked dev dependencies (requires uv)"
+	@echo "  make check      - Run CI checks (use PYTHON=.venv/bin/python after setup)"
+	@echo "  make generated-check - Check catalog, exports, READMEs, manifest, and solution hashes without rewriting"
+	@echo "  make generate   - Regenerate all derived content in dependency order"
 	@echo "  make export     - Regenerate catalog.json and radar.json"
 	@echo "  make render     - Regenerate root and catalog README indexes plus the Radar table"
 	@echo "  make manifest   - Regenerate content-manifest.json"
+	@echo "  make solutions  - Regenerate course-solutions.json"
 	@echo "  make lint       - Run ruff"
 	@echo "  make test       - Run pytest test suite"
 	@echo "  make verify     - Verify all runnable examples"
@@ -28,14 +39,29 @@ help:
 	@echo "  make lock-check - Fail if the lock files no longer match pyproject.toml"
 	@echo "  make all        - Regenerate all exports and run all checks and tests"
 
-check: lint test
+setup:
+	$(UV) venv --python "$$(cat .python-version)" .venv
+	$(UV) pip sync --python .venv/bin/python requirements-dev.lock.txt
+
+check: lint test generated-check
+	$(PYTHON) tools/verify_examples.py
+	$(PYTHON) tools/verify_courses.py
+	$(PYTHON) tools/verify_paths.py
+
+generated-check:
 	$(PYTHON) tools/validate_catalog.py
 	$(PYTHON) tools/export_catalog.py --check --target both
 	$(PYTHON) tools/render_readmes.py --check
 	$(PYTHON) tools/build_content_manifest.py --check
-	$(PYTHON) tools/verify_examples.py
-	$(PYTHON) tools/verify_courses.py
-	$(PYTHON) tools/verify_paths.py
+	$(PYTHON) tools/build_solution_hashes.py --check
+
+# Keep writers sequential even under make -j: README/manifest checks must not
+# race against a producer. No automatic commit, content-pin update or deploy.
+generate:
+	$(MAKE) export
+	$(MAKE) render
+	$(MAKE) manifest
+	$(MAKE) solutions
 
 export:
 	$(PYTHON) tools/export_catalog.py --target both
@@ -46,6 +72,9 @@ render:
 manifest:
 	$(PYTHON) tools/build_content_manifest.py
 
+solutions:
+	$(PYTHON) tools/build_solution_hashes.py
+
 lint:
 	$(PYTHON) -m ruff check .
 
@@ -72,4 +101,5 @@ lock-check:
 	@git diff --exit-code requirements.lock.txt requirements-dev.lock.txt || \
 		{ echo "lock files drifted from pyproject.toml — commit the regenerated files"; exit 1; }
 
-all: export render manifest check
+all: generate
+	$(MAKE) check

course-solutions.json

@@ -64,7 +64,7 @@
     {
       "slug": "mcp-server-in-python",
       "course_id": "course-mcp-tools",
-      "solution_sha256": "e9a0c348e12bd1f04d83783689f299e3ece8884f3f8a5be2f8a40655e211b790"
+      "solution_sha256": "3f58792fafaf0025f8766ca84ac8cae660e73868193fe55b61bb97548ac2aca7"
     },
     {
       "slug": "secure-ai-generated-code",

courses/mcp-server-in-python/TASK.md

@@ -15,6 +15,7 @@ Change only `starter/mcp_server.py`.
 - Supported methods:
   - `"tools/list"`: returns `{"result": {"tools": [{"name": ..., "description": ..., "inputSchema": ...}, ...]}}`.
   - `"tools/call"`: accepts `params: {"name": ..., "arguments": ..., "inputResponses": {...}?}` and calls the handler as `handler(arguments, inputResponses)`.
+    - If the tool name is missing or is not a string (including lists, objects, booleans, numbers, and null), return JSON-RPC error `-32602` (Invalid params), preserving the request ID.
     - If tool not registered: returns `{"result": {"isError": True, "content": [{"type": "text", "text": "Tool not found"}]}}`.
     - If required argument missing: returns `{"result": {"isError": True, "content": [{"type": "text", "text": "Missing required argument: <arg>"}]}}`.
     - If the handler raises `InputRequired(requests)`: returns `{"result": {"resultType": "input_required", "requests": <requests>, "content": [{"type": "text", "text": "Additional client input is required before this tool can finish."}]}}`. The client retries the same call with answers in `params.inputResponses`.

courses/mcp-server-in-python/TASK_cn.md

@@ -15,6 +15,7 @@
 - 支持的核心方法：
   - `"tools/list"`：返回 `{"result": {"tools": [{"name": ..., "description": ..., "inputSchema": ...}, ...]}}`。
   - `"tools/call"`：接收 `params: {"name": ..., "arguments": ..., "inputResponses": {...}?}`，并以 `handler(arguments, inputResponses)` 调用工具。
+    - 工具名缺失或不是字符串（包括列表、对象、布尔值、数字和 null）时，返回 JSON-RPC 错误码 `-32602`（Invalid params），并保留请求 ID。
     - 工具未找到：返回 `{"result": {"isError": True, "content": [{"type": "text", "text": "Tool not found"}]}}`。
     - 缺少 schema 中声明的必填参数：返回 `{"result": {"isError": True, "content": [{"type": "text", "text": "Missing required argument: <arg>"}]}}`。
     - 工具抛出 `InputRequired(requests)`：返回 `{"result": {"resultType": "input_required", "requests": <requests>, "content": [{"type": "text", "text": "Additional client input is required before this tool can finish."}]}}`。客户端携带 `params.inputResponses` 重试同一请求。

courses/mcp-server-in-python/solution/mcp_server.py

@@ -108,6 +108,15 @@ def handle_request(self, request: Any) -> dict[str, Any]:
                 }
 
             tool_name = params["name"]
+            if not isinstance(tool_name, str):
+                return {
+                    "jsonrpc": "2.0",
+                    "id": req_id,
+                    "error": {
+                        "code": -32602,
+                        "message": "Invalid params: tool name must be a string",
+                    },
+                }
             if tool_name not in self.tools:
                 return {
                     "jsonrpc": "2.0",