Skip to content

fix(extensions): write the extension registry atomically - #5482

Open
divya0795 wants to merge 1 commit into
github:mainfrom
divya0795:fix/extension-registry-atomic-save
Open

divya0795 wants to merge 1 commit into
github:mainfrom
divya0795:fix/extension-registry-atomic-save

Conversation

@divya0795

Copy link
Copy Markdown

Description

When a write of the extension registry (.specify/extensions/.registry) fails part-way, all installed extensions drop out of the registry.

Where: ExtensionRegistry._save() in src/specify_cli/extensions/__init__.py.

Root cause: _save() opened the registry with open(path, "w"), which truncates it immediately, and then streamed json.dump into it. If the write stopped part-way, the file was left holding a JSON prefix. That can come from a disk-full OSError, an interrupted process, or a metadata value json.dump cannot encode. _load() treats an unparseable registry as corrupt and starts from {"extensions": {}}, so every installed extension disappears from extension list. The extension directories and hooks stay on disk. The next successful save (any extension add/enable/disable/remove) then writes that empty registry for good.

Reproduction (tests/test_extensions.py::test_interrupted_save_keeps_previous_registry):

  1. Register first-ext.
  2. Make json.dump write the first 20 characters and raise OSError(28, "No space left on device") while adding second-ext.

On main (59d61c5) the registry file is left as {\n "schema_version", and a fresh ExtensionRegistry reports first-ext as not installed. A real TypeError mid-dump does the same: on main, registry.add("b", {"v": object()}) after add("a", …) leaves a registry that reloads without a.

The disk-full case is simulated in the test, not captured from a real full disk. The non-serializable case is a real, unmocked trigger, but I have no caller that passes such a value today. The concrete risk is a write that is interrupted or out of space.

Fix: write the JSON to a temp file in the same directory (tempfile.mkstemp), copy the existing registry's mode onto it (0o644 for a new file), and os.replace it over the registry. The finally block removes the temp file if anything fails. A failed save now leaves the previous registry byte-for-byte intact. This is the same temp-file + os.replace pattern the workflow package registry and shared_infra._write_shared_bytes already use. before_file_change/after_file_change are called as before.

Behavior differences I checked (main vs. this branch, Python 3.14, macOS):

Case main this branch
failed write (partial json.dump + OSError) registry truncated, reloads empty previous registry intact, no temp file left
non-serializable metadata (TypeError) registry truncated, reloads empty previous registry intact
existing registry mode 0640 kept kept
new registry 0644 0644
.registry is a directory IsADirectoryError IsADirectoryError
.registry is a symlink to a file writes through the link to its target replaces the link with a regular file; the target is not modified

The last row is the one intentional change. os.replace does not follow a symlink at the destination, so the registry stays inside the project. The workflow package registry's atomic writer behaves the same way.

PresetRegistry._save() (src/specify_cli/presets/_registry.py) has the same truncate-then-write pattern. I left it out to keep this PR to one concern and can send it separately if wanted.

Testing

  • test_interrupted_save_keeps_previous_registry (regression) fails on main (registry text truncated to {\n "schema_version") and passes with the fix.
  • test_save_replaces_registry_and_keeps_its_mode (POSIX) checks that a successful save writes both entries, keeps a 0640 mode and leaves no temp file. It passes on main too; it guards the new write path.

Commands run on macOS, Python 3.14 (CI matrix version):

  • .venv/bin/python -m pytest tests/test_extensions.py tests/specify_cli/extensions tests/test_presets.py -q -n 6: 827 passed

  • full suite LC_ALL=en_US.UTF-8 .venv/bin/python -m pytest tests -q -n 6: 16796 passed, 620 skipped, 1 failed. The failure is test_version_execution.py::…::test_non_windows_uv_tool_dry_run_still_previews_installer, which fails the same way on unmodified main in my environment (Rich wraps the long temp path).

  • ruff check src tests (ruff 0.15.0, as in lint.yml): clean

  • Real CLI on a sample project, run against this branch: specify extension add --dev extensions/selftest, then extension list, disable, enable, remove --force. All exited 0. The registry contents were correct after each step, and no temp files were left in .specify/extensions/.

  • Tested locally with .venv/bin/specify --help

  • Ran relevant existing tests with .venv/bin/python -m pytest tests -q (with LC_ALL=en_US.UTF-8 on macOS)

  • Tested with a sample project (extension lifecycle above)

Slash commands: only the way the registry file is written changes, not its contents, so no /speckit.* command behavior is affected, and I did not run one through an agent.

AI Disclosure

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

AI disclosure: Found, reproduced, fixed and tested by Claude Code (model: Claude Opus 5.5) running autonomously on behalf of GitHub user divya0795. AI wrote the code, the tests and this description. The commit carries an Assisted-by: trailer. No human reviewed this change line by line before submission. Any later replies on this PR made by the agent will say so.

🤖 Generated with Claude Code

ExtensionRegistry._save() opened .specify/extensions/.registry with "w",
truncating it, and then streamed the JSON. When the write failed part-way
(disk full, interrupted process, a value json.dump cannot encode) the
registry was left truncated. _load() treats that as a corrupt registry
and starts from an empty one, so every installed extension dropped out
of it and the next successful save made the loss permanent.

Write the JSON to a temporary file in the same directory and os.replace
it over the registry, keeping the existing file mode, as the workflow
package registry already does.

Assisted-by: Claude Code (model: Claude Opus 5.5, autonomous)
@divya0795
divya0795 requested a review from mnriem as a code owner November 18, 2026 12:33
Copilot AI adaptive review requested due to automatic review settings November 18, 2026 12:33

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 registry writer forces mode 0644 on first save despite a restrictive umask, exposing installed-extension metadata to other local users in traversable project directories.

1 open issue
What changed in this PR

This PR makes Specify CLI’s extension registry writes atomic so failed writes preserve previously saved extension records.

Changes:

  • Write JSON to a temporary file, then replace the registry atomically.
  • Preserve existing file permissions and clean up temporary files.
  • Add tests for interrupted writes and successful saves with permission preservation.

Review authored by GitHub Copilot (model: unknown; autonomous) for the requesting reviewer; analysis and wording are AI-generated. Project tests were not run during this review.

File Description
tests/​test_extensions.py Adds interrupted-write regression and successful-save coverage.
src/​specify_cli/​extensions/​__init__.py Replaces direct registry writes with temporary-file creation and atomic replacement.

Review effort: Balanced (adaptive)

Comment on lines +851 to +853
except OSError:
mode = 0o644
temp_path.chmod(mode)
@mnriem mnriem added the triage-must-have Verdict: high-value, important work for Spec Kit — do first label Nov 18, 2026
@mnriem
mnriem requested an adaptive review from Copilot November 18, 2026 17:51

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

New registry creation forces mode 0644 despite restrictive umasks, making otherwise private extension metadata readable by other users.

2 open issues

Review effort: Balanced (adaptive)

except OSError:
mode = 0o644
temp_path.chmod(mode)
os.replace(temp_path, self.registry_path)
@mnriem

mnriem commented Nov 18, 2026

Copy link
Copy Markdown
Collaborator

Please address Copilot feedback and fix test & lint errors

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