fix: trash as root folder and caching strageties

[bosi95]

fix: make trash a root folder and use a similar approach as a generic folder
fix: cached version store
fix: depth check for listFolder
chore: remove unused functions/variables
chore: make error throws consistent
test: missing and newly fixed functionalities
fix: use admin_drive_name instead of admin_stamp_label

[Copilot]

Pull request overview

This PR refactors lifecycle handling to make trash a first-class, reserved root folder (.trash) instead of an owner-private overlay, while also tightening path validation, improving caching of feed state, and hardening operational behavior (abort semantics + event listener isolation). It updates the public API docs accordingly and expands unit/integration test coverage around the new behaviors.

Changes:

• Replace “trash overlay” semantics with .trash fork relocation (trash, recover, listTrash, emptyTrash) and reserve .trash from regular write/list operations.
• Rework mantaray/feed caching to track “next feed index” and avoid stale cache writes when reading historical versions.
• Add/adjust tests and docs to cover path guards, duplicate-name behavior, abort rollback behavior, and consistent event payloads.

Reviewed changes

Copilot reviewed 36 out of 36 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tsup.config.ts	Removes stub for getContentType after FS helper cleanup.
tests/utils.ts	Adds getEncodedData test helper and updates Bee imports.
tests/unit/version.spec.ts	Extends versioning tests for path stamping and cached-head refs behavior.
tests/unit/trash.spec.ts	Reworks lifecycle tests around reserved .trash folder and new APIs (trash/recover/emptyTrash).
tests/unit/mock.ts	Switches mocks from ADMIN_STAMP_LABEL to ADMIN_DRIVE_NAME.
tests/unit/init.spec.ts	Adds unit tests for initialize rollback/retry and admin manifest-cache failure recovery.
tests/unit/folder.spec.ts	Adds tests for default download path, duplicate folder creation rejection, and descendant path rewrites on move.
tests/unit/file.spec.ts	Adds tests for upload collision rejection, path validation, uploadFiles default root behavior, and trashed-path guards.
tests/unit/events.spec.ts	Adds tests ensuring throwing listeners don’t break library operations.
tests/unit/drive.spec.ts	Updates expectations to ADMIN_DRIVE_NAME.
tests/unit/abort.spec.ts	Adds batch-abort tests for uploadFiles and verifies rollback/forwarding of abort signals.
tests/TESTS.md	Updates testing documentation to reflect .trash-based behavior and new events.
tests/integration/version.spec.ts	Adds cold-instance restore test to ensure restores don’t collide with same-named root decoys.
tests/integration/trash.spec.ts	Updates integration lifecycle tests for .trash relocation, guarded writes, and emptying trash.
tests/integration/setup/utils.ts	Uses ADMIN_DRIVE_NAME when creating/finding the owner stamp.
tests/integration/init.spec.ts	Adds integration tests for 404/unwritten feeds and initialize listener isolation + rollback retry.
tests/integration/folder.spec.ts	Adds integration coverage for duplicate folder rejection and default download behavior.
tests/integration/file.spec.ts	Adds integration coverage for upload collisions, invalid paths, uploadFiles defaults/duplicates; removes cross-drive move test.
tests/integration/abort.spec.ts	Adds integration coverage for aborting uploadFiles and ensuring aborted batches never commit later.
src/utils/path.ts	Adds node-path validation + .trash reservation helpers (assertNotTrashPath, trashPathOf, etc.).
src/utils/mantaray.ts	Adjusts manifest save result typing and adds folderInfoFromMetadata + trashed-origin metadata handling.
src/utils/index.ts	Exports ADMIN_DRIVE_NAME instead of ADMIN_STAMP_LABEL.
src/utils/fs/fs-node.ts	Removes content-type detection from node FS read helper (stream-only upload).
src/utils/events.ts	Updates event enum (adds folder move + trash emptied; removes file-downloaded).
src/utils/constants.ts	Introduces TRASH_FOLDER_NAME and MANIFEST_METADATA_TRASHED_FROM; renames admin constant.
src/utils/common.ts	Redefines record status from path (trash detection) and tightens 404 detection.
src/utils/bee.ts	Returns richer feed-write result (index + nextIndex) and enforces Bee version support via exception.
src/utils/asserts.ts	Removes trashed overlay parsing and validates FileRecord.version via FeedIndex.
src/types/info.ts	Removes trashedNodes from drives; adds trashedFrom + ResolvedFileFork typing.
src/types/index.ts	Removes re-export of TrashEntry.
src/types/fileManager.ts	Updates public interface docs for new trash APIs, guards, and semantics.
src/mantarayStore.ts	Refactors caches to “next index”, adds head-read options to avoid stale ref/index caching.
src/fileManager.ts	Implements .trash relocation-based lifecycle, abort-batch rollback, path guards, move semantics changes, and versioning cache fixes.
src/eventEmitter/eventEmitter.ts	Isolates throwing listeners to prevent consumer handlers from breaking library execution.
REFERENCE.md	Updates reference docs to new trash model, events payloads, and path/abort semantics.
README.md	Updates high-level docs and examples for new FeedIndex usage and .trash behavior.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.