renamer/specs/003-add-remove-command/spec.md

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.