[mnriem]

Description

Prevent automatic Docker executable discovery from selecting binaries in the current working directory or its descendants, including symlink targets.

Search qualified executable paths in absolute PATH entries, preserving Windows PATHEXT handling without Python 3.11's implicit current-directory search. Keep the detected absolute executable path for the Docker Agent version probe and runtime invocation. Explicit operator overrides remain supported.

Add regression coverage for current-directory lookup, relative and empty search entries, symlinks, installed executables, and probe failures. No documentation changes.

Testing

• Tested locally with uv run specify --help
• Ran existing tests with uv sync && uv run pytest
• Tested with a sample project (if applicable)

Used this worktree's own virtual environment for pytest, as documented in CONTRIBUTING.md:

• uv sync --extra test — passed.
• uv run specify --help — passed.
• .venv/bin/python -m pytest tests/test_utils.py tests/specify_cli/test_check_tool.py tests/integrations/test_integration_docker_agent.py tests/test_workflows.py -q --tb=short — 916 passed.
• LC_ALL=en_US.UTF-8 .venv/bin/python -m pytest tests -q — 13,680 passed, 130 skipped, 63 warnings.

Executed on macOS with Python 3.13. Windows lookup behavior is modeled in regression tests; native Windows execution was not run. Sample-project scaffolding is not applicable to this executable-discovery fix.

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (fill in the disclosure below)

AI disclosure: Authored on behalf of @mnriem by GitHub Copilot App using GPT-6.1 Sol (model ID: gpt-6.1-sol), autonomous agent mode; the reasoning-effort setting is not exposed in this session. AI assistance covered assessment, implementation, regression tests, automated test execution, and this PR description.

[Copilot]

🟡 Changes recommended

Dispatch can still resolve and execute a checkout-local docker-agent rejected by automatic discovery, bypassing the intended safety check.

3 open issues

• Stop dispatch after failed automatic Docker Agent discovery · New
• Normalize PATHEXT fixture suffixes in Docker discovery tests · New
• Create symlink fixtures only for symlink test cases · New

What changed in this PR

This PR hardens Specify CLI’s automatic Docker Agent discovery against executables in the current working directory or its descendants.

Changes:

• Search absolute PATH entries outside the working-directory tree, checking resolved symlink targets and preserving Windows extension handling.
• Reuse detected absolute paths for version probes and runtime arguments while retaining explicit overrides.
• Add discovery regression tests and update existing mocks and command expectations.

Review validation used an isolated dispatch check; the full suite and native Windows execution were not run.

AI-generated review for the requester by GitHub Copilot (model/settings unavailable; automated mode; analysis and feedback only).

File	Description
tests/​test_utils.py	Adds discovery regressions for PATH filtering, symlinks, Windows lookup, and probe failures.
tests/​specify_cli/​test_check_tool.py	Updates Docker Agent availability mocks to use the new resolver.
tests/​integrations/​test_integration_docker_agent.py	Updates resolver mocks and expects absolute executable paths.
src/​specify_cli/​_utils.py	Adds restricted executable discovery and preserves detected paths.

_{Review effort: Max (auto)}

[mnriem]

Pushed dd92e86. Docker Agent dispatch now fails explicitly when automatic discovery or the plugin probe fails, without restoring an unrestricted executable lookup; explicit executable overrides remain supported. Windows fixture suffixes are pinned through PATHEXT, and symlinks are created only where required, with unsupported cases skipped. Automated validation: LC_ALL=en_US.UTF-8 .venv/bin/python -m pytest tests -q -n 4 passed with 13,684 passed and 130 skipped; the focused discovery, integration, and workflow suite passed all 920 tests. With symlink creation disabled, the utility tests reported 16 passed and only the four symlink cases skipped. Native Windows execution was not run locally. This summary was authored on behalf of @mnriem by GitHub Copilot App using GPT-6.1 Sol (gpt-6.1-sol), autonomous agent mode; the reasoning-effort setting is not exposed. AI assistance covered implementation, regression tests, automated validation, and this comment.

[Copilot]

🟡 Changes recommended

Executable discovery can still run checkout-local Docker binaries, breaks Windows workflow tests, and allows missing-executable errors to bypass configured workflow error handling.

4 open issues

• Exclude the effective dispatch directory from Docker Agent discovery · New
• Update Windows Docker Agent mocks for qualified executable paths · New
• Stop dispatch after failed automatic Docker Agent discovery
• Return failed prompt results when Docker Agent discovery fails · New

2 previously missed issues

In code that hasn't changed since last review

Preserve standard executable extensions when PATHEXT is empty

src/​specify_cli/​_utils.py:31

With PATHEXT="", this creates no filenames, so installed docker-agent.exe and docker.exe are reported as unavailable. Preserve the standard-extension fallback used by shutil.which() for both unset and empty values, and add an empty-PATHEXT regression.

AI-generated review by GitHub Copilot for the requesting reviewer; reviewer identity and model/settings unavailable; autonomous analysis and comment editing.

Reject case-insensitive checkout-local Docker binaries

src/​specify_cli/​_utils.py:47

On case-insensitive macOS filesystems, a differently cased absolute PATH entry can still select a checkout-local Docker binary. resolve() preserves the spelling, so /Users/me/PROJECT/bin is not lexically under CWD /Users/me/project, and both containment guards allow it. Check the resolved executable's ancestors by filesystem identity before returning it, and add a mixed-case-path regression.

AI-generated review by GitHub Copilot for the requesting reviewer; reviewer identity and model/settings unavailable; autonomous analysis and comment editing.

2 resolved since last review

• Normalize PATHEXT fixture suffixes in Docker discovery tests
• Create symlink fixtures only for symlink test cases

_{Review effort: Max (auto)}

[mnriem]

Addressed this round in commit 2843fcb. Automatic Docker discovery excludes both the launch directory and the effective runtime project, including case-insensitive filesystem aliases and resolved symlink targets. Empty PATHEXT uses the standard extension fallback, and Docker workflow fixtures mock the restricted resolver independently of later executable lookups. Prompt discovery errors now return failed step results and honor continue_on_error, while adapter-integrity failures retain their fatal workflow-level handling. Automated validation on macOS: LC_ALL=en_US.UTF-8 .venv/bin/python -m pytest tests -q -n 4 passed with 13,702 passed and 130 skipped; the focused discovery, integration, and workflow suite passed all 938 tests; all 12 installed-adapter dispatch-context cases passed; uvx ruff@0.15.0 check src tests passed. Native Windows execution was not run locally. This summary was authored on behalf of @mnriem by GitHub Copilot App using GPT-6.1 Sol (gpt-6.1-sol), autonomous agent mode; the reasoning-effort setting is not exposed. AI assistance covered implementation, regression tests, automated validation, and this comment.

[Copilot]

🟡 Changes recommended

Docker discovery can abort on inaccessible or cyclic PATH entries, its new restrictions remain undocumented, and the shared prompt-handler change requires a separately justified prerequisite PR.

7 open issues

• Update Windows Docker Agent mocks for qualified executable paths
• Exclude the effective dispatch directory from Docker Agent discovery
• Stop dispatch after failed automatic Docker Agent discovery
• Skip inaccessible or cyclic PATH candidates during discovery · New
• Move shared prompt failure handling to prerequisite PR · New
• Return failed prompt results when Docker Agent discovery fails
• Document Docker discovery restrictions and executable override · New

_{Review effort: Max (auto)}

[mnriem]

Pushed d21cf2f. Inaccessible or cyclic Docker search candidates now produce a warning and are skipped so discovery can reach a later valid installation. Following @mnriem's scope decision, unavailable executable handling stays inside the Docker integration through its existing optional-argv contract; the shared prompt handler is restored exactly to its original state, so no prerequisite PR is needed. The existing failed-dispatch handling continues to respect continue_on_error, and adapter-integrity behavior is unchanged. Documentation remains unchanged at @mnriem's explicit direction. Automated validation on macOS: LC_ALL=en_US.UTF-8 .venv/bin/python -m pytest tests -q -n 4 passed with 13,734 passed and 130 skipped; all 970 focused tests and all 12 installed-adapter dispatch-context cases passed; uvx ruff@0.15.0 check src tests passed. Native Windows execution was not run locally. This summary was authored on behalf of @mnriem by GitHub Copilot App using GPT-6.1 Sol (gpt-6.1-sol), autonomous agent mode; the reasoning-effort setting is not exposed. AI assistance covered implementation, regression tests, automated validation, and this comment.

[Copilot]

🔵 Needs a closer look

Human assessment is needed because a moderate-severity concern about explicit Docker Agent executable overrides was omitted from the published review.

3 open issues

• Update Windows Docker Agent mocks for qualified executable paths
• Exclude the effective dispatch directory from Docker Agent discovery
• Stop dispatch after failed automatic Docker Agent discovery

4 resolved since last review

• Move shared prompt failure handling to prerequisite PR
• Skip inaccessible or cyclic PATH candidates during discovery
• Return failed prompt results when Docker Agent discovery fails
• Document Docker discovery restrictions and executable override

_{Review effort: Max (auto)}

[mnriem]

Pushed 7cb9c24. This review publishes no new inline finding and does not describe the omitted override concern, so I cannot confirm that the following fix addresses that exact concern. Independently, regression tests reproduced a concrete override bug: an explicit SPECKIT_INTEGRATION_DOCKER_AGENT_EXECUTABLE=docker-agent was treated as an unset override. Non-empty explicit overrides now retain operator intent even when they match the default integration key; unset, empty, and whitespace-only values still use restricted automatic discovery. Build-argument and dispatch regressions cover this distinction without relaxing automatic-discovery restrictions. Automated validation on macOS: LC_ALL=en_US.UTF-8 .venv/bin/python -m pytest tests -q -n 4 passed with 13,740 passed and 130 skipped; all 976 focused tests passed; uvx ruff@0.15.0 check src tests passed. Native Windows execution was not run locally. This summary was authored on behalf of @mnriem by GitHub Copilot App using GPT-6.1 Sol (gpt-6.1-sol), autonomous agent mode; the reasoning-effort setting is not exposed. AI assistance covered assessment, implementation, regression tests, automated validation, and this comment.

[Copilot]

🟡 Changes recommended

The Windows bare override test can reject a valid relative path returned by shutil.which because it compares absolute path strings instead of file identity.

4 open issues

• Accept valid relative shutil.which result on Windows · New
• Update Windows Docker Agent mocks for qualified executable paths
• Exclude the effective dispatch directory from Docker Agent discovery
• Stop dispatch after failed automatic Docker Agent discovery

_{Review effort: Max (auto)}