π« Toolkit to help you get started with SDD or any other process!
feat(cli): add `py` script type & Python interpreter resolution (#3278) (#3285)
Manfred Riembbe86310cafc
diff --git a/src/specify_cli/_agent_config.py b/src/specify_cli/_agent_config.pyindex 6e3a9e689..3befc1964 100644--- a/src/specify_cli/_agent_config.py+++ b/src/specify_cli/_agent_config.py@@ -17,4 +17,8 @@ AGENT_CONFIG: dict[str, dict[str, Any]] = _build_agent_config()DEFAULT_INIT_INTEGRATION = "copilot"-SCRIPT_TYPE_CHOICES: dict[str, str] = {"sh": "POSIX Shell (bash/zsh)", "ps": "PowerShell"}+SCRIPT_TYPE_CHOICES: dict[str, str] = {+ "sh": "POSIX Shell (bash/zsh)",+ "ps": "PowerShell",+ "py": "Python",+}diff --git a/src/specify_cli/integrations/base.py b/src/specify_cli/integrations/base.pyindex c820fd4ee..d5ebce78e 100644--- a/src/specify_cli/integrations/base.py+++ b/src/specify_cli/integrations/base.py@@ -17,6 +17,7 @@ import osimport reimport shleximport shutil+import sysfrom abc import ABCfrom dataclasses import dataclassfrom pathlib import Path@@ -495,8 +496,8 @@ class IntegrationBase(ABC):Copies files from this integration's ``scripts/`` directory to``.specify/integrations/<key>/scripts/`` in the project. Shell- scripts are made executable. All copied files are recorded in- *manifest*.+ (``.sh``) and Python (``.py``) scripts are made executable. All+ copied files are recorded in *manifest*.Returns the list of files created."""@@ -513,7 +514,7 @@ class IntegrationBase(ABC):continuedst_script = scripts_dest / src_script.nameshutil.copy2(src_script, dst_script)- if dst_script.suffix == ".sh":+ if dst_script.suffix in (".sh", ".py"):dst_script.chmod(dst_script.stat().st_mode | 0o111)self.record_file_in_manifest(dst_script, project_root, manifest)created.append(dst_script)@@ -538,6 +539,47 @@ class IntegrationBase(ABC):content,)+ @staticmethod+ def resolve_python_interpreter(project_root: Path | None = None) -> str:+ """Resolve a portable Python interpreter command for ``{SCRIPT}``.++ Used to build the invocation string for the ``py`` script type so+ that ``.py`` workflow scripts run consistently across platforms+ (notably Windows, where ``.py`` files are not directly executable).++ Resolution order:++ 1. A project virtual environment (``.venv``) interpreter, if one+ exists under *project_root* (POSIX ``bin/python`` or Windows+ ``Scripts/python.exe``). The returned path is **relative to the+ project root** (e.g. ``.venv/bin/python``) so generated+ ``{SCRIPT}`` invocations stay portable and runnable from the+ repo root regardless of where the project lives.+ 2. ``python3`` on ``PATH``.+ 3. ``python`` on ``PATH``.++ Falls back to the running interpreter (``sys.executable``) when+ ``PATH`` resolution fails so the generated command is guaranteed+ to work in the current environment, and finally to ``"python3"``+ if even that is unavailable.+ """+ if project_root is not None:+ # (existence check path, repo-root-relative invocation string)+ venv_candidates = (+ (project_root / ".venv" / "bin" / "python", ".venv/bin/python"),+ (+ project_root / ".venv" / "Scripts" / "python.exe",+ ".venv/Scripts/python.exe",+ ),+ )+ for candidate, relative in venv_candidates:+ if candidate.exists():+ return relative+ for name in ("python3", "python"):+ if shutil.which(name):+ return name+ return sys.executable or "python3"+@staticmethoddef process_template(content: str,@@ -545,6 +587,7 @@ class IntegrationBase(ABC):script_type: str,arg_placeholder: str = "$ARGUMENTS",invoke_separator: str = ".",+ project_root: Path | None = None,) -> str:"""Process a raw command template into agent-ready content.@@ -578,6 +621,17 @@ class IntegrationBase(ABC):# 2. Replace {SCRIPT}if script_command:+ # For the Python script type, prefix the resolved interpreter so+ # the command is portable (``.py`` files are not directly+ # executable on Windows).+ if script_type == "py":+ interpreter = IntegrationBase.resolve_python_interpreter(project_root)+ # Quote the interpreter if it contains whitespace (e.g. an+ # absolute ``sys.executable`` path under Windows+ # ``Program Files``) so it isn't split into multiple args.+ if any(ch.isspace() for ch in interpreter):+ interpreter = f'"{interpreter}"'+ script_command = f"{interpreter} {script_command}"content = content.replace("{SCRIPT}", script_command)# 3. Strip scripts: section from frontmatter@@ -784,6 +838,7 @@ class MarkdownIntegration(IntegrationBase):raw = src_file.read_text(encoding="utf-8")processed = self.process_template(raw, self.key, script_type, arg_placeholder,+ project_root=project_root,)dst_name = self.command_filename(src_file.stem)dst_file = self.write_file_and_record(@@ -986,6 +1041,7 @@ class TomlIntegration(IntegrationBase):description = self._extract_description(raw)processed = self.process_template(raw, self.key, script_type, arg_placeholder,+ project_root=project_root,)_, body = self._split_frontmatter(processed)toml_content = self._render_toml(description, body)@@ -1186,6 +1242,7 @@ class YamlIntegration(IntegrationBase):processed = self.process_template(raw, self.key, script_type, arg_placeholder,+ project_root=project_root,)_, body = self._split_frontmatter(processed)yaml_content = self._render_yaml(@@ -1381,6 +1438,7 @@ class SkillsIntegration(IntegrationBase):# Process body through the standard template pipelineprocessed_body = self.process_template(raw, self.key, script_type, arg_placeholder,+ project_root=project_root,invoke_separator=self.invoke_separator,)# Strip the processed frontmatter β we rebuild it for skills.diff --git a/src/specify_cli/integrations/copilot/__init__.py b/src/specify_cli/integrations/copilot/__init__.pyindex 747b7e9ca..44bd47f35 100644--- a/src/specify_cli/integrations/copilot/__init__.py+++ b/src/specify_cli/integrations/copilot/__init__.py@@ -370,6 +370,7 @@ class CopilotIntegration(IntegrationBase):raw = src_file.read_text(encoding="utf-8")processed = self.process_template(raw, self.key, script_type, arg_placeholder,+ project_root=project_root,)dst_name = self.command_filename(src_file.stem)dst_file = self.write_file_and_record(diff --git a/src/specify_cli/integrations/forge/__init__.py b/src/specify_cli/integrations/forge/__init__.pyindex 8c21353fe..d0a8cc7ab 100644--- a/src/specify_cli/integrations/forge/__init__.py+++ b/src/specify_cli/integrations/forge/__init__.py@@ -134,6 +134,7 @@ class ForgeIntegration(MarkdownIntegration):processed = self.process_template(raw, self.key, script_type, arg_placeholder,invoke_separator=self.invoke_separator,+ project_root=project_root,)# FORGE-SPECIFIC: Ensure any remaining $ARGUMENTS placeholders arediff --git a/src/specify_cli/integrations/generic/__init__.py b/src/specify_cli/integrations/generic/__init__.pyindex d87427355..a2fd430f7 100644--- a/src/specify_cli/integrations/generic/__init__.py+++ b/src/specify_cli/integrations/generic/__init__.py@@ -123,6 +123,7 @@ class GenericIntegration(MarkdownIntegration):raw = src_file.read_text(encoding="utf-8")processed = self.process_template(raw, self.key, script_type, arg_placeholder,+ project_root=project_root,)dst_name = self.command_filename(src_file.stem)dst_file = self.write_file_and_record(diff --git a/src/specify_cli/integrations/hermes/__init__.py b/src/specify_cli/integrations/hermes/__init__.pyindex e094dcfcf..f4bc43be6 100644--- a/src/specify_cli/integrations/hermes/__init__.py+++ b/src/specify_cli/integrations/hermes/__init__.py@@ -140,6 +140,7 @@ class HermesIntegration(SkillsIntegration):script_type,arg_placeholder,invoke_separator=self.invoke_separator,+ project_root=project_root,)# Strip the processed frontmatter β we rebuild it for skills.if processed_body.startswith("---"):diff --git a/tests/integrations/test_base.py b/tests/integrations/test_base.pyindex 9ec7d236c..fe531e624 100644--- a/tests/integrations/test_base.py+++ b/tests/integrations/test_base.py@@ -1,5 +1,7 @@"""Tests for IntegrationOption, IntegrationBase, MarkdownIntegration, and primitives."""+import sys+import pytestfrom specify_cli.integrations.base import (@@ -299,3 +301,186 @@ class TestResolveCommandRefs:text = "__SPECKIT_COMMAND_V2_PLAN__"result = IntegrationBase.resolve_command_refs(text, ".")assert result == "/speckit.v2.plan"+++class TestResolvePythonInterpreter:+ def test_returns_python_on_path(self, monkeypatch):+ # Positive: when python3 is on PATH it is preferred over python.+ def fake_which(name):+ return f"/usr/bin/{name}" if name in ("python3", "python") else None++ monkeypatch.setattr(+ "specify_cli.integrations.base.shutil.which", fake_which+ )+ assert IntegrationBase.resolve_python_interpreter() == "python3"++ def test_falls_back_to_python_when_no_python3(self, monkeypatch):+ def fake_which(name):+ return "/usr/bin/python" if name == "python" else None++ monkeypatch.setattr(+ "specify_cli.integrations.base.shutil.which", fake_which+ )+ assert IntegrationBase.resolve_python_interpreter() == "python"++ def test_falls_back_to_sys_executable_when_nothing_found(self, monkeypatch):+ # Negative: nothing on PATH and no venv -> the running interpreter+ # (sys.executable) is used so the command works in this environment.+ monkeypatch.setattr(+ "specify_cli.integrations.base.shutil.which", lambda name: None+ )+ monkeypatch.setattr(+ "specify_cli.integrations.base.sys.executable", "/opt/py/bin/python"+ )+ assert IntegrationBase.resolve_python_interpreter() == "/opt/py/bin/python"++ def test_falls_back_to_python3_when_no_interpreter_at_all(self, monkeypatch):+ # Negative edge: neither PATH nor sys.executable resolves.+ monkeypatch.setattr(+ "specify_cli.integrations.base.shutil.which", lambda name: None+ )+ monkeypatch.setattr(+ "specify_cli.integrations.base.sys.executable", ""+ )+ assert IntegrationBase.resolve_python_interpreter() == "python3"++ def test_prefers_project_venv_posix(self, monkeypatch, tmp_path):+ venv_python = tmp_path / ".venv" / "bin" / "python"+ venv_python.parent.mkdir(parents=True)+ venv_python.write_text("")+ # Even if python3 is on PATH, the project venv wins. The returned+ # path is relative to the project root for portability.+ monkeypatch.setattr(+ "specify_cli.integrations.base.shutil.which",+ lambda name: "/usr/bin/python3",+ )+ result = IntegrationBase.resolve_python_interpreter(tmp_path)+ assert result == ".venv/bin/python"++ def test_prefers_project_venv_windows(self, monkeypatch, tmp_path):+ venv_python = tmp_path / ".venv" / "Scripts" / "python.exe"+ venv_python.parent.mkdir(parents=True)+ venv_python.write_text("")+ monkeypatch.setattr(+ "specify_cli.integrations.base.shutil.which", lambda name: None+ )+ result = IntegrationBase.resolve_python_interpreter(tmp_path)+ assert result == ".venv/Scripts/python.exe"++ def test_ignores_missing_venv(self, monkeypatch, tmp_path):+ # Negative: no venv directory -> PATH resolution is used instead.+ monkeypatch.setattr(+ "specify_cli.integrations.base.shutil.which",+ lambda name: "/usr/bin/python3" if name == "python3" else None,+ )+ assert IntegrationBase.resolve_python_interpreter(tmp_path) == "python3"+++class TestProcessTemplatePyScriptType:+ CONTENT = (+ "---\n"+ "scripts:\n"+ " sh: scripts/bash/check-prerequisites.sh --json\n"+ " ps: scripts/powershell/check-prerequisites.ps1 -Json\n"+ " py: scripts/python/check-prerequisites.py --json\n"+ "---\n"+ "Run {SCRIPT} now."+ )++ def test_py_prefixes_interpreter(self, monkeypatch):+ # Positive: py script type prefixes a resolved interpreter and the+ # script path is rewritten to the .specify location.+ monkeypatch.setattr(+ "specify_cli.integrations.base.shutil.which",+ lambda name: "/usr/bin/python3" if name == "python3" else None,+ )+ result = IntegrationBase.process_template(self.CONTENT, "agent", "py")+ assert "python3 .specify/scripts/python/check-prerequisites.py --json" in result+ # The scripts: frontmatter block is stripped.+ assert "scripts:" not in result++ def test_sh_does_not_prefix_interpreter(self):+ # Negative: non-py script types are never prefixed with an interpreter.+ result = IntegrationBase.process_template(self.CONTENT, "agent", "sh")+ assert ".specify/scripts/bash/check-prerequisites.sh --json" in result+ assert "python" not in result++ def test_py_quotes_interpreter_with_spaces(self, monkeypatch):+ # An interpreter path containing whitespace (e.g. Windows+ # ``Program Files``) must be quoted so it isn't split into args.+ monkeypatch.setattr(+ "specify_cli.integrations.base.shutil.which", lambda name: None+ )+ monkeypatch.setattr(+ "specify_cli.integrations.base.sys.executable",+ r"C:\Program Files\Python\python.exe",+ )+ result = IntegrationBase.process_template(self.CONTENT, "agent", "py")+ assert (+ '"C:\\Program Files\\Python\\python.exe" '+ ".specify/scripts/python/check-prerequisites.py --json"+ ) in result++ def test_py_does_not_quote_interpreter_without_spaces(self, monkeypatch):+ # Negative: a whitespace-free interpreter is left unquoted.+ monkeypatch.setattr(+ "specify_cli.integrations.base.shutil.which",+ lambda name: "/usr/bin/python3" if name == "python3" else None,+ )+ result = IntegrationBase.process_template(self.CONTENT, "agent", "py")+ assert '"' not in result.split("check-prerequisites.py")[0]++ def test_py_uses_project_venv(self, monkeypatch, tmp_path):+ venv_python = tmp_path / ".venv" / "bin" / "python"+ venv_python.parent.mkdir(parents=True)+ venv_python.write_text("")+ result = IntegrationBase.process_template(+ self.CONTENT, "agent", "py", project_root=tmp_path+ )+ assert ".venv/bin/python .specify/scripts/python/check-prerequisites.py" in result+++class TestInstallScriptsPython:+ def _make_integration_with_scripts(self, monkeypatch, tmp_path):+ scripts_src = tmp_path / "bundled_scripts"+ scripts_src.mkdir()+ (scripts_src / "common.py").write_text("print('hi')\n")+ (scripts_src / "common.sh").write_text("echo hi\n")+ (scripts_src / "notes.txt").write_text("not executable\n")+ integration = StubIntegration()+ monkeypatch.setattr(+ integration, "integration_scripts_dir", lambda: scripts_src+ )+ return integration++ def test_copies_all_script_files(self, monkeypatch, tmp_path):+ # Cross-platform: every bundled file is copied into the project.+ integration = self._make_integration_with_scripts(monkeypatch, tmp_path)+ project_root = tmp_path / "proj"+ project_root.mkdir()+ manifest = IntegrationManifest("stub", project_root.resolve())++ created = integration.install_scripts(project_root, manifest)+ names = {p.name for p in created}+ assert {"common.py", "common.sh", "notes.txt"} == names++ @pytest.mark.skipif(+ sys.platform == "win32", reason="chmod exec bit not reliable on Windows"+ )+ def test_marks_py_and_sh_executable(self, monkeypatch, tmp_path):+ integration = self._make_integration_with_scripts(monkeypatch, tmp_path)+ project_root = tmp_path / "proj"+ project_root.mkdir()+ manifest = IntegrationManifest("stub", project_root.resolve())++ integration.install_scripts(project_root, manifest)++ dest = project_root / ".specify" / "integrations" / "stub" / "scripts"+ py_file = dest / "common.py"+ sh_file = dest / "common.sh"+ txt_file = dest / "notes.txt"+ # Positive: .py and .sh are executable.+ assert py_file.stat().st_mode & 0o111+ assert sh_file.stat().st_mode & 0o111+ # Negative: a non-script file is not made executable.+ assert not (txt_file.stat().st_mode & 0o111)diff --git a/tests/test_commands_package.py b/tests/test_commands_package.pyindex e2252ffc1..b8cd262e8 100644--- a/tests/test_commands_package.py+++ b/tests/test_commands_package.py@@ -24,6 +24,20 @@ def test_agent_config_importable():assert "sh" in SCRIPT_TYPE_CHOICES+def test_script_type_choices_includes_python():+ from specify_cli._agent_config import SCRIPT_TYPE_CHOICES+ assert SCRIPT_TYPE_CHOICES.get("py") == "Python"+ # The three supported variants are sh, ps, and py.+ assert {"sh", "ps", "py"} <= set(SCRIPT_TYPE_CHOICES)+++def test_workflow_init_valid_script_types_includes_python():+ from specify_cli.workflows.steps.init import VALID_SCRIPT_TYPES+ assert "py" in VALID_SCRIPT_TYPES+ # Negative: an unknown variant is not accepted.+ assert "rb" not in VALID_SCRIPT_TYPES++def test_agent_config_re_exported_from_init():from specify_cli import AGENT_CONFIG, SCRIPT_TYPE_CHOICESassert isinstance(AGENT_CONFIG, dict)