feat(exec): add interpreter field with python support

[jahvon]

Part 1/5 of a stack adding Python execution to flow. Base: main.

Summary

flow could not run Python. exec.cmd is always parsed by the in-process mvdan.cc/sh POSIX interpreter, and exec.file only dispatched .sh / .bat / .cmd / .ps1 — a .py file was parsed as shell and failed.

This adds an interpreter field to the exec type, and teaches exec.file to dispatch .py by extension.

executables:
  - verb: run
    name: report
    exec:
      interpreter: python
      cmd: |
        import json, sys
        print(json.dumps({"python": sys.version_info[:2]}))

A .py file needs no interpreter at all — the extension implies it. Setting it explicitly overrides the extension.

Notable Changes

• interpreter is a pointer. go-jsonschema runs with --only-models, so it emits plain structs with no UnmarshalJSON: neither the schema default nor its enum is ever applied in Go. Unset therefore stays distinguishable from an explicit sh (an unset interpreter is what lets a file extension decide), and the enum is re-checked in Executable.Validate the way ExecContainer.Validate re-checks its runtime.
• Interpreter resolution prefers a project virtualenv, so a script gets the dependencies its repo installed: FLOW_PYTHON_BIN → $VIRTUAL_ENV → <workspace>/.venv → python3/python on PATH. The workspace root arrives via FLOW_WORKSPACE_PATH, already in the resolved env, so no run signature had to widen. An override that does not resolve fails rather than silently falling back.
• Windows prefers python over python3, because python3.exe there is usually the Microsoft Store alias stub that prints an ad and exits non-zero.
• Inline code runs from a 0600 temp file, not python -c — keeps user code out of the process table and preserves traceback line numbers.
• Sets PYTHONUNBUFFERED (flow pipes stdout to a log writer, and CPython block-buffers to a pipe, so a long run would otherwise look hung) and PYTHONDONTWRITEBYTECODE (keeps __pycache__ out of workspaces). Both overridable.

Testing

• Unit tests for resolution order, env defaults, temp-script handling, the type helpers, and runner routing.
• tests/python_exec_e2e_test.go covers real execution, params through the environment, traceback line numbers, .py extension inference, and the not-found error.
• CI pins an interpreter with actions/setup-python and adds a cross-platform test python-script job that runs a real .py through the built binary, asserting the env contract — so a resolution regression fails CI rather than silently degrading to shell.
• flow validate passes (generate → lint → unit + e2e → schema validation), and generate produces no diff.

🤖 Generated with Claude Code

https://claude.ai/code/session_01R328pa3FUUfga4gYah1iQi

[codecov]

Codecov Report

❌ Patch coverage is 73.91304% with 36 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/services/run/python.go	72.52%	16 Missing and 9 partials ⚠️
types/executable/executable.go	33.33%	2 Missing and 2 partials ⚠️
pkg/errors/errors.go	70.00%	2 Missing and 1 partial ⚠️
internal/services/run/run.go	0.00%	2 Missing ⚠️
types/executable/interpreter.go	90.90%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!