# Feature Specification: Remove Command with Sequential Multi-Pattern Support

**Feature Branch**: `003-add-remove-command`  
**Created**: 2025-10-29  
**Status**: Draft  
**Input**: User description: "添加 移除（Remove）命令，用于删除指定字符、字符串，支持同时删除多个字符串，示例：renamer remove str1 str2 ....，注意：多个移除时后续参数的移除依赖于前一个移除后的结果，移除计算完成前不进行重命名，避免IO负载过高"

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Remove Unwanted Tokens in One Pass (Priority: P1)

As a CLI user tidying filenames, I want `renamer remove` to delete multiple substrings in order so I
can normalize file names without writing custom scripts.

**Why this priority**: Delivers the core value—batch cleanup of recurring tokens across many files
with predictable results.

**Independent Test**: Run `renamer remove " copy" " draft" --dry-run` in a sample directory,
confirm preview shows the ordered removal effects, then apply with `--yes` and verify names update
accordingly.

**Acceptance Scenarios**:

1. **Given** files `report copy draft.txt` and `notes draft.txt`, **When** the user runs
   `renamer remove " copy" " draft"`, **Then** the preview shows both tokens removed sequentially
   and execution produces `report.txt` and `notes.txt`.
2. **Given** patterns where later removals depend on earlier results (e.g., removing `foo` then `foo-`),
   **When** the command runs, **Then** each removal applies to the output of the previous step before
   computing rename conflicts.

---

### User Story 2 - Script-Friendly Removal Workflow (Priority: P2)

As an operator automating rename tasks, I want deterministic previews, exit codes, and ledger entries
so scripts can run `renamer remove` safely without interactive prompts.

**Why this priority**: Ensures automation pipelines can rely on the same safety guarantees as manual
runs.

**Independent Test**: In a CI script, call `renamer remove ... --dry-run`, assert exit code 0, then
run with `--yes` and verify ledger entry plus `renamer undo` restores originals.

**Acceptance Scenarios**:

1. **Given** a non-interactive context, **When** the user passes `--yes` after a successful preview,
   **Then** the command exits 0 on success and writes a ledger entry capturing tokens removed per file.
2. **Given** invalid input (e.g., fewer than two arguments), **When** the command executes, **Then** it
   exits with non-zero status and instructs the user on correct sequential argument usage.

---

### User Story 3 - Validate Sequential Removal Inputs (Priority: P3)

As a power user managing complex token lists, I want clear validation and guidance for spaces,
duplicate tokens, and results that could produce empty filenames so I can adjust before applying.

**Why this priority**: Prevents surprise failures when tokens overlap or yield empty names.

**Independent Test**: Run `renamer remove "Project X" " Project" "X" --dry-run`, confirm preview
shows the sequential impact and warns if names collapse; invalid quoting should produce actionable
errors.

**Acceptance Scenarios**:

1. **Given** duplicate tokens, **When** the command runs, **Then** duplicates are deduplicated with a
   warning and order preserved for remaining unique tokens.
2. **Given** a removal sequence that would produce an empty basename, **When** the preview runs,
   **Then** the command warns and excludes the rename unless the user overrides in a future version.

---

### Edge Cases

- Sequential removals should operate on the output of prior removals within the same filename.
- Removing tokens may collapse names to empty strings or leave trailing separators; preview must flag
  these cases before apply.
- Resulting names may collide; conflicts must be reported before confirmation.
- Hidden files or directories may need inclusion depending on scope flags (`--hidden`).
- No matches should result in a friendly "No entries matched" message and exit code 0 without ledger
  writes.

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: The CLI MUST expose `renamer remove <pattern1> [pattern2 ...]` where all tokens are
  literal substrings removed sequentially; final name computation MUST complete before any renames
  occur.
- **FR-002**: Preview → confirm workflow MUST mirror existing commands, listing original and proposed
  names with highlighted removals.
- **FR-003**: Executions MUST append detailed entries to `.renamer` including original names, tokens
  removed (with order), resulting names, and timestamps so undo remains possible.
- **FR-004**: Users MUST be able to undo the most recent remove batch via existing undo mechanics
  without leaving orphaned files.
- **FR-005**: Command MUST respect global scope flags (`--path`, `--recursive`, `--include-dirs`,
  `--hidden`, `--extensions`, `--dry-run`, `--yes`) identical to `list` / `replace` behavior.
- **FR-006**: Preview MUST evaluate all removals first, calculate conflicts, and only then apply
  filesystem operations when confirmed, limiting IO load.
- **FR-007**: Command MUST warn (and skip) renames that would result in empty basenames unless a
  future explicit override flag is provided.
- **FR-008**: Invalid invocations (fewer than two arguments, empty tokens after trimming) MUST fail
  with exit code ≠0 and actionable usage guidance.
- **FR-009**: Help output MUST document sequential behavior, whitespace quoting, and interaction with
  other scope flags.

### Key Entities

- **RemoveRequest**: Captures working directory, scope flags, ordered token list, and preview/apply
  options.
- **RemoveSummary**: Aggregates per-token match counts, per-file outcomes, conflicts, and warnings for
  preview and ledger output.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: Users complete a sequential removal across 100 files (preview + apply) in under 2
  minutes end-to-end.
- **SC-002**: 95% of usability test participants correctly understand that removals execute in the
  provided order after reading `renamer remove --help`.
- **SC-003**: Automated regression tests confirm remove + undo leave the filesystem unchanged in
  100% of scripted scenarios.
- **SC-004**: Support requests related to manual substring cleanup drop by 35% within the first release
  cycle after launch.

## Assumptions

- Removals are literal substring matches; regex or wildcard support is out of scope for this release.
- Default matching is case-sensitive; case-insensitive options can be considered later if needed.
- Delete operations target filenames (and directories when `-d/--include-dirs` is set), not file
  contents.
- Existing traversal, conflict detection, and ledger infrastructure can be extended for the remove
  command.

## Dependencies & Risks

- Requires new remove-specific packages analogous to replace to maintain modularity.
- Help/quickstart documentation must be updated to explain sequential removal behavior.
- Potential filename conflicts or empty results must be detected pre-apply to avoid data loss.