[mnriem]

Description

Use anchored directories and opened file descriptors for FileHelper.overwrite_text() while retaining its non-atomic text-upsert contract. Preserve supported contained symlink chains, trusted root aliases, existing inode and hard-link identity, permissions, and native text encoding and newline behavior.

Extract the existing Windows handle primitive into a shared private module, add overwrite coverage, and document the operation's filesystem behavior and limitations. This is an independent change targeting main, not a stacked PR.

Testing

Set up this checkout's .venv and editable install using the local development guide. Run commands from the checkout root.

• Tested locally with .venv/bin/specify --help (Windows PowerShell: .\.venv\Scripts\specify.exe --help)
• Ran relevant existing tests with .venv/bin/python -m pytest tests -q (Windows PowerShell: .\.venv\Scripts\python.exe -m pytest tests -q); use affected test paths for focused checks and LC_ALL=en_US.UTF-8 on macOS
• Tested with a sample project (if applicable)

Commands and results:

• .venv/bin/specify --help — passed.
• LC_ALL=en_US.UTF-8 .venv/bin/python -m pytest tests/test_file_helper.py tests/test_file_helper_overwrite.py tests/test_file_handles.py tests/specify_cli/workflows/test_catalog_cache.py tests/specify_cli/test_file_policy.py tests/integrations/test_integration_state.py -q — 489 passed, 88 skipped.
• git diff --check — passed.

Validation ran on macOS. Native Windows tests are included but were not executed on this host. A separate sample-project run is not applicable; operation tests use temporary project roots. The full test suite was not run.

AI Disclosure

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

AI disclosure: GitHub Copilot using GPT-6.1 Sol (model ID: gpt-6.1-sol) in autonomous mode with runtime-default reasoning settings authored the implementation, tests, documentation, commit message, and PR description, and ran local validation on behalf of @mnriem.

[Copilot]

🟡 Changes recommended

The file-opening changes bypass Windows creation masks, reject otherwise valid writes beneath unreadable parent directories, and break existing Windows permission-failure tests.

3 open issues

• Honor the process umask when creating Windows files · New
• Update Windows overwrite failure injection in tests · New
• Use search-only directory handles for unreadable parents · New

What changed in this PR

This PR moves FileHelper.overwrite_text() to handle-based I/O to resist link-based path swaps while retaining non-atomic, in-place text updates.

Changes:

• Anchor directory traversal and validate the opened file before truncation.
• Share Windows handle utilities with workflow catalog caching.
• Add overwrite and handle tests, and document filesystem guarantees and limitations.

Validation here used isolated POSIX checks; native Windows behavior was not executed.

File	Description
tests/​test_file_helper_overwrite.py	Covers path swaps, text behavior, metadata preservation, and cleanup.
tests/​test_file_handles.py	Checks Windows handle flags, validation, and ownership.
src/​specify_cli/​workflows/​_catalog_cache.py	Reuses the extracted Windows handle helper.
src/​specify_cli/​file_helper.py	Implements anchored, descriptor-based text overwrites.
src/​specify_cli/​_file_handles.py	Provides shared Windows handle and overwrite-descriptor primitives.
design/​file-helper.md	Documents overwrite behavior, platform requirements, and safety limits.

_{Review effort: Max (auto)}

[Copilot]

🟡 Changes recommended

Concurrent Windows overwrites can corrupt the process-wide umask, POSIX traversal can exhaust file descriptors, and the Windows regression test can fail because it compares different encodings.

3 open issues

• Avoid process-wide umask changes during Windows overwrites · New
• Specify UTF-8 in the native reference write · New
• Update Windows overwrite failure injection in tests

2 previously missed issues

In code that hasn't changed since last review

Close previous POSIX directory FDs during traversal

src/​specify_cli/​file_helper.py:267

Keeping every POSIX ancestor in the ExitStack makes descriptor usage grow with path depth, although only the current directory FD is needed for anchored traversal. With 80 valid parent directories and RLIMIT_NOFILE=64, native text overwrite succeeds but this implementation raises EMFILE before opening the leaf. Please close each previous parent after opening its child, as _cache_directory already does; retain the full hierarchy only on Windows, where the sharing locks require it.

Remove the blanket overwrite_text sandbox exception

design/​file-helper.md:227

The blanket overwrite_text exception implies a race-free sandbox and excludes its writes from the partial-results warning. That conflicts with its write-failure contract at lines 180–182 and namespace limits at lines 242–246. Remove this exception and keep the narrower anchored-traversal guarantee in the operation's description above.

2 resolved since last review

• Honor the process umask when creating Windows files
• Use search-only directory handles for unreadable parents

_{Review effort: Max (auto)}

[Copilot]

🔵 Needs a closer look

Overlapping overwrites can corrupt the Windows runtime permission mask, while directory pins unnecessarily require listing access and block otherwise permitted writes.

2 open issues

• Avoid process-wide umask changes during Windows overwrites
• Update Windows overwrite failure injection in tests

2 previously missed issues

In code that hasn't changed since last review

Overlapping overwrites corrupt the process creation mask

src/​specify_cli/​_file_handles.py:46

Two overlapping overwrites can restore 0o200 over an original mask of 0, making a newly created file read-only and changing permissions for later file creations. Unrelated native text-file creation can also observe the temporary mask between these calls. Use a creation strategy that applies the Windows runtime's mask without mutating it, and add an overlapping-call regression; a helper-only lock would not protect unrelated file creators.

Directory pins incorrectly require list access

src/​specify_cli/​file_helper.py:239

The reused _windows_handle(..., directory=True) requests FILE_LIST_DIRECTORY for every directory it pins. On Windows, a directory can allow traversal and writes to a known child while denying directory listing, so this now raises PermissionError for files that native Path.write_text() and the previous implementation can overwrite. Please use directory pins that require traversal rather than listing access while retaining rename protection, and add a native Windows ACL parity regression.

1 resolved since last review

• Specify UTF-8 in the native reference write

_{Review effort: Max (auto)}

[Copilot]

🟡 Changes recommended

A critical Windows symlink race can redirect exclusive file creation outside the helper root, violating the no-redirection guarantee.

2 open issues

• Prevent Windows exclusive-create from following dangling symlinks · New
• Update Windows overwrite failure injection in tests

1 resolved since last review

• Avoid process-wide umask changes during Windows overwrites

_{Review effort: Max (auto)}

[Copilot]

🟡 Changes recommended

The Windows permission probe can fail when creation and writing are allowed but deletion is denied, leaving a probe file behind and aborting otherwise permitted destination creation.

2 open issues

• Update Windows overwrite failure injection in tests
• Avoid requiring delete permission to determine creation attributes · New

1 resolved since last review

• Prevent Windows exclusive-create from following dangling symlinks

_{Review effort: Max (auto)}

[Copilot]

🔵 Needs a closer look

Human assessment is needed because Windows directory pinning can reject otherwise permitted text writes when ACLs deny directory listing.

1 open issue

• Update Windows overwrite failure injection in tests

1 resolved since last review

• Avoid requiring delete permission to determine creation attributes

_{Review effort: Max (auto)}

[Copilot]

🟡 Changes recommended

The overwrite documentation omits Windows pinning’s directory-listing and attribute-read requirements on the canonical root and resolved parents, leaving unexplained why restrictive access rules can prevent overwriting an otherwise writable file.

2 open issues

• Update Windows overwrite failure injection in tests
• Document Windows directory-listing access requirement · New

_{Review effort: Max (auto)}

[Copilot]

🔵 Needs a closer look

The overwrite contract omits the new Windows directory-list access requirement on the root and parent directories, leaving a platform-specific failure mode undocumented.

2 open issues

• Update Windows overwrite failure injection in tests
• Document Windows directory-listing access requirement

_{Review effort: Max (auto)}

[Copilot]

🔵 Needs a closer look

Human assessment is needed because the FIFO test can pass without O_NONBLOCK, leaving the no-reader case vulnerable to an undetected indefinite hang.

1 open issue

• Update Windows overwrite failure injection in tests

1 resolved since last review

• Document Windows directory-listing access requirement

_{Review effort: Max (auto)}

[Copilot]

🔵 Needs a closer look

Human review is needed to assess test coverage gaps around unsupported platform primitives, concurrent file creation, and creation-mask probe avoidance during Windows overwrites.

1 open issue

• Update Windows overwrite failure injection in tests

_{Review effort: Max (auto)}

[Copilot]

🔵 Needs a closer look

Human assessment is needed to judge whether the concurrency test’s simulated umask state and timed waits introduce unnecessary complexity.

1 open issue

• Update Windows overwrite failure injection in tests

_{Review effort: Max (auto)}

[mnriem]

Updated in 032dad0d: the concurrency test now runs two overwrite calls and relies on the existing assertion that os.umask must not be called, with no simulated mask state or timed waits. It still checks descriptor cleanup. .venv/bin/python -m pytest tests/test_file_handles.py tests/test_file_helper.py::test_overwrite_text_io_errors_propagate -q passed (38 tests). GitHub Copilot (GPT-6.1 Sol, gpt-6.1-sol, autonomous; reasoning setting not exposed) generated this test change, ran validation, and wrote this comment on behalf of @mnriem.

[Copilot]

🔵 Needs a closer look

The new Win32/CRT filesystem paths lack native Windows validation, and macOS-only runs with portable mocks cannot establish sharing, ACL, creation-mask, or handle-ownership behavior.

No open issues 🎉

1 resolved since last review

• Update Windows overwrite failure injection in tests

_{Review effort: Max (auto)}