Skip to content

fix(tman): remove stale files when replacing packages - #2314

Open
OT-WuLong wants to merge 1 commit into
TEN-framework:mainfrom
OT-WuLong:fix/tman-remove-stale-package-files
Open

OT-WuLong wants to merge 1 commit into
TEN-framework:mainfrom
OT-WuLong:fix/tman-remove-stale-package-files

Conversation

@OT-WuLong

Copy link
Copy Markdown

Summary

Fix stale files remaining after tman install replaces an existing package.

Previously, tman extracted the replacement archive directly into the existing
package directory. Files with matching names were overwritten, but files that
did not exist in the replacement package remained on disk.

The existing package path is now removed before extraction, ensuring the
installed directory exactly matches the selected package version.

How This Was Found

While looking for an issue to contribute, I revisited #920. Since the issue was
reported in 2025, I first:

  • synchronized the repository with the latest upstream/main;
  • checked the current tman 0.11.71 implementation;
  • searched existing open and closed pull requests for a previous fix;
  • reproduced the problem using a local package registry.

The reproduction used two versions of the same extension:

  1. Version 2.0.0 contained a v2_only.txt file.
  2. Version 1.0.0 did not contain that file.
  3. Version 2.0.0 was installed first.
  4. The dependency was changed to version 1.0.0.
  5. tman install reported a successful downgrade, but v2_only.txt remained.

Tracing the installation flow showed that the replacement archive was extracted
over the existing directory. The new installed_paths only described files
from the replacement package, so it could not identify files left by the
previous version.

Implementation

  • Download the replacement package before modifying the existing installation.
  • Remove the existing non-local package path before extracting the replacement.
  • Use the existing remove_dir_all dependency for reliable directory removal,
    including Windows read-only file handling.
  • Detect symbolic links without following them, so only the link is removed and
    its target remains untouched.
  • Handle dangling links, unexpected regular files, and missing paths.
  • Add an integration regression test covering a 2.0.0 to 1.0.0 downgrade.

Downloading happens before removal, so a download failure leaves the currently
installed package untouched.

Type of Change

  • Bug fix
  • New feature
  • Documentation update
  • Performance improvement
  • Code refactoring

Testing

  • Tests added/updated
  • Targeted tests pass locally
  • Manual testing completed
  • Full CI suite passes — pending GitHub Actions

Tests performed:

  • Confirmed the regression test fails with the unmodified tman 0.11.71 binary.
  • Built the updated tman target successfully.
  • Verified that downgrading from 2.0.0 to 1.0.0 removes the
    newer-version-only file.
  • Verified that an already-installed matching version is not reinstalled and
    retains additional files.
  • Verified that replacing a package-directory symbolic link preserves the link
    target.
  • Ran Black, Python compilation, GN validation, JSON validation, Rust
    compilation, and git diff --check.

Documentation

Documentation updates are not required because this fixes existing installation
behavior without changing the public API or user workflow.

Breaking Changes

None.

Fixes #920

Remove the existing registry package path before extracting a replacement.

Add downgrade coverage for files that only exist in the newer package.
@OT-WuLong
OT-WuLong requested a review from halajohn as a code owner September 8, 2026 16:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

tman install 插件回退插件版本的的时候,需要将代码一并回退

1 participant