Skip to content

fix(integrations): keep shared scripts executable when the default integration changes - #5425

Open
kartsan03 wants to merge 3 commits into
github:mainfrom
kartsan03:fix/keep-scripts-executable-on-default-change
Open

kartsan03 wants to merge 3 commits into
github:mainfrom
kartsan03:fix/keep-scripts-executable-on-default-change

Conversation

@kartsan03

@kartsan03 kartsan03 commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Description

After specify integration switch <key>, specify integration use <key>, or specify integration uninstall of the default integration (when another installed one takes over), every script in .specify/scripts/bash/ has mode 0644. The generated commands and skills tell the agent to run them directly (.specify/scripts/bash/setup-plan.sh --json in speckit-plan, and so on), so on macOS and Linux each of those steps now fails with Permission denied (exit 126).

All three commands go through _set_default_integration() in integrations/_helpers.py. It refreshes shared infrastructure with _install_shared_infra(..., refresh_managed=True), which writes the scripts with their packaged mode, 0644. init, integration install, integration upgrade and the first refresh in switch call ensure_executable_scripts() after they write the scripts. _set_default_integration() didn't. In switch the existing call (command_switch.py:293) runs before the final default refresh, and that refresh writes the scripts a second time.

This PR makes the refresh itself write the scripts executable. install_shared_infra() already passes a mode to _write_shared_bytes(); for a .sh file that starts with a shebang, that mode now gets an execute bit for each class that can read it (the rule ensure_executable_scripts() uses). The mode is set on the temp file before the atomic replace, so it goes through the same symlink checks and the same lifecycle journal as the content. Nothing outside the files the refresh writes is touched. On Windows the mode is unchanged.

The first version of this PR called ensure_executable_scripts() after the refresh instead. That scan follows a symlinked .specify/scripts and isn't journaled, so I dropped it here; the existing callers of the scan are unchanged.

Repro with the real CLI:

specify init --here --integration claude --script sh --ignore-agent-tools
specify integration switch codex
stat -c '%a %n' .specify/scripts/bash/*.sh
.specify/scripts/bash/check-prerequisites.sh --help
After main (2ee2b1e) This PR
integration switch codex scripts 0644, direct run exits 126 0755, exits 0
integration install codex --script sh, then integration use codex 0644, exits 126 0755, exits 0
integration install codex --script sh, then integration uninstall claude 0644, exits 126 0755, exits 0

Release 1.3.3 behaves the same for all three. #5377 added one more path: switch <current default> --refresh-shared-infra now refreshes too, so it also drops the bits.

With this change, the next use, switch or uninstall also fixes the unmodified shared scripts of a project that is already affected, because the refresh rewrites them. A script the user edited is preserved by the refresh, so it keeps its current mode; specify integration upgrade fixes those, as it does on main.

init, install and upgrade go through the same writer, so they now write the scripts executable too, before their own ensure_executable_scripts() call.

Testing

  • Tested locally with .venv/bin/specify --help
  • Ran relevant existing tests with .venv/bin/python -m pytest tests -q
  • Tested with a sample project (if applicable)

New CLI tests, one per command, in the files design/cli.md assigns them to. Each checks the scripts are executable before the command and still executable after it:

  • test_command_switch.py: TestIntegrationSwitch::test_switch_keeps_shared_scripts_executable, for a new target, an installed target, and the current default with --force and with --refresh-shared-infra
  • test_command_use.py: TestIntegrationUse::test_use_keeps_shared_scripts_executable, and test_use_changes_modes_only_on_scripts_it_writes: a user's 0644 shebang script next to the shared ones keeps its mode, also when .specify/scripts is a symlink to a directory outside the project
  • test_command_uninstall.py: TestIntegrationUninstall::test_uninstall_default_keeps_fallback_scripts_executable
  • tests/test_shared_infra_script_mode.py: the mode rule itself (0644 → 0755, 0640 → 0750; packaged mode kept without a shebang, for other suffixes and on Windows)
  • test_installed_adapters.py::test_failed_switch_restores_shared_script_mode_and_content: a switch away from an external adapter that fails after the refresh restores each script's mode and content

With shared_infra.py reverted to main, the 6 execute-bit cases fail, for example AssertionError: switch left shared scripts non-executable: ['check-prerequisites.sh', 'common.sh', 'create-new-feature.sh', 'resolve-template.sh', 'setup-plan.sh', 'setup-tasks.sh']. With the fix, all 8 cases pass. The two mode cases fail on this PR's first commit (the scan made the user's script 0755 in both). They are skipped on Windows, like #3723's test.

Full suite on Linux, Python 3.13: 16275 passed, 566 skipped, 1 failed (uv sync --extra test, then pytest -n 2, 9 min). The failure, test_version_execution.py::TestWindowsUvToolEnvironment::test_non_windows_uv_tool_dry_run_still_previews_installer, fails the same way on main here: Rich wraps the dry-run output, and my checkout's venv path is long enough to be split mid-path. Ruff 0.15.0 (ruff check src tests) passes. I haven't run it on Windows or macOS.

AI Disclosure

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

AI disclosure: Codex CLI (model: gpt-6.1-sol, reasoning effort xhigh, autonomous, offline sandbox) found the dropped execute bits while comparing release 1.3.3 and main on the same commands, and wrote a first patch. Claude Code (model: claude-opus-5-5, autonomous) traced every affected command to _set_default_integration(), rewrote the fix and the tests, reran the repro with the real CLI on main and the branch, ran the full suite and lint, and drafted this description. After the Copilot review of the first commit, Claude Code (model: claude-fable-5-2, autonomous) moved the execute bits into the refresh's own write, added the two mode cases, reran the repro and the full suite, and updated this description. Each commit carries its Assisted-by: trailers.

…tegration changes

`integration use`, every `integration switch` path, and `integration uninstall`
of the default integration refresh shared infrastructure through
`_set_default_integration()`. The refresh rewrites `.specify/scripts/bash/*.sh`
with the packaged mode (0644) and nothing restored the execute bits, so the
scripts that generated commands and skills run directly failed with
"Permission denied". Restore them after the refresh, as init, install and
upgrade already do.

Assisted-by: Codex (model: gpt-6.1-sol, autonomous)
Assisted-by: Claude Code (model: claude-opus-5-5, autonomous)
@kartsan03
kartsan03 requested a review from mnriem as a code owner November 13, 2026 15:38
Copilot AI adaptive review requested due to automatic review settings November 13, 2026 15:38

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Human confirmation is needed because the shared transition changes permissions across use, switch, uninstall, and rollback, with interactions involving lifecycle journaling, partial-refresh recovery, and POSIX/Windows behavior.

No open issues 🎉

What changed in this PR

This PR fixes a permissions regression where integration changes rewrote shared POSIX scripts without execute permissions, causing directly invoked generated commands to fail. It restores executable bits after default-integration refreshes and adds regression coverage.

Changes:

  • Restore execute permissions in _set_default_integration() after shared infrastructure refreshes.
  • Test integration switch, integration use, and default-integration fallback during integration uninstall.
  • Cover new, installed, and current-default switch paths, including refresh options.
File Description
tests/​specify_cli/​integrations/​test_command_use.py Verifies that integration use preserves executable permissions on shared scripts.
tests/​specify_cli/​integrations/​test_command_uninstall.py Verifies that fallback shared scripts remain executable after uninstalling the default integration.
tests/​specify_cli/​integrations/​test_command_switch.py Covers executable permissions across new, installed, and current-default integration switch paths.
src/​specify_cli/​integrations/​_helpers.py Restores executable permissions after default-integration shared infrastructure refreshes.

Review effort: Lite (dynamic)

@mnriem mnriem added the triage-must-have Verdict: high-value, important work for Spec Kit — do first label Nov 13, 2026
@mnriem
mnriem requested a max review from Copilot November 16, 2026 20:46

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The executable-script scan can change permissions outside the project through symlinked roots and bypass transaction journaling, leaving permission changes in place after rollback.

2 open issues

Review effort: Max

…n write

The previous commit restored execute bits with `ensure_executable_scripts()`
after the default-integration refresh. That scan follows a symlinked
`.specify/scripts` or `.specify/extensions` root and changes modes outside the
lifecycle journal, so a rollback could not undo it.

Give `.sh` files that start with a shebang their execute bits in the mode
`install_shared_infra()` already passes to `_write_shared_bytes()`. The mode is
applied to the temp file before the atomic replace, behind the same symlink
checks and journal calls as the content, and only files the refresh writes are
touched. Drop the scan from `_set_default_integration()`.

Assisted-by: Claude Code (model: claude-fable-5-2, autonomous)
Copilot AI max review requested due to automatic review settings November 16, 2026 21:06
@kartsan03

Copy link
Copy Markdown
Contributor Author

Both Copilot findings are addressed in 13ff151.

They came from the same thing: the first commit restored the bits with ensure_executable_scripts(), a scan that follows a symlinked .specify/scripts and runs outside the lifecycle journal. I removed that call from _set_default_integration(). The refresh now writes the scripts executable itself: install_shared_infra() already passes a mode to _write_shared_bytes(), and for a .sh file that starts with a shebang that mode now includes the execute bits. It is applied to the temp file before the atomic replace, so it sits behind the same symlink checks and the same before_file_change/after_file_change calls as the content, and only files the refresh writes change.

New test test_use_changes_modes_only_on_scripts_it_writes: a user's 0644 shebang script next to the shared ones keeps its mode after integration use, with a normal .specify/scripts and with one symlinked to a directory outside the project. Both cases fail on 89bea99 and pass now; the six execute-bit cases still fail with shared_infra.py from main and pass with the fix. Full suite: 16275 passed, 566 skipped, and the same path-length failure in test_version_execution.py that main has in my checkout. Ruff is clean.

One side effect: init, install and upgrade use the same writer, so they now write these scripts executable before their own ensure_executable_scripts() call. I left those callers and the scan itself alone. The description is updated.

Drafted on behalf of @kartsan03 by Claude Code (model: claude-fable-5-2, autonomous); it also wrote the change and ran the tests.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Test coverage is missing for permission-mode rules and exclusions, and for transactional rollback restoring a managed script’s original mode and content after a later failure.

2 open issues
2 resolved since last review

Review effort: Max

Comment on lines +329 to +330
if os.name != "nt" and src_path.suffix == ".sh" and content.startswith(b"#!"):
mode |= ((mode & 0o444) >> 2) | 0o100

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added in 3f7bdc0: tests/test_shared_infra_script_mode.py calls _shared_script_mode() with explicit source modes (0644 → 0755, 0640 → 0750, 0600 → 0700, 0755 unchanged) and checks the packaged mode is kept for a shebang-less .sh, an empty .sh, .ps1, .py, and for a .sh with os.name set to nt.

Drafted on behalf of @kartsan03 by Claude Code (model: claude-fable-5-2, autonomous); it also wrote the tests and ran them.

content.encode("utf-8"),
src_path.stat().st_mode & 0o777,
)
(dst_path, rel, data, _shared_script_mode(src_path, data))

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added in 3f7bdc0: test_failed_switch_restores_shared_script_mode_and_content in test_installed_adapters.py. With the external sample adapter installed, the managed bash scripts are set to 0644, integration switch copilot --script sh refreshes them, and installer.write_records then fails. The failing step asserts the scripts are 0755 at that point; after the rollback the project snapshot equals the one taken before and every script is 0644 again. With shared_infra.py from main the test fails at the 0755 assert.

Drafted on behalf of @kartsan03 by Claude Code (model: claude-fable-5-2, autonomous); it also wrote the tests and ran them.

Unit tests for `_shared_script_mode()`: an execute bit for each class that can
read a `.sh` file with a shebang, and the packaged mode for a shebang-less
`.sh`, other file types and Windows. A failed switch away from an external
adapter restores the mode and content of the scripts the refresh rewrote.

Assisted-by: Claude Code (model: claude-fable-5-2, autonomous)
Copilot AI max review requested due to automatic review settings November 17, 2026 01:28
@kartsan03

Copy link
Copy Markdown
Contributor Author

Both test requests from the last Copilot pass are covered in 3f7bdc0 (tests only, no source change).

  • tests/test_shared_infra_script_mode.py: the permission rule with explicit source modes, plus the cases that keep the packaged mode (no shebang, other suffixes, Windows).
  • test_installed_adapters.py::test_failed_switch_restores_shared_script_mode_and_content: a switch away from an external adapter that fails after the refresh restores each rewritten script's mode and content.

The three touched test files pass (716 tests) and ruff is clean. The full suite ran on 13ff151; I did not rerun it for this test-only commit.

Drafted on behalf of @kartsan03 by Claude Code (model: claude-fable-5-2, autonomous); it also wrote the tests and ran them.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The rollback test’s exact 0755 assertion rejects valid 0775 permissions from group-writable source scripts, causing it to fail before exercising the simulated commit error.

3 open issues

Review effort: Max

before = snapshot(project)

def fail_commit(*args, **kwargs):
assert all(stat.S_IMODE(script.stat().st_mode) == 0o755 for script in scripts)

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

triage-must-have Verdict: high-value, important work for Spec Kit — do first

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants