Skip to content

πŸ’« 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.py
index 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.py
index c820fd4ee..d5ebce78e 100644
--- a/src/specify_cli/integrations/base.py
+++ b/src/specify_cli/integrations/base.py
@@ -17,6 +17,7 @@ import os
import re
import shlex
import shutil
+import sys
from abc import ABC
from dataclasses import dataclass
from 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):
continue
dst_script = scripts_dest / src_script.name
shutil.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"
+
@staticmethod
def 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 pipeline
processed_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__.py
index 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__.py
index 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 are
diff --git a/src/specify_cli/integrations/generic/__init__.py b/src/specify_cli/integrations/generic/__init__.py
index 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__.py
index 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.py
index 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 pytest
from 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.py
index 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_CHOICES
assert isinstance(AGENT_CONFIG, dict)