Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

fix(scripts): honor SPECKIT_PYTHON override for preset manifest parsing (#4445)

Jialong(Bruce) Li88fd17a80ddc
diff --git a/scripts/bash/common.sh b/scripts/bash/common.sh
index 59e68099c..7b1516d29 100644
--- a/scripts/bash/common.sh
+++ b/scripts/bash/common.sh
@@ -406,7 +406,14 @@ check_file() { [[ -f "$1" ]] && echo " βœ“ $2" || echo " βœ— $2"; }
check_dir() { [[ -d "$1" && -n $(ls -A "$1" 2>/dev/null) ]] && echo " βœ“ $2" || echo " βœ— $2"; }
_python3_command() {
- if command -v python3 >/dev/null 2>&1 &&
+ # SPECKIT_PYTHON_EXECUTABLE is the canonical override; SPECKIT_PYTHON is
+ # kept as a deprecated fallback (still used by update-agent-context.sh).
+ local override="${SPECKIT_PYTHON_EXECUTABLE:-${SPECKIT_PYTHON:-}}"
+ if [[ -n "$override" ]] && command -v "$override" >/dev/null 2>&1 &&
+ "$override" -c 'import sys; raise SystemExit(sys.version_info.major != 3)' >/dev/null 2>&1 &&
+ "$override" -c 'import yaml' >/dev/null 2>&1; then
+ printf '%s\n' "$override"
+ elif command -v python3 >/dev/null 2>&1 &&
python3 -c 'import sys; raise SystemExit(sys.version_info.major != 3)' >/dev/null 2>&1; then
printf '%s\n' "python3"
elif command -v python >/dev/null 2>&1 &&
@@ -414,7 +421,7 @@ _python3_command() {
printf '%s\n' "python"
elif command -v py >/dev/null 2>&1 &&
py -3 -c 'import sys' >/dev/null 2>&1; then
- printf '%s\n' "py -3"
+ printf '%s\n' "py" "-3"
else
return 1
fi
@@ -422,10 +429,12 @@ _python3_command() {
_sorted_extension_ids() {
local ext_dir="$1"
- local python_spec
- if python_spec=$(_python3_command); then
- local -a python_cmd
- read -r -a python_cmd <<< "$python_spec"
+ local -a python_cmd=()
+ local _python_cmd_line
+ while IFS= read -r _python_cmd_line; do
+ python_cmd+=("$_python_cmd_line")
+ done < <(_python3_command)
+ if [ "${#python_cmd[@]}" -gt 0 ]; then
local py_stderr sorted_ids
py_stderr=$(mktemp)
if sorted_ids=$(SPECKIT_EXTENSIONS="$ext_dir" "${python_cmd[@]}" -c "
@@ -520,11 +529,11 @@ resolve_template() {
local presets_dir="$repo_root/.specify/presets"
if [ -d "$presets_dir" ]; then
local registry_file="$presets_dir/.registry"
- local python_spec=""
local -a python_cmd=()
- if python_spec=$(_python3_command); then
- read -r -a python_cmd <<< "$python_spec"
- fi
+ local _python_cmd_line
+ while IFS= read -r _python_cmd_line; do
+ python_cmd+=("$_python_cmd_line")
+ done < <(_python3_command)
if [ -f "$registry_file" ] && [ "${#python_cmd[@]}" -gt 0 ]; then
# Read preset IDs sorted by priority (lower number = higher precedence).
# The python3 call is wrapped in an if-condition so that set -e does not
@@ -643,11 +652,11 @@ resolve_template_content() {
local registry_file="$presets_dir/.registry"
local sorted_presets=""
local registry_parsed=false
- local python_spec=""
local -a python_cmd=()
- if python_spec=$(_python3_command); then
- read -r -a python_cmd <<< "$python_spec"
- fi
+ local _python_cmd_line
+ while IFS= read -r _python_cmd_line; do
+ python_cmd+=("$_python_cmd_line")
+ done < <(_python3_command)
if [ -f "$registry_file" ] && [ "${#python_cmd[@]}" -gt 0 ]; then
if sorted_presets=$(SPECKIT_REGISTRY="$registry_file" "${python_cmd[@]}" -c "
import json, re, sys, os
diff --git a/scripts/powershell/common.ps1 b/scripts/powershell/common.ps1
index d8c9d19bb..c90308ef9 100644
--- a/scripts/powershell/common.ps1
+++ b/scripts/powershell/common.ps1
@@ -327,6 +327,16 @@ function Format-SpecKitCommand {
# Find a usable Python 3 executable (python3, python, or py -3).
# Returns the command/arguments as an array, or $null if none found.
function Get-Python3Command {
+ # SPECKIT_PYTHON_EXECUTABLE is the canonical override; SPECKIT_PYTHON is
+ # kept as a deprecated fallback (still used by update-agent-context.sh).
+ $override = if ($env:SPECKIT_PYTHON_EXECUTABLE) { $env:SPECKIT_PYTHON_EXECUTABLE } else { $env:SPECKIT_PYTHON }
+ if ($override -and (Get-Command $override -ErrorAction SilentlyContinue)) {
+ $ver = & $override --version 2>&1
+ if ($ver -match 'Python 3') {
+ & $override -c 'import yaml' *> $null
+ if ($LASTEXITCODE -eq 0) { return @($override) }
+ }
+ }
if (Get-Command python3 -ErrorAction SilentlyContinue) { return @('python3') }
if (Get-Command python -ErrorAction SilentlyContinue) {
$ver = & python --version 2>&1
diff --git a/scripts/python/common.py b/scripts/python/common.py
index 5a2445a0e..0cd17e013 100644
--- a/scripts/python/common.py
+++ b/scripts/python/common.py
@@ -5,6 +5,7 @@ from __future__ import annotations
import json
import os
import re
+import subprocess
import sys
from dataclasses import dataclass
from pathlib import Path
@@ -386,6 +387,171 @@ def _validate_manifest_template_entry(entry: object) -> None:
)
+class _DelegatedYAMLError(Exception):
+ """Raised when a SPECKIT_PYTHON_EXECUTABLE-delegated manifest parse fails."""
+
+
+class _NonNativeYAMLValue:
+ """Marker for a YAML value with no native JSON equivalent (e.g. a date).
+
+ Preserves the fact that native ``yaml.safe_load`` would not have produced
+ a string/int/etc. here, so callers validating field types (e.g. that
+ ``file`` is a string) reject it the same way the in-process parser would,
+ instead of silently accepting a stringified value.
+ """
+
+ def __repr__(self) -> str:
+ return "<non-native YAML value>"
+
+
+_NON_NATIVE_MARKER_KEY = "$speckit_non_native"
+
+
+def _delegated_yaml_object_hook(obj: dict) -> object:
+ if len(obj) == 1 and obj.get(_NON_NATIVE_MARKER_KEY) is True:
+ return _NonNativeYAMLValue()
+ return obj
+
+
+class _DelegatedYAML:
+ """``yaml.safe_load`` proxy that shells out to SPECKIT_PYTHON_EXECUTABLE.
+
+ Used when this interpreter lacks PyYAML but SPECKIT_PYTHON_EXECUTABLE
+ (or the deprecated SPECKIT_PYTHON alias) names one that has it (e.g. a
+ `uv tool install` / `pipx` venv invisible to the bare `python3` a script
+ is launched with). See #4443.
+
+ Only ``_preset_template_layer`` calls this, and only the ``type``,
+ ``name``, ``file``, and ``strategy`` fields of each ``provides.templates``
+ entry are ever inspected, so the child drops every other top-level
+ manifest field (e.g. free-form ``metadata``) and every other per-entry
+ field (e.g. ``description``) before serializing: a valid, ignored YAML
+ alias DAG in either place is otherwise unrepresentable in JSON without
+ exponential blow-up on the round trip.
+ """
+
+ YAMLError = _DelegatedYAMLError
+
+ def __init__(self, python_exe: str) -> None:
+ self._python_exe = python_exe
+
+ def safe_load(self, text: str) -> object:
+ child_env = dict(os.environ, PYTHONIOENCODING="utf-8")
+ try:
+ proc = subprocess.run(
+ [
+ self._python_exe,
+ "-c",
+ "import sys, json, yaml\n"
+ "def _default(value):\n"
+ f" return {{'{_NON_NATIVE_MARKER_KEY}': True}}\n"
+ "def _stringify_keys(obj, stack=None):\n"
+ " if stack is None:\n"
+ " stack = set()\n"
+ " if isinstance(obj, (dict, list, tuple)):\n"
+ " if id(obj) in stack:\n"
+ f" return {{'{_NON_NATIVE_MARKER_KEY}': True}}\n"
+ " stack.add(id(obj))\n"
+ " try:\n"
+ " if isinstance(obj, dict):\n"
+ " return {\n"
+ " (k if isinstance(k, (str, int, float, bool)) or k is None else str(k)): _stringify_keys(v, stack)\n"
+ " for k, v in obj.items()\n"
+ " }\n"
+ " return [_stringify_keys(v, stack) for v in obj]\n"
+ " finally:\n"
+ " stack.discard(id(obj))\n"
+ " return obj\n"
+ "def _only_entry_fields(entry):\n"
+ " if not isinstance(entry, dict):\n"
+ " return _default(entry)\n"
+ " fields = {}\n"
+ " for k in ('type', 'name', 'file', 'strategy'):\n"
+ " if k not in entry:\n"
+ " continue\n"
+ " v = entry[k]\n"
+ " fields[k] = v if isinstance(v, str) else _default(v)\n"
+ " return fields\n"
+ "def _only_templates(data):\n"
+ " if not isinstance(data, dict):\n"
+ " return _default(data)\n"
+ " if 'provides' not in data:\n"
+ " return {}\n"
+ " provides = data['provides']\n"
+ " if not isinstance(provides, dict):\n"
+ " return {'provides': _default(provides)}\n"
+ " if 'templates' not in provides:\n"
+ " return {'provides': {}}\n"
+ " templates = provides['templates']\n"
+ " if not isinstance(templates, list):\n"
+ " return {'provides': {'templates': _default(templates)}}\n"
+ " return {\n"
+ " 'provides': {\n"
+ " 'templates': [_only_entry_fields(e) for e in templates]\n"
+ " }\n"
+ " }\n"
+ "try:\n"
+ " data = yaml.safe_load(sys.stdin.read())\n"
+ "except yaml.YAMLError as exc:\n"
+ " print(str(exc), file=sys.stderr)\n"
+ " sys.exit(1)\n"
+ "json.dump(_stringify_keys(_only_templates(data)), sys.stdout, default=_default)",
+ ],
+ input=text,
+ capture_output=True,
+ encoding="utf-8",
+ env=child_env,
+ timeout=10,
+ )
+ except (OSError, subprocess.TimeoutExpired) as exc:
+ raise _DelegatedYAMLError(
+ f"SPECKIT_PYTHON_EXECUTABLE could not parse the manifest: {exc}"
+ ) from exc
+ if proc.returncode != 0:
+ raise _DelegatedYAMLError(
+ proc.stderr.strip()
+ or "SPECKIT_PYTHON_EXECUTABLE could not parse the manifest"
+ )
+ try:
+ return json.loads(proc.stdout, object_hook=_delegated_yaml_object_hook)
+ except json.JSONDecodeError as exc:
+ raise _DelegatedYAMLError(
+ f"SPECKIT_PYTHON_EXECUTABLE returned invalid JSON: {exc}"
+ ) from exc
+
+
+def _import_yaml() -> object | None:
+ """Import PyYAML, delegating to SPECKIT_PYTHON_EXECUTABLE (or the
+ deprecated SPECKIT_PYTHON alias) if this interpreter lacks it."""
+ try:
+ import yaml
+
+ return yaml
+ except ImportError:
+ pass
+
+ python_override = os.environ.get("SPECKIT_PYTHON_EXECUTABLE") or os.environ.get(
+ "SPECKIT_PYTHON"
+ )
+ if not python_override:
+ return None
+ try:
+ probe = subprocess.run(
+ [
+ python_override,
+ "-c",
+ "import sys, yaml\nraise SystemExit(sys.version_info.major != 3)",
+ ],
+ capture_output=True,
+ timeout=10,
+ )
+ except (OSError, subprocess.TimeoutExpired):
+ return None
+ if probe.returncode != 0:
+ return None
+ return _DelegatedYAML(python_override)
+
+
def _preset_template_layer(
preset_dir: Path, template_name: str
) -> tuple[Path, str] | None:
@@ -393,57 +559,52 @@ def _preset_template_layer(
manifest_path = preset_dir / "preset.yml"
conventional = _conventional_template(preset_dir, template_name)
- try:
- import yaml
- except ImportError as exc:
- if manifest_path.is_file():
- raise TemplateResolutionError(
- "PyYAML is required to resolve preset template composition"
- ) from exc
+ if not manifest_path.is_file():
return (conventional, "replace") if conventional is not None else None
- if manifest_path.is_file():
- try:
- manifest = yaml.safe_load(manifest_path.read_text(encoding="utf-8"))
- if not isinstance(manifest, dict):
- raise ValueError("manifest root must be a mapping")
- if "provides" not in manifest:
- raise ValueError("manifest missing provides section")
- provides = manifest["provides"]
- if not isinstance(provides, dict):
- raise ValueError("manifest provides must be a mapping")
- if "templates" not in provides:
- raise ValueError("manifest provides missing templates")
- templates = provides["templates"]
- if not isinstance(templates, list):
- raise ValueError("manifest templates must be a list")
- if not templates:
- raise ValueError("manifest must provide at least one template")
- for entry in templates:
- _validate_manifest_template_entry(entry)
- for entry in templates:
- if (
- entry.get("name") != template_name
- or entry.get("type", "template") != "template"
- ):
- continue
- file_value = entry.get("file", "")
- strategy = entry.get("strategy", "replace")
- relative = Path(file_value)
- if (
- not relative
- or relative.is_absolute()
- or ".." in relative.parts
- ):
- return None
- candidate = preset_dir / relative
- if not candidate.is_file():
- return None
- return candidate, strategy.lower()
- except (OSError, UnicodeError, ValueError, yaml.YAMLError) as exc:
- raise TemplateResolutionError(
- f"Failed to parse preset manifest {manifest_path}: {exc}"
- ) from exc
+ yaml = _import_yaml()
+ if yaml is None:
+ raise TemplateResolutionError(
+ "PyYAML is required to resolve preset template composition"
+ )
+
+ try:
+ manifest = yaml.safe_load(manifest_path.read_text(encoding="utf-8"))
+ if not isinstance(manifest, dict):
+ raise ValueError("manifest root must be a mapping")
+ if "provides" not in manifest:
+ raise ValueError("manifest missing provides section")
+ provides = manifest["provides"]
+ if not isinstance(provides, dict):
+ raise ValueError("manifest provides must be a mapping")
+ if "templates" not in provides:
+ raise ValueError("manifest provides missing templates")
+ templates = provides["templates"]
+ if not isinstance(templates, list):
+ raise ValueError("manifest templates must be a list")
+ if not templates:
+ raise ValueError("manifest must provide at least one template")
+ for entry in templates:
+ _validate_manifest_template_entry(entry)
+ for entry in templates:
+ if (
+ entry.get("name") != template_name
+ or entry.get("type", "template") != "template"
+ ):
+ continue
+ file_value = entry.get("file", "")
+ strategy = entry.get("strategy", "replace")
+ relative = Path(file_value)
+ if not relative or relative.is_absolute() or ".." in relative.parts:
+ return None
+ candidate = preset_dir / relative
+ if not candidate.is_file():
+ return None
+ return candidate, strategy.lower()
+ except (OSError, UnicodeError, ValueError, yaml.YAMLError) as exc:
+ raise TemplateResolutionError(
+ f"Failed to parse preset manifest {manifest_path}: {exc}"
+ ) from exc
return (conventional, "replace") if conventional is not None else None
diff --git a/tests/parity_helpers.py b/tests/parity_helpers.py
index 5ab3fcfa0..bc6edc0ac 100644
--- a/tests/parity_helpers.py
+++ b/tests/parity_helpers.py
@@ -4,6 +4,7 @@ from __future__ import annotations
import json
import os
+import shlex
import shutil
import subprocess
import sys
@@ -79,9 +80,113 @@ def clean_env() -> dict[str, str]:
for key in list(env):
if key.startswith("SPECIFY_"):
env.pop(key)
+ # A --without-pip venv still honors an inherited PYTHONPATH, so leaving
+ # this set could make a "no-PyYAML" test interpreter import PyYAML
+ # anyway, silently skipping the delegated-parsing path under test.
+ env.pop("PYTHONPATH", None)
+ # Tests exercising SPECKIT_PYTHON_EXECUTABLE/SPECKIT_PYTHON set them
+ # explicitly; an ambient value in the host environment would otherwise
+ # silently override the "unset" baseline for every other test.
+ env.pop("SPECKIT_PYTHON_EXECUTABLE", None)
+ env.pop("SPECKIT_PYTHON", None)
return env
+def venv_python3_exe(venv_dir: Path) -> Path:
+ """Path to the python3 executable of a venv created with ``--without-pip``."""
+ if os.name == "nt":
+ return venv_dir / "Scripts" / "python.exe"
+ return venv_dir / "bin" / "python3"
+
+
+def make_yaml_less_venv(venv_dir: Path) -> Path:
+ """Create a ``--without-pip`` venv and return its python3 executable.
+
+ Asserts the interpreter cannot actually import PyYAML, since it could
+ otherwise be visible via an inherited ``PYTHONPATH`` despite
+ ``--without-pip``, silently invalidating tests that assume it lacks one.
+ """
+ subprocess.run(
+ [sys.executable, "-m", "venv", "--without-pip", str(venv_dir)],
+ check=True,
+ capture_output=True,
+ )
+ exe = venv_python3_exe(venv_dir)
+ assert exe.is_file()
+ probe = subprocess.run(
+ [str(exe), "-c", "import yaml"],
+ capture_output=True,
+ env=clean_env(),
+ check=False,
+ )
+ assert probe.returncode != 0, "venv unexpectedly has PyYAML importable"
+ return exe
+
+
+def _bash_posix_path(path: Path) -> str:
+ """Convert a Windows path to the POSIX form the available bash expects.
+
+ Uses ``abspath`` rather than ``Path.resolve()``: the caller may pass a
+ venv's python3, which is typically a symlink, and resolving it would
+ exec the underlying base interpreter from outside the venv directory,
+ silently dropping that venv's site-packages isolation.
+ """
+ resolved = os.path.abspath(path)
+ if os.name != "nt":
+ return resolved
+ converted = subprocess.run(
+ [
+ "bash",
+ "-lc",
+ 'command -v cygpath >/dev/null 2>&1 && cygpath -u "$1"',
+ "bash",
+ resolved,
+ ],
+ capture_output=True,
+ text=True,
+ timeout=30,
+ )
+ if converted.returncode == 0 and converted.stdout.strip():
+ return converted.stdout.strip()
+ drive = path.drive.rstrip(":").lower()
+ posix = path.as_posix()
+ return f"/mnt/{drive}{posix[2:]}" if drive else posix
+
+
+def make_python3_path_shim(shim_dir: Path, target: Path | str | None = None) -> Path:
+ """Create a deterministic ``python3`` shim that execs ``target`` (the
+ current pytest interpreter by default), so a test can put a guaranteed
+ interpreter first on PATH as the *default* ``python3`` a script finds via
+ its python3 -> python -> py -3 fallback chain (as opposed to the
+ SPECKIT_PYTHON(_EXECUTABLE) override, which names its interpreter
+ explicitly and never depends on PATH lookup).
+
+ A venv's own bin/Scripts directory is not enough on Windows: it provides
+ ``python.exe``, not ``python3``, so it never actually shadows a PATH
+ lookup for ``python3``. This shim exists precisely to fill that gap.
+ """
+ shim_dir.mkdir(parents=True, exist_ok=True)
+ # Deliberately not .resolve(): a venv's python3 is typically a symlink,
+ # and following it to the underlying base interpreter would exec it
+ # from outside the venv directory, which drops pyvenv.cfg discovery and
+ # silently regains/loses that venv's site-packages (e.g. PyYAML).
+ python_exe = Path(target if target is not None else sys.executable).absolute()
+
+ shell_shim = shim_dir / "python3"
+ shell_shim.write_text(
+ f"#!/usr/bin/env sh\nexec {shlex.quote(_bash_posix_path(python_exe))} \"$@\"\n",
+ encoding="utf-8",
+ newline="\n",
+ )
+ shell_shim.chmod(0o755)
+
+ if os.name == "nt":
+ cmd_shim = shim_dir / "python3.cmd"
+ cmd_shim.write_text(f'@echo off\r\n"{python_exe}" %*\r\n', encoding="utf-8")
+
+ return shim_dir
+
+
def collation_range_locale() -> str | None:
"""A locale whose ``[a-z]`` bracket range is collation-ordered, or ``None``.
@@ -156,7 +261,7 @@ def install_composition_stack(
"""Install wrap/prepend/append presets over a core template."""
templates = repo / ".specify" / "templates"
templates.mkdir(parents=True, exist_ok=True)
- (templates / f"{template_name}.md").write_text(core_content, encoding="utf-8")
+ (templates / f"{template_name}.md").write_bytes(core_content.encode("utf-8"))
layers = [
("wrap-pack", 1, "wrap", "## Wrapper\n{CORE_TEMPLATE}\n## End\n"),
@@ -171,7 +276,7 @@ def install_composition_stack(
preset_dir = repo / ".specify" / "presets" / preset_id
template_dir = preset_dir / "templates"
template_dir.mkdir(parents=True)
- (template_dir / f"{template_name}.md").write_text(content, encoding="utf-8")
+ (template_dir / f"{template_name}.md").write_bytes(content.encode("utf-8"))
(preset_dir / "preset.yml").write_text(
"provides:\n"
" templates:\n"
diff --git a/tests/test_resolve_template_python_parity.py b/tests/test_resolve_template_python_parity.py
index 2bf9977e1..7e5f3a208 100644
--- a/tests/test_resolve_template_python_parity.py
+++ b/tests/test_resolve_template_python_parity.py
@@ -4,10 +4,14 @@ from __future__ import annotations
import json
import os
+import subprocess
+import sys
+import time
from pathlib import Path
import pytest
+from scripts.python import common as python_common
from tests.conftest import requires_bash
from tests.parity_helpers import (
HAS_POWERSHELL,
@@ -16,7 +20,9 @@ from tests.parity_helpers import (
install_composition_stack,
install_scripts,
json_stdout,
+ make_python3_path_shim,
make_repo,
+ make_yaml_less_venv,
ps_cmd,
py_cmd,
run,
@@ -648,6 +654,723 @@ def test_all_variants_fail_when_yaml_parser_is_unavailable(
assert all(result.stdout == "" for result in results)
+@requires_bash
+def test_all_variants_honor_speckit_python_override_when_yaml_missing(
+ tmp_path: Path,
+) -> None:
+ """SPECKIT_PYTHON can name an interpreter with PyYAML when the default
+ one lacks it, e.g. a `uv tool install` venv invisible to bare `python3`
+ on PATH (#4443)."""
+ repo, expected = _setup_repo(tmp_path)
+
+ no_yaml_exe = make_yaml_less_venv(tmp_path / "no-yaml-venv")
+ no_yaml_python3_shim = make_python3_path_shim(
+ tmp_path / "no-yaml-python3-shim", no_yaml_exe
+ )
+
+ py_script = repo / ".specify" / "scripts" / "python" / "resolve_template.py"
+
+ baseline_env = clean_env()
+ baseline_env.pop("SPECKIT_PYTHON", None)
+ baseline_env["PATH"] = (
+ f"{no_yaml_python3_shim}{os.pathsep}{baseline_env.get('PATH', '')}"
+ )
+ baseline_results = [
+ run(bash_cmd(repo, SCRIPT, TEMPLATE, "--json"), repo, baseline_env),
+ run([str(no_yaml_exe), str(py_script), TEMPLATE, "--json"], repo, baseline_env),
+ ]
+ if HAS_POWERSHELL:
+ baseline_results.append(
+ run(ps_cmd(repo, SCRIPT, TEMPLATE, "-Json"), repo, baseline_env)
+ )
+ assert all(result.returncode != 0 for result in baseline_results)
+
+ override_env = dict(baseline_env)
+ override_env["SPECKIT_PYTHON"] = sys.executable
+ override_results = [
+ run(bash_cmd(repo, SCRIPT, TEMPLATE, "--json"), repo, override_env),
+ run([str(no_yaml_exe), str(py_script), TEMPLATE, "--json"], repo, override_env),
+ ]
+ if HAS_POWERSHELL:
+ override_results.append(
+ run(ps_cmd(repo, SCRIPT, TEMPLATE, "-Json"), repo, override_env)
+ )
+
+ assert all(result.returncode == 0 for result in override_results)
+ assert all(
+ json_stdout(result)
+ == {"TEMPLATE_NAME": TEMPLATE, "TEMPLATE_CONTENT": expected}
+ for result in override_results
+ )
+
+
+@requires_bash
+def test_all_variants_fall_back_when_speckit_python_lacks_pyyaml(
+ tmp_path: Path,
+) -> None:
+ """SPECKIT_PYTHON naming a Python-3 interpreter without PyYAML must not
+ break composition that a PATH interpreter can already serve.
+
+ SPECKIT_PYTHON is an override for *expanding* what's available (#4443),
+ not a way to narrow it: falling through to a working PATH interpreter
+ when the override lacks PyYAML must behave the same as if SPECKIT_PYTHON
+ had never been set.
+
+ `clean_env()` preserves the host PATH, which may hold nothing but a
+ PyYAML-less system `python3` even when pytest itself was launched with a
+ PyYAML-equipped `.venv/bin/python`. A deterministic `python3` shim put
+ first on PATH keeps the fallback precondition true regardless of the
+ host environment.
+ """
+ repo, expected = _setup_repo(tmp_path)
+
+ no_yaml_exe = make_yaml_less_venv(tmp_path / "no-yaml-venv")
+ python3_shim = make_python3_path_shim(tmp_path / "python3-shim")
+
+ env = clean_env()
+ env["SPECKIT_PYTHON"] = str(no_yaml_exe)
+ env["PATH"] = f"{python3_shim}{os.pathsep}{env.get('PATH', '')}"
+
+ results = [
+ run(bash_cmd(repo, SCRIPT, TEMPLATE, "--json"), repo, env),
+ ]
+ if HAS_POWERSHELL:
+ results.append(run(ps_cmd(repo, SCRIPT, TEMPLATE, "-Json"), repo, env))
+
+ assert all(result.returncode == 0 for result in results)
+ assert all(
+ json_stdout(result)
+ == {"TEMPLATE_NAME": TEMPLATE, "TEMPLATE_CONTENT": expected}
+ for result in results
+ )
+
+
+@requires_bash
+def test_all_variants_prefer_speckit_python_executable_when_both_set(
+ tmp_path: Path,
+) -> None:
+ """SPECKIT_PYTHON_EXECUTABLE is the canonical override and must take
+ precedence over the deprecated SPECKIT_PYTHON alias when both are set
+ (#4445). PATH's own `python3` is also PyYAML-less, so composition can
+ only succeed if SPECKIT_PYTHON_EXECUTABLE (not the PyYAML-less
+ SPECKIT_PYTHON) is the interpreter actually selected.
+ """
+ repo, expected = _setup_repo(tmp_path)
+
+ no_yaml_exe = make_yaml_less_venv(tmp_path / "no-yaml-venv")
+ no_yaml_bin = no_yaml_exe.parent
+
+ py_script = repo / ".specify" / "scripts" / "python" / "resolve_template.py"
+
+ env = clean_env()
+ env["SPECKIT_PYTHON_EXECUTABLE"] = sys.executable
+ env["SPECKIT_PYTHON"] = str(no_yaml_exe)
+ env["PATH"] = f"{no_yaml_bin}{os.pathsep}{env.get('PATH', '')}"
+
+ results = [
+ run(bash_cmd(repo, SCRIPT, TEMPLATE, "--json"), repo, env),
+ run([str(no_yaml_exe), str(py_script), TEMPLATE, "--json"], repo, env),
+ ]
+ if HAS_POWERSHELL:
+ results.append(run(ps_cmd(repo, SCRIPT, TEMPLATE, "-Json"), repo, env))
+
+ assert all(result.returncode == 0 for result in results)
+ assert all(
+ json_stdout(result)
+ == {"TEMPLATE_NAME": TEMPLATE, "TEMPLATE_CONTENT": expected}
+ for result in results
+ )
+
+
+def test_clean_env_strips_pythonpath(monkeypatch: pytest.MonkeyPatch) -> None:
+ """A ``--without-pip`` venv still honors an inherited `PYTHONPATH`, so a
+ leaked `PYTHONPATH` pointing at a directory with PyYAML would let the
+ "no-PyYAML" interpreters used above import it anyway, silently making
+ those tests pass without exercising the `SPECKIT_PYTHON`/delegated-YAML
+ path they claim to cover (#4445)."""
+ monkeypatch.setenv("PYTHONPATH", "/somewhere/with/yaml")
+ assert "PYTHONPATH" not in clean_env()
+
+
+def test_clean_env_strips_speckit_python(monkeypatch: pytest.MonkeyPatch) -> None:
+ """An ambient `SPECKIT_PYTHON`/`SPECKIT_PYTHON_EXECUTABLE` in the
+ host/CI environment would otherwise survive into every baseline built
+ from `clean_env()`, silently bypassing the blocked/default interpreter
+ that tests like `test_all_variants_fail_when_yaml_parser_is_unavailable`
+ rely on. Tests that exercise the override set it explicitly after
+ calling `clean_env()` (#4445)."""
+ monkeypatch.setenv("SPECKIT_PYTHON", "/somewhere/with/yaml")
+ monkeypatch.setenv("SPECKIT_PYTHON_EXECUTABLE", "/somewhere/else/with/yaml")
+ env = clean_env()
+ assert "SPECKIT_PYTHON" not in env
+ assert "SPECKIT_PYTHON_EXECUTABLE" not in env
+
+
+@requires_bash
+def test_bash_honors_speckit_python_path_containing_spaces(tmp_path: Path) -> None:
+ """SPECKIT_PYTHON may be an absolute path containing spaces (e.g. a venv
+ named "tool env"); callers must treat it as one argv element rather than
+ splitting it on whitespace (#4445).
+
+ A shim script that execs `sys.executable` guarantees the spaced path
+ actually has PyYAML: a symlink would not do, since `sys.executable` may
+ itself be a venv-relative symlink (e.g. under `uv run`), and invoking it
+ through a second symlink placed outside that venv's directory tree
+ breaks Python's `pyvenv.cfg` discovery, silently hiding the venv's
+ site-packages (and PyYAML with it). Exec'ing the real path from a shim
+ keeps `argv[0]` at its original, correctly-resolvable location. PATH's
+ `python3` is a PyYAML-less venv, so success is only possible if
+ `_python3_command` selects the spaced override intact.
+ """
+ repo, expected = _setup_repo(tmp_path)
+
+ spaced_dir = tmp_path / "tool env"
+ spaced_dir.mkdir()
+ spaced_exe = spaced_dir / Path(sys.executable).name
+ spaced_exe.write_text(f'#!/bin/sh\nexec "{sys.executable}" "$@"\n')
+ spaced_exe.chmod(0o755)
+
+ no_yaml_bin = make_yaml_less_venv(tmp_path / "no-yaml-venv").parent
+
+ env = clean_env()
+ env["SPECKIT_PYTHON"] = str(spaced_exe)
+ env["PATH"] = f"{no_yaml_bin}{os.pathsep}{env.get('PATH', '')}"
+
+ result = run(bash_cmd(repo, SCRIPT, TEMPLATE, "--json"), repo, env)
+
+ assert result.returncode == 0, result.stderr
+ assert json_stdout(result) == {
+ "TEMPLATE_NAME": TEMPLATE,
+ "TEMPLATE_CONTENT": expected,
+ }
+
+
+@requires_bash
+def test_python_variant_delegates_manifest_with_non_json_native_yaml_value(
+ tmp_path: Path,
+) -> None:
+ """A manifest holding a value PyYAML parses into a non-JSON-native type
+ (e.g. an unquoted date) must still resolve when the Python twin delegates
+ parsing to SPECKIT_PYTHON because its own interpreter lacks PyYAML."""
+ repo, expected = _setup_repo(tmp_path)
+
+ manifest = repo / ".specify" / "presets" / "wrap-pack" / "preset.yml"
+ manifest.write_text(
+ "created_at: 2026-09-08\n" + manifest.read_text(encoding="utf-8"),
+ encoding="utf-8",
+ )
+
+ no_yaml_exe = make_yaml_less_venv(tmp_path / "no-yaml-venv")
+
+ py_script = repo / ".specify" / "scripts" / "python" / "resolve_template.py"
+ env = clean_env()
+ env["SPECKIT_PYTHON"] = sys.executable
+
+ result = run([str(no_yaml_exe), str(py_script), TEMPLATE, "--json"], repo, env)
+
+ assert result.returncode == 0, result.stderr
+ assert json_stdout(result) == {
+ "TEMPLATE_NAME": TEMPLATE,
+ "TEMPLATE_CONTENT": expected,
+ }
+
+
+@requires_bash
+def test_python_variant_rejects_delegated_manifest_with_non_string_validated_field(
+ tmp_path: Path,
+) -> None:
+ """A validated field (``file``) holding a value PyYAML parses into a
+ non-JSON-native type (e.g. an unquoted date) must be rejected via
+ delegation exactly as the in-process parser rejects it, not silently
+ coerced to a string that passes the ``isinstance(str)`` check (#4445)."""
+ repo, _ = _setup_repo(tmp_path)
+
+ manifest = repo / ".specify" / "presets" / "wrap-pack" / "preset.yml"
+ manifest.write_text(
+ "provides:\n"
+ " templates:\n"
+ " - type: template\n"
+ f" name: {TEMPLATE}\n"
+ " file: 2026-09-08\n"
+ " strategy: wrap\n",
+ encoding="utf-8",
+ )
+
+ no_yaml_exe = make_yaml_less_venv(tmp_path / "no-yaml-venv")
+
+ py_script = repo / ".specify" / "scripts" / "python" / "resolve_template.py"
+ env = clean_env()
+ env["SPECKIT_PYTHON"] = sys.executable
+
+ result = run([str(no_yaml_exe), str(py_script), TEMPLATE, "--json"], repo, env)
+
+ assert result.returncode != 0
+ assert result.stdout == ""
+
+
+@requires_bash
+def test_python_variant_delegates_manifest_with_non_ascii_metadata_under_ascii_locale(
+ tmp_path: Path,
+) -> None:
+ """Delegated manifest parsing must force UTF-8 on the subprocess pipe and
+ the child's own stdio, not the process locale, so non-ASCII metadata in a
+ manifest still resolves when this interpreter lacks PyYAML and the
+ process is running under a forced ASCII locale (#4445)."""
+ repo, expected = _setup_repo(tmp_path)
+
+ manifest = repo / ".specify" / "presets" / "wrap-pack" / "preset.yml"
+ manifest.write_text(
+ manifest.read_text(encoding="utf-8") + ' description: "CafΓ© βœ“"\n',
+ encoding="utf-8",
+ )
+
+ no_yaml_exe = make_yaml_less_venv(tmp_path / "no-yaml-venv")
+
+ py_script = repo / ".specify" / "scripts" / "python" / "resolve_template.py"
+ env = clean_env()
+ env["SPECKIT_PYTHON"] = sys.executable
+ env["PYTHONUTF8"] = "0"
+ env["PYTHONCOERCECLOCALE"] = "0"
+ env["LC_ALL"] = "C"
+ env["LANG"] = "C"
+
+ result = run([str(no_yaml_exe), str(py_script), TEMPLATE, "--json"], repo, env)
+
+ assert result.returncode == 0, result.stderr
+ assert json_stdout(result) == {
+ "TEMPLATE_NAME": TEMPLATE,
+ "TEMPLATE_CONTENT": expected,
+ }
+
+
+@requires_bash
+def test_python_variant_delegates_manifest_with_non_json_native_mapping_key(
+ tmp_path: Path,
+) -> None:
+ """An otherwise-ignored mapping whose key PyYAML parses into a
+ non-JSON-native type (e.g. an unquoted date) must not break delegation:
+ `json.dump`'s `default` hook only applies to values, never to keys, so
+ such a key must be stringified before serialization instead of raising
+ `TypeError` (#4445)."""
+ repo, expected = _setup_repo(tmp_path)
+
+ manifest = repo / ".specify" / "presets" / "wrap-pack" / "preset.yml"
+ manifest.write_text(
+ "metadata:\n 2026-09-08: value\n" + manifest.read_text(encoding="utf-8"),
+ encoding="utf-8",
+ )
+
+ no_yaml_exe = make_yaml_less_venv(tmp_path / "no-yaml-venv")
+
+ py_script = repo / ".specify" / "scripts" / "python" / "resolve_template.py"
+ env = clean_env()
+ env["SPECKIT_PYTHON"] = sys.executable
+
+ result = run([str(no_yaml_exe), str(py_script), TEMPLATE, "--json"], repo, env)
+
+ assert result.returncode == 0, result.stderr
+ assert json_stdout(result) == {
+ "TEMPLATE_NAME": TEMPLATE,
+ "TEMPLATE_CONTENT": expected,
+ }
+
+
+def test_python_variant_delegates_manifest_with_omap_metadata(
+ tmp_path: Path,
+) -> None:
+ """An ignored `!!omap` metadata value must not break delegation:
+ PyYAML's safe loader represents `!!omap`/`!!pairs` entries as tuples,
+ which naive recursive normalization returns unchanged, so a nested
+ non-JSON-native mapping key inside one (e.g. an unquoted date) still
+ reaches `json.dump` unstringified and raises `TypeError`, even though
+ the in-process parser accepts and ignores the same metadata (#4445)."""
+ repo, expected = _setup_repo(tmp_path)
+
+ manifest = repo / ".specify" / "presets" / "wrap-pack" / "preset.yml"
+ manifest.write_text(
+ "metadata: !!omap\n - entry:\n 2026-09-08: value\n"
+ + manifest.read_text(encoding="utf-8"),
+ encoding="utf-8",
+ )
+
+ no_yaml_exe = make_yaml_less_venv(tmp_path / "no-yaml-venv")
+
+ py_script = repo / ".specify" / "scripts" / "python" / "resolve_template.py"
+ env = clean_env()
+ env["SPECKIT_PYTHON"] = sys.executable
+
+ result = run([str(no_yaml_exe), str(py_script), TEMPLATE, "--json"], repo, env)
+
+ assert result.returncode == 0, result.stderr
+ assert json_stdout(result) == {
+ "TEMPLATE_NAME": TEMPLATE,
+ "TEMPLATE_CONTENT": expected,
+ }
+
+
+@requires_bash
+def test_python_variant_delegates_manifest_with_recursive_yaml_alias(
+ tmp_path: Path,
+) -> None:
+ """An ignored `metadata` mapping containing a self-referential YAML alias
+ (`&m {self: *m}`) must not break delegation: `yaml.safe_load` supports
+ this via a shared reference, so naive recursive serialization of the
+ same object forever revisits it and raises `RecursionError` instead of
+ ignoring the unused field the way the in-process parser does (#4445)."""
+ repo, expected = _setup_repo(tmp_path)
+
+ manifest = repo / ".specify" / "presets" / "wrap-pack" / "preset.yml"
+ manifest.write_text(
+ "metadata: &m\n self: *m\n" + manifest.read_text(encoding="utf-8"),
+ encoding="utf-8",
+ )
+
+ no_yaml_exe = make_yaml_less_venv(tmp_path / "no-yaml-venv")
+
+ py_script = repo / ".specify" / "scripts" / "python" / "resolve_template.py"
+ env = clean_env()
+ env["SPECKIT_PYTHON"] = sys.executable
+
+ result = run([str(no_yaml_exe), str(py_script), TEMPLATE, "--json"], repo, env)
+
+ assert result.returncode == 0, result.stderr
+ assert json_stdout(result) == {
+ "TEMPLATE_NAME": TEMPLATE,
+ "TEMPLATE_CONTENT": expected,
+ }
+
+
+@requires_bash
+def test_python_variant_delegates_manifest_with_shared_non_recursive_alias(
+ tmp_path: Path,
+) -> None:
+ """A YAML alias shared between two locations (not a self-reference) must
+ not be treated as a cycle: marking a container as seen for the rest of
+ the document -- rather than only while its own subtree is being walked
+ -- makes a second, unrelated reference to the same anchor look like a
+ recursive structure, so delegation replaces `provides.templates` with
+ the non-native marker even though `yaml.safe_load` resolves it to the
+ same plain list the in-process parser accepts (#4445)."""
+ repo, expected = _setup_repo(tmp_path)
+
+ manifest = repo / ".specify" / "presets" / "wrap-pack" / "preset.yml"
+ manifest.write_text(
+ "metadata:\n"
+ " shared_templates: &shared_templates\n"
+ " - type: template\n"
+ f" name: {TEMPLATE}\n"
+ f" file: templates/{TEMPLATE}.md\n"
+ " strategy: wrap\n"
+ "provides:\n"
+ " templates: *shared_templates\n",
+ encoding="utf-8",
+ )
+
+ no_yaml_exe = make_yaml_less_venv(tmp_path / "no-yaml-venv")
+
+ py_script = repo / ".specify" / "scripts" / "python" / "resolve_template.py"
+ env = clean_env()
+ env["SPECKIT_PYTHON"] = sys.executable
+
+ result = run([str(no_yaml_exe), str(py_script), TEMPLATE, "--json"], repo, env)
+
+ assert result.returncode == 0, result.stderr
+ assert json_stdout(result) == {
+ "TEMPLATE_NAME": TEMPLATE,
+ "TEMPLATE_CONTENT": expected,
+ }
+
+
+@requires_bash
+def test_python_variant_delegates_manifest_with_exponential_alias_dag(
+ tmp_path: Path,
+) -> None:
+ """An ignored `metadata` value built from nested, non-recursive YAML
+ aliases (a DAG, not a cycle) must not make delegation blow up:
+ normalizing every occurrence of a shared reference independently turns
+ a document with O(depth) YAML nodes into an O(2**depth) JSON payload,
+ even though cycle detection alone lets it terminate. Restricting what
+ the child serializes to the `provides.templates` fields resolution
+ actually needs avoids expanding unused aliases like this one at all
+ (#4445)."""
+ repo, expected = _setup_repo(tmp_path)
+
+ depth = 20
+ lines = ["x0: &x0 [a]"]
+ for i in range(1, depth):
+ lines.append(f"x{i}: &x{i} [*x{i - 1}, *x{i - 1}]")
+ lines.append(f"metadata: *x{depth - 1}")
+
+ manifest = repo / ".specify" / "presets" / "wrap-pack" / "preset.yml"
+ manifest.write_text(
+ "\n".join(lines) + "\n" + manifest.read_text(encoding="utf-8"),
+ encoding="utf-8",
+ )
+
+ no_yaml_exe = make_yaml_less_venv(tmp_path / "no-yaml-venv")
+
+ py_script = repo / ".specify" / "scripts" / "python" / "resolve_template.py"
+ env = clean_env()
+ env["SPECKIT_PYTHON"] = sys.executable
+
+ start = time.monotonic()
+ result = run([str(no_yaml_exe), str(py_script), TEMPLATE, "--json"], repo, env)
+ elapsed = time.monotonic() - start
+
+ assert result.returncode == 0, result.stderr
+ assert json_stdout(result) == {
+ "TEMPLATE_NAME": TEMPLATE,
+ "TEMPLATE_CONTENT": expected,
+ }
+ assert elapsed < 5, f"delegated parsing took {elapsed:.2f}s; expected well under the 10s child timeout"
+
+
+@requires_bash
+def test_python_variant_delegates_manifest_with_exponential_alias_dag_in_entry(
+ tmp_path: Path,
+) -> None:
+ """An ignored per-entry field (e.g. `description`) built from nested,
+ non-recursive YAML aliases must not make delegation blow up either:
+ pruning unused top-level manifest fields alone still leaves every other
+ field of a `provides.templates` entry in place, so a DAG placed there
+ instead of in top-level `metadata` still turns into an O(2**depth) JSON
+ payload during normalization (#4445)."""
+ repo, expected = _setup_repo(tmp_path)
+
+ depth = 24
+ lines = ["x0: &x0 [a]"]
+ for i in range(1, depth):
+ lines.append(f"x{i}: &x{i} [*x{i - 1}, *x{i - 1}]")
+
+ manifest = repo / ".specify" / "presets" / "wrap-pack" / "preset.yml"
+ manifest.write_text(
+ "\n".join(lines) + "\n"
+ "provides:\n"
+ " templates:\n"
+ " - type: template\n"
+ f" name: {TEMPLATE}\n"
+ f" file: templates/{TEMPLATE}.md\n"
+ " strategy: wrap\n"
+ f" description: *x{depth - 1}\n",
+ encoding="utf-8",
+ )
+
+ no_yaml_exe = make_yaml_less_venv(tmp_path / "no-yaml-venv")
+
+ py_script = repo / ".specify" / "scripts" / "python" / "resolve_template.py"
+ env = clean_env()
+ env["SPECKIT_PYTHON"] = sys.executable
+
+ start = time.monotonic()
+ result = run([str(no_yaml_exe), str(py_script), TEMPLATE, "--json"], repo, env)
+ elapsed = time.monotonic() - start
+
+ assert result.returncode == 0, result.stderr
+ assert json_stdout(result) == {
+ "TEMPLATE_NAME": TEMPLATE,
+ "TEMPLATE_CONTENT": expected,
+ }
+ assert elapsed < 5, f"delegated parsing took {elapsed:.2f}s; expected well under the 10s child timeout"
+
+
+@requires_bash
+def test_python_variant_rejects_malformed_templates_container_with_exponential_alias_dag(
+ tmp_path: Path,
+) -> None:
+ """A malformed `provides.templates` value (not a list) must be rejected
+ immediately, even when it's built from nested, non-recursive YAML
+ aliases: the in-process parser already fails on the isinstance check
+ without inspecting the value's contents, so delegation must replace it
+ with the non-native marker up front instead of copying it through
+ `_stringify_keys`, which would otherwise turn an O(depth) aliased DAG
+ into an O(2**depth) JSON payload before the check ever runs (#4445)."""
+ repo, _ = _setup_repo(tmp_path)
+
+ depth = 24
+ lines = ["x0: &x0 [a]"]
+ for i in range(1, depth):
+ lines.append(f"x{i}: &x{i} [*x{i - 1}, *x{i - 1}]")
+
+ manifest = repo / ".specify" / "presets" / "wrap-pack" / "preset.yml"
+ manifest.write_text(
+ "\n".join(lines) + "\n"
+ "provides:\n"
+ f" templates: *x{depth - 1}\n",
+ encoding="utf-8",
+ )
+
+ no_yaml_exe = make_yaml_less_venv(tmp_path / "no-yaml-venv")
+
+ py_script = repo / ".specify" / "scripts" / "python" / "resolve_template.py"
+ env = clean_env()
+ env["SPECKIT_PYTHON"] = sys.executable
+
+ start = time.monotonic()
+ result = run([str(no_yaml_exe), str(py_script), TEMPLATE, "--json"], repo, env)
+ elapsed = time.monotonic() - start
+
+ assert result.returncode != 0
+ assert result.stdout == ""
+ assert elapsed < 5, f"delegated parsing took {elapsed:.2f}s; expected well under the 10s child timeout"
+
+
+@requires_bash
+def test_python_variant_rejects_malformed_template_entry_field_with_exponential_alias_dag(
+ tmp_path: Path,
+) -> None:
+ """A `provides.templates` entry field that fails the "must be a string"
+ check must be rejected immediately even when it's built from nested,
+ non-recursive YAML aliases: `_only_entry_fields` used to copy a
+ wrong-typed field value through unchanged, so `_stringify_keys` still
+ expanded the aliased DAG into an exponential JSON payload before the
+ later isinstance check could reject it (#4445)."""
+ repo, _ = _setup_repo(tmp_path)
+
+ depth = 24
+ lines = ["x0: &x0 [a]"]
+ for i in range(1, depth):
+ lines.append(f"x{i}: &x{i} [*x{i - 1}, *x{i - 1}]")
+
+ manifest = repo / ".specify" / "presets" / "wrap-pack" / "preset.yml"
+ manifest.write_text(
+ "\n".join(lines) + "\n"
+ "provides:\n"
+ " templates:\n"
+ " - type: template\n"
+ f" name: {TEMPLATE}\n"
+ f" file: *x{depth - 1}\n",
+ encoding="utf-8",
+ )
+
+ no_yaml_exe = make_yaml_less_venv(tmp_path / "no-yaml-venv")
+
+ py_script = repo / ".specify" / "scripts" / "python" / "resolve_template.py"
+ env = clean_env()
+ env["SPECKIT_PYTHON"] = sys.executable
+
+ start = time.monotonic()
+ result = run([str(no_yaml_exe), str(py_script), TEMPLATE, "--json"], repo, env)
+ elapsed = time.monotonic() - start
+
+ assert result.returncode != 0
+ assert result.stdout == ""
+ assert elapsed < 5, f"delegated parsing took {elapsed:.2f}s; expected well under the 10s child timeout"
+
+
+def test_python_variant_rejects_speckit_python_override_without_python_3(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """A `SPECKIT_PYTHON` override that can `import yaml` but is not a
+ Python 3 interpreter (e.g. Python 2 with PyYAML installed) must not be
+ accepted: probing only `import yaml` lets it through, and the later
+ delegated subprocess then fails with syntax/runtime errors instead of
+ falling back to a working interpreter (#4445)."""
+ monkeypatch.setitem(sys.modules, "yaml", None)
+ monkeypatch.setenv("SPECKIT_PYTHON", "/fake/python2")
+
+ def fake_run(cmd: list[str], **kwargs: object) -> subprocess.CompletedProcess:
+ code = cmd[2]
+ returncode = 1 if "version_info" in code else 0
+ return subprocess.CompletedProcess(cmd, returncode)
+
+ monkeypatch.setattr(python_common.subprocess, "run", fake_run)
+
+ assert python_common._import_yaml() is None
+
+
+def test_python_variant_prefers_speckit_python_executable_over_deprecated_alias(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """`SPECKIT_PYTHON_EXECUTABLE` is the canonical override; the deprecated
+ `SPECKIT_PYTHON` alias must only be consulted when it is unset (#4445)."""
+ monkeypatch.setitem(sys.modules, "yaml", None)
+ monkeypatch.setenv("SPECKIT_PYTHON_EXECUTABLE", "/canonical/python3")
+ monkeypatch.setenv("SPECKIT_PYTHON", "/deprecated/python3")
+
+ def fake_run(cmd: list[str], **kwargs: object) -> subprocess.CompletedProcess:
+ return subprocess.CompletedProcess(cmd, 0)
+
+ monkeypatch.setattr(python_common.subprocess, "run", fake_run)
+
+ delegate = python_common._import_yaml()
+
+ assert isinstance(delegate, python_common._DelegatedYAML)
+ assert delegate._python_exe == "/canonical/python3"
+
+
+def test_python_variant_skips_yaml_probe_for_manifest_less_preset(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """A preset with no preset.yml only needs the conventional template
+ fallback; importing/probing PyYAML for it (which can spawn a
+ SPECKIT_PYTHON child process) is unnecessary per-preset overhead that
+ `resolve_template_content` would otherwise pay for every manifest-less
+ preset (#4445)."""
+ preset_dir = tmp_path / "preset"
+ (preset_dir / "templates").mkdir(parents=True)
+ conventional = preset_dir / "templates" / f"{TEMPLATE}.md"
+ conventional.write_text("# Preset\n", encoding="utf-8")
+
+ def fail_if_called() -> object:
+ raise AssertionError("_import_yaml should not be called without a manifest")
+
+ monkeypatch.setattr(python_common, "_import_yaml", fail_if_called)
+
+ assert python_common._preset_template_layer(preset_dir, TEMPLATE) == (
+ conventional,
+ "replace",
+ )
+
+
+@requires_bash
+def test_python_variant_reports_concise_error_for_malformed_delegated_manifest(
+ tmp_path: Path,
+) -> None:
+ """A syntactically invalid manifest parsed via delegation must fail with
+ a concise message, matching the in-process parser, instead of leaking
+ the child interpreter's raw Python traceback into the user-facing
+ error (#4445)."""
+ repo, _ = _setup_repo(tmp_path)
+
+ manifest = repo / ".specify" / "presets" / "wrap-pack" / "preset.yml"
+ manifest.write_text("provides: [\n", encoding="utf-8")
+
+ no_yaml_exe = make_yaml_less_venv(tmp_path / "no-yaml-venv")
+
+ py_script = repo / ".specify" / "scripts" / "python" / "resolve_template.py"
+ env = clean_env()
+ env["SPECKIT_PYTHON"] = sys.executable
+
+ result = run([str(no_yaml_exe), str(py_script), TEMPLATE, "--json"], repo, env)
+
+ assert result.returncode != 0
+ assert result.stdout == ""
+ assert "Traceback" not in result.stderr
+
+
+@requires_bash
+def test_bash_resolves_composed_template_without_bash4_mapfile_builtin(
+ tmp_path: Path,
+) -> None:
+ """`resolve_template_content` must not rely on `mapfile`, a Bash 4+
+ builtin unavailable on macOS's system Bash 3.2 (#4445). Disabling the
+ builtin for this process reproduces that environment without requiring
+ an actual Bash 3.2 install."""
+ repo, expected = _setup_repo(tmp_path)
+
+ script = repo / ".specify" / "scripts" / "bash" / f"{SCRIPT}.sh"
+ result = run(
+ ["bash", "-c", 'enable -n mapfile; source "$0" "$@"', str(script), TEMPLATE, "--json"],
+ repo,
+ )
+
+ assert result.returncode == 0, result.stderr
+ assert json_stdout(result) == {
+ "TEMPLATE_NAME": TEMPLATE,
+ "TEMPLATE_CONTENT": expected,
+ }
+
+
@requires_bash
def test_bash_fails_when_override_read_fails(tmp_path: Path) -> None:
repo = make_repo(tmp_path)