@amirdaraee/namewise 0.5.5 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -7,10 +7,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.6.0] - 2026-04-02
11
+
12
+ ### Added
13
+ - **Recursive Directory Scanning**: New `-r, --recursive` flag scans subdirectories
14
+ - Optional `--depth <n>` to cap recursion depth
15
+ - Example: `namewise rename ./projects --recursive --depth 2 --dry-run`
16
+ - **Undo Command**: New `namewise undo` reverses the most recent rename session
17
+ - Sessions stored in `~/.namewise/history.json` (append-only audit log)
18
+ - `namewise undo --list` shows the last 10 sessions with their IDs
19
+ - `namewise undo <session-id>` undoes a specific past session
20
+ - Warns and skips (without erroring) if a file has already been moved
21
+ - **Cascading Config File**: Project- and user-level config support
22
+ - `~/.namewise.json` sets user-wide defaults
23
+ - `<targetDir>/.namewise.json` overrides per project
24
+ - CLI flags override both; all keys are optional
25
+ - Supports: `provider`, `case`, `template`, `name`, `date`, `maxSize`, `model`, `baseUrl`, `concurrency`, `recursive`, `depth`, `output`
26
+ - **Concurrency Control**: New `--concurrency <n>` flag (default: 3)
27
+ - Files are processed in parallel up to the configured limit
28
+ - Implemented with a zero-dependency semaphore
29
+ - **JSON Rename Report**: New `--output <path>` flag writes a full report after each run
30
+ - Includes timestamp, directory, dry-run flag, summary counts, and per-file results
31
+
32
+ ### Changed
33
+ - **Conflict Auto-Numbering**: Replaces the old "file already exists" error
34
+ - When the suggested name is taken, automatically tries `-2`, `-3` … up to `-99`
35
+ - Example: `report.pdf` → `report-2.pdf` if `report.pdf` already exists
36
+
37
+ ### Technical
38
+ - Added `src/utils/config-loader.ts` and `src/utils/history.ts` as thin, focused modules
39
+ - Added `src/cli/undo.ts` for undo command logic
40
+ - 103 new tests across 11 new/updated test files; total now 428 tests (36 files)
41
+
42
+ ### Examples
43
+ ```bash
44
+ # Recursive scan with depth limit
45
+ namewise rename ./projects --recursive --depth 2 --dry-run
46
+
47
+ # Save defaults to ~/.namewise.json
48
+ echo '{"provider":"claude","case":"snake_case","concurrency":5}' > ~/.namewise.json
49
+
50
+ # Save a rename report
51
+ namewise rename ./documents --output ./report.json
52
+
53
+ # Undo the last session
54
+ namewise undo
55
+
56
+ # List and undo a specific session
57
+ namewise undo --list
58
+ namewise undo 2026-04-02T10:30:00.000Z
59
+ ```
60
+
10
61
  ## [0.5.4] - 2026-03-31
11
62
 
12
63
  ### Improved
13
- - **🧪 Test Coverage**: Achieved 100% coverage across all metrics (statements, branches, functions, lines)
64
+ - **Test Coverage**: Achieved 100% coverage across all metrics (statements, branches, functions, lines)
14
65
  - 325 tests across 26 test files
15
66
  - Added tests for all error branches including non-Error exception paths
16
67
  - Full coverage for scanned PDF handling, folder-based categorization, and naming convention truncation
@@ -19,7 +70,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
19
70
  ## [0.5.0] - 2025-11-10
20
71
 
21
72
  ### Added
22
- - **📄 Scanned PDF Support**: Full support for image-only (scanned) PDFs with vision AI
73
+ - **Scanned PDF Support**: Full support for image-only (scanned) PDFs with vision AI
23
74
  - Automatic detection of scanned PDFs (documents with minimal or no text)
24
75
  - Converts first page to image and sends to AI for content analysis
25
76
  - Intelligent image optimization to stay under Claude's 5MB limit
@@ -28,11 +79,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
28
79
  - Smart size calculation to ensure API compatibility
29
80
 
30
81
  ### Enhanced
31
- - **🔄 PDF Processing**: Replaced PDF.js with pdf-to-png-converter for better Node.js compatibility
82
+ - **PDF Processing**: Replaced PDF.js with pdf-to-png-converter for better Node.js compatibility
32
83
  - Resolves canvas rendering issues in Node.js environment
33
84
  - More reliable PDF-to-image conversion
34
85
  - Better error handling and debugging
35
- - **🤖 AI Model**: Updated to Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
86
+ - **AI Model**: Updated to Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
36
87
  - Latest Claude model with enhanced vision capabilities
37
88
  - Improved accuracy for document analysis
38
89
  - Better understanding of complex document layouts
@@ -44,9 +95,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
44
95
  - Improved error logging with detailed stack traces
45
96
 
46
97
  ### Fixed
47
- - **🐛 Critical**: Fixed "Image or Canvas expected" errors when processing scanned PDFs
48
- - **🐛 Critical**: Fixed "image exceeds 5 MB maximum" errors with large scanned documents
49
- - **🐛 Model**: Fixed deprecated model warnings by updating to latest Claude API
98
+ - **Critical**: Fixed "Image or Canvas expected" errors when processing scanned PDFs
99
+ - **Critical**: Fixed "image exceeds 5 MB maximum" errors with large scanned documents
100
+ - **Model**: Fixed deprecated model warnings by updating to latest Claude API
50
101
 
51
102
  ### Examples
52
103
  ```bash
@@ -64,27 +115,27 @@ namewise rename ./documents --dry-run
64
115
  ## [0.4.1] - 2025-09-15
65
116
 
66
117
  ### Enhanced
67
- - **🔧 Reliability Improvements**: Enhanced stability and consistency across all AI providers
68
- - **📋 Documentation**: Improved examples and usage documentation
118
+ - **Reliability Improvements**: Enhanced stability and consistency across all AI providers
119
+ - **Documentation**: Improved examples and usage documentation
69
120
 
70
121
  ## [0.4.0] - 2025-09-15
71
122
 
72
123
  ### Added
73
- - **🤖 Local LLM Provider Support**: Full integration with local AI services
124
+ - **Local LLM Provider Support**: Full integration with local AI services
74
125
  - **Ollama**: Local LLM support with customizable models (llama3.1, codellama, etc.)
75
126
  - **LMStudio**: Local model hosting with OpenAI-compatible API
76
127
  - Support for custom base URLs and model selection
77
128
  - Availability checking and model listing for local providers
78
129
 
79
130
  ### Enhanced
80
- - **🎯 Intelligent Person Name Detection**: Major AI prompting improvements
131
+ - **Intelligent Person Name Detection**: Major AI prompting improvements
81
132
  - AI now extracts person names from document content and places them at filename beginning
82
133
  - Smart folder name filtering to ignore irrelevant names like "no", "temp", "downloads"
83
134
  - Enhanced prompts that focus on document content rather than metadata
84
135
  - Support for detecting visa applications, contracts, medical records, certificates
85
136
 
86
137
  ### Architecture
87
- - **📋 Centralized Prompt System**: Single source of truth for all AI prompts
138
+ - **Centralized Prompt System**: Single source of truth for all AI prompts
88
139
  - Model-agnostic prompting that works across Claude, OpenAI, LMStudio, and Ollama
89
140
  - Consolidated prompt building in `/src/utils/ai-prompts.ts`
90
141
  - Consistent behavior across all AI providers
@@ -110,18 +161,18 @@ namewise rename ./files --provider lmstudio --base-url http://localhost:1234 --m
110
161
  ## [0.3.1] - 2025-09-05
111
162
 
112
163
  ### Security
113
- - **🔒 Vulnerability Fix**: Replaced vulnerable `xlsx` package with secure `exceljs`
164
+ - **Vulnerability Fix**: Replaced vulnerable `xlsx` package with secure `exceljs`
114
165
  - Enhanced Excel file parsing with improved security and reliability
115
166
 
116
167
  ### Infrastructure
117
- - **⚙️ CI/CD Improvements**: Enhanced GitHub Actions workflows
168
+ - **CI/CD Improvements**: Enhanced GitHub Actions workflows
118
169
  - Updated Node.js versions in CI pipelines
119
170
  - Improved test workflow reliability and build process
120
171
 
121
172
  ## [0.3.0] - 2025-09-05
122
173
 
123
174
  ### Added
124
- - **🎯 Personal File Templates**: Customizable templates for different file categories
175
+ - **Personal File Templates**: Customizable templates for different file categories
125
176
  - `document`: Personal docs with name and date (e.g., `driving-license-amirhossein-20250213.pdf`)
126
177
  - `movie`: Movies with release year (e.g., `the-dark-knight-2008.mkv`)
127
178
  - `music`: Music with artist names (e.g., `the-beatles-hey-jude.mp3`)
@@ -129,14 +180,14 @@ namewise rename ./files --provider lmstudio --base-url http://localhost:1234 --m
129
180
  - `photo`: Photos with personal info (e.g., `vacation-paris-john-20240715.jpg`)
130
181
  - `book`: Books with author names (e.g., `george-orwell-1984.pdf`)
131
182
  - `general`: General files without special formatting
132
- - **🤖 Smart File Categorization**: Automatically detects file type based on extension and content
133
- - **👤 Personal Name Integration**: `-n, --name` option to include your name in documents
134
- - **📅 Flexible Date Formats**: `-d, --date` option with formats:
183
+ - **Smart File Categorization**: Automatically detects file type based on extension and content
184
+ - **Personal Name Integration**: `-n, --name` option to include your name in documents
185
+ - **Flexible Date Formats**: `-d, --date` option with formats:
135
186
  - `YYYY-MM-DD`: 2025-09-05
136
187
  - `YYYY`: 2025
137
188
  - `YYYYMMDD`: 20250905
138
189
  - `none`: No date (default)
139
- - **📂 Category Templates**: `-t, --template` option to specify file category or use auto-detection
190
+ - **Category Templates**: `-t, --template` option to specify file category or use auto-detection
140
191
 
141
192
  ### Enhanced
142
193
  - AI prompts now include category-specific instructions for better filename generation
package/README.md CHANGED
@@ -1,12 +1,12 @@
1
1
  # Namewise
2
2
 
3
- [![Tests](https://img.shields.io/badge/tests-325%20passing-brightgreen.svg)](#testing--development)
3
+ [![Tests](https://img.shields.io/badge/tests-428%20passing-brightgreen.svg)](#testing--development)
4
4
  [![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](#testing--development)
5
5
  [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
6
6
  [![Node.js](https://img.shields.io/badge/Node.js-20+-green.svg)](https://nodejs.org/)
7
7
  [![License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
8
8
 
9
- **AI-Powered File Renaming CLI Tool**
9
+ **AI-Powered File Renaming CLI Tool**
10
10
 
11
11
  Automatically rename files based on their content using AI providers (Claude, OpenAI, Ollama, LMStudio). Transform messy filenames like `document1.pdf` or `IMG_20240315_143022.pdf` into descriptive names like `project-requirements-document.pdf` or `quarterly-sales-report-q4-2023.pdf`.
12
12
 
@@ -16,13 +16,17 @@ Automatically rename files based on their content using AI providers (Claude, Op
16
16
 
17
17
  - **AI-Powered Renaming**: Uses cloud providers (Claude, OpenAI) or local LLMs (Ollama, LMStudio) to generate descriptive filenames
18
18
  - **Privacy First**: Local LLM support means your files never leave your machine
19
- - **Cost Effective**: Use free local models or pay-per-use cloud APIs
19
+ - **Recursive Scanning**: Scan nested directories with an optional depth limit
20
+ - **Undo Support**: Reverse any previous rename session via `namewise undo`
21
+ - **Config File**: Set persistent defaults in `~/.namewise.json` or per-project `.namewise.json`
22
+ - **Concurrency Control**: Process multiple files in parallel with a configurable limit
23
+ - **Conflict Auto-Numbering**: When a target name is taken, automatically appends `-2`, `-3`, etc.
24
+ - **JSON Report Output**: Save a full rename report to a file with `--output`
20
25
  - **Personal File Templates**: Customizable templates for different file categories (documents, movies, music, series, photos, books)
21
26
  - **Smart Categorization**: Automatic file type detection or manual category selection
22
27
  - **Naming Convention Options**: 6 different formats (kebab-case, snake_case, camelCase, PascalCase, lowercase, UPPERCASE)
23
28
  - **Multiple File Types**: Supports PDF, DOCX, DOC, XLSX, XLS, TXT, MD, and RTF files
24
29
  - **Dry Run Mode**: Preview changes before renaming files
25
- - **Conflict Detection**: Prevents overwriting existing files
26
30
  - **Size Limits**: Configurable maximum file size limits
27
31
 
28
32
  ## Quick Start
@@ -34,10 +38,10 @@ cd namewise
34
38
  npm install
35
39
  npm run build
36
40
 
37
- # Rename files (dry run first)
41
+ # Preview renames (recommended first)
38
42
  npx namewise rename ./my-documents --dry-run --provider claude
39
43
 
40
- # Actually rename with your API key
44
+ # Actually rename
41
45
  npx namewise rename ./my-documents --provider claude --api-key your-api-key
42
46
  ```
43
47
 
@@ -59,10 +63,12 @@ Download the latest release from [GitHub Releases](https://github.com/amirdaraee
59
63
 
60
64
  ### Command Structure
61
65
  ```bash
62
- namewise rename <directory> [options]
66
+ namewise rename [directory] [options]
67
+ namewise undo [session-id] [options]
63
68
  ```
64
69
 
65
70
  ### Options Reference
71
+
66
72
  | Option | Description | Default |
67
73
  |--------|-------------|---------|
68
74
  | `--provider` | AI provider (`claude`, `openai`, `ollama`, `lmstudio`) | `claude` |
@@ -75,15 +81,47 @@ namewise rename <directory> [options]
75
81
  | `--date` | Date format (YYYY-MM-DD, YYYY, YYYYMMDD, none) | `none` |
76
82
  | `--dry-run` | Preview changes without renaming | `false` |
77
83
  | `--max-size` | Maximum file size in MB | `10` |
84
+ | `-r, --recursive` | Recursively scan subdirectories | `false` |
85
+ | `--depth <n>` | Maximum recursion depth (requires `--recursive`) | Unlimited |
86
+ | `--concurrency <n>` | Files to process in parallel | `3` |
87
+ | `--output <path>` | Save rename report as JSON to this path | - |
88
+
89
+ ### Undo Options
90
+
91
+ | Option | Description |
92
+ |--------|-------------|
93
+ | `--list` | List recent rename sessions with their IDs |
94
+ | `[session-id]` | Undo a specific session by ID (default: most recent) |
78
95
 
79
96
  ### Examples
80
97
 
81
- **Basic usage (general template, no personalization):**
98
+ **Basic usage:**
82
99
  ```bash
83
100
  namewise rename ./documents --dry-run
84
101
  # Result: quarterly-financial-report.pdf
85
102
  ```
86
103
 
104
+ **Recursive scan with depth limit:**
105
+ ```bash
106
+ namewise rename ./projects --recursive --depth 2 --dry-run
107
+ ```
108
+
109
+ **Save a JSON report:**
110
+ ```bash
111
+ namewise rename ./documents --output ./report.json
112
+ ```
113
+
114
+ **Undo the last rename session:**
115
+ ```bash
116
+ namewise undo
117
+ ```
118
+
119
+ **List and undo a specific session:**
120
+ ```bash
121
+ namewise undo --list
122
+ namewise undo 2026-04-02T10:30:00.000Z
123
+ ```
124
+
87
125
  **Personal documents with your name and date:**
88
126
  ```bash
89
127
  namewise rename ./documents --template document --name "john" --date "YYYYMMDD" --dry-run
@@ -98,80 +136,87 @@ namewise rename ./movies --template auto --dry-run
98
136
 
99
137
  **TV series with season/episode detection:**
100
138
  ```bash
101
- namewise rename ./shows --template auto --dry-run
139
+ namewise rename ./shows --template auto --dry-run
102
140
  # Result: breaking-bad-s01e01.mkv
103
141
  ```
104
142
 
105
- **Music with artist names:**
106
- ```bash
107
- namewise rename ./music --template music --dry-run
108
- # Result: the-beatles-hey-jude.mp3
109
- ```
110
-
111
143
  **Snake case naming convention:**
112
144
  ```bash
113
145
  namewise rename ./docs --case snake_case --dry-run
114
146
  # Result: project_requirements_document.pdf
115
147
  ```
116
148
 
117
- **Local LLMs (Privacy-First, No API Keys):**
149
+ **Local LLMs (no API key required):**
118
150
  ```bash
119
151
  # Ollama - requires 'ollama serve' running
120
152
  namewise rename ./documents --provider ollama --dry-run
121
- # Result: quarterly-financial-report.pdf
122
-
123
- # Custom Ollama model
124
- namewise rename ./code --provider ollama --model codellama --dry-run
125
- # Result: user-authentication-service.js
126
153
 
127
154
  # LMStudio - requires local server enabled
128
155
  namewise rename ./contracts --provider lmstudio --dry-run
129
- # Result: employment-agreement-template.docx
130
-
131
- # Remote Ollama server
132
- namewise rename ./files --provider ollama --base-url http://192.168.1.100:11434 --model llama3.1
133
156
  ```
134
157
 
135
- **Cloud Providers (API Keys Required):**
158
+ **Cloud providers:**
136
159
  ```bash
137
- # Claude (recommended for accuracy)
138
- export CLAUDE_API_KEY=your-key
160
+ export ANTHROPIC_API_KEY=your-key
139
161
  namewise rename ./documents --provider claude --dry-run
140
162
 
141
- # OpenAI
142
163
  export OPENAI_API_KEY=your-key
143
- namewise rename ./files --provider openai --max-size 20 --dry-run
164
+ namewise rename ./files --provider openai --dry-run
144
165
  ```
145
166
 
146
- **Before and After Example:**
167
+ **Before and after:**
147
168
  ```
148
- Before:
169
+ Before:
149
170
  ├── IMG_20240315_143022.pdf
150
171
  ├── document1.docx
151
172
  ├── Report Q4 2023 FINAL FINAL.xlsx
152
173
 
153
- After:
174
+ After:
154
175
  ├── quarterly-financial-report-q4-2023.pdf
155
176
  ├── project-requirements-specification.docx
156
177
  ├── annual-sales-performance-summary.xlsx
157
178
  ```
158
179
 
180
+ ## Config File
181
+
182
+ Set persistent defaults so you don't have to repeat flags on every run.
183
+
184
+ **User-wide defaults** (`~/.namewise.json`):
185
+ ```json
186
+ {
187
+ "provider": "claude",
188
+ "case": "snake_case",
189
+ "concurrency": 5
190
+ }
191
+ ```
192
+
193
+ **Per-project overrides** (`<targetDir>/.namewise.json`):
194
+ ```json
195
+ {
196
+ "template": "document",
197
+ "name": "alice",
198
+ "date": "YYYYMMDD"
199
+ }
200
+ ```
201
+
202
+ Priority order (highest to lowest): CLI flags > project config > user config.
203
+
204
+ Supported keys: `provider`, `case`, `template`, `name`, `date`, `maxSize`, `model`, `baseUrl`, `concurrency`, `recursive`, `depth`, `output`.
205
+
159
206
  ## Supported File Types
160
207
 
161
208
  | Type | Extensions | Parser |
162
- |------|------------|---------|
209
+ |------|------------|--------|
163
210
  | PDF Documents | `.pdf` | pdf-extraction |
164
211
  | Microsoft Word | `.docx`, `.doc` | mammoth |
165
- | Microsoft Excel | `.xlsx`, `.xls` | xlsx |
212
+ | Microsoft Excel | `.xlsx`, `.xls` | exceljs |
166
213
  | Text Files | `.txt`, `.md`, `.rtf` | Native fs |
167
214
 
168
215
  ## File Templates
169
216
 
170
- Choose from specialized templates for different file types:
171
-
172
217
  | Template | Pattern | Example Output | When to Use |
173
218
  |----------|---------|----------------|-------------|
174
- | `general` | `{content}` | `meeting-notes-q4-2024.pdf` | Default - simple descriptive names |
219
+ | `general` | `{content}` | `meeting-notes-q4-2024.pdf` | Default simple descriptive names |
175
220
  | `document` | `{content}-{name}-{date}` | `driving-license-john-20250905.pdf` | Personal documents, contracts, certificates |
176
221
  | `movie` | `{content}-{year}` | `the-dark-knight-2008.mkv` | Movie files with release year |
177
222
  | `series` | `{content}-s{season}e{episode}` | `breaking-bad-s01e01.mkv` | TV series episodes |
@@ -182,94 +227,67 @@ Choose from specialized templates for different file types:
182
227
 
183
228
  ## AI Provider Setup
184
229
 
185
- ### Local LLMs (Privacy-First, No API Keys)
230
+ ### Local LLMs (no API keys required)
186
231
 
187
- **Ollama** - Recommended for privacy
232
+ **Ollama**
188
233
  1. Install: Download from [ollama.ai](https://ollama.ai)
189
234
  2. Start server: `ollama serve`
190
- 3. Pull model: `ollama pull llama3.1` (or your preferred model)
235
+ 3. Pull a model: `ollama pull llama3.1`
191
236
  4. Use: `--provider ollama`
192
237
 
193
- **LMStudio** - User-friendly interface
238
+ **LMStudio**
194
239
  1. Install: Download from [lmstudio.ai](https://lmstudio.ai)
195
240
  2. Download and load a model in LMStudio
196
- 3. Enable "Local Server" mode in LMStudio
241
+ 3. Enable "Local Server" mode
197
242
  4. Use: `--provider lmstudio`
198
243
 
199
- ### Cloud Providers (Require API Keys)
244
+ ### Cloud Providers (API keys required)
200
245
 
201
- **Claude (Anthropic)** - Recommended for accuracy
246
+ **Claude (Anthropic)** recommended for accuracy
202
247
  1. Visit [Anthropic Console](https://console.anthropic.com/)
203
- 2. Create an account and generate an API key
204
- 3. Set as environment variable: `export CLAUDE_API_KEY=your-key`
248
+ 2. Generate an API key
249
+ 3. `export ANTHROPIC_API_KEY=your-key`
205
250
 
206
251
  **OpenAI**
207
- 1. Visit [OpenAI Platform](https://platform.openai.com/api-keys)
252
+ 1. Visit [OpenAI Platform](https://platform.openai.com/api-keys)
208
253
  2. Create an API key
209
- 3. Set as environment variable: `export OPENAI_API_KEY=your-key`
210
-
211
- ### Quick Start by Privacy Preference
212
-
213
- **Maximum Privacy (Local Processing):**
214
- ```bash
215
- # Setup Ollama
216
- ollama serve
217
- ollama pull llama3.1
218
-
219
- # Use locally - no data leaves your machine
220
- namewise rename ./documents --provider ollama --dry-run
221
- ```
254
+ 3. `export OPENAI_API_KEY=your-key`
222
255
 
223
- **Balanced (Cloud with API key):**
224
- ```bash
225
- # Use Claude for best accuracy
226
- export CLAUDE_API_KEY=your-key
227
- namewise rename ./documents --provider claude --dry-run
228
- ```
256
+ ## How It Works
229
257
 
230
- > **Tip**: Local LLMs require no API keys and keep your data private. Cloud providers may offer better accuracy but require API keys and send data externally.
258
+ 1. **File Discovery**: Scans directory (recursively if `--recursive`) for supported file types
259
+ 2. **Content Extraction**: Uses specialized parsers to extract text; falls back to vision AI for scanned PDFs
260
+ 3. **AI Processing**: Sends content to the configured AI provider for filename suggestions
261
+ 4. **Template & Convention**: Applies the chosen category template and naming convention
262
+ 5. **Conflict Resolution**: If the target name exists, auto-numbers (`-2`, `-3`, …)
263
+ 6. **Rename / Preview**: Renames files on disk, or shows a preview in dry-run mode
264
+ 7. **History**: Saves the session to `~/.namewise/history.json` for later undo
231
265
 
232
- ## How It Works
266
+ ## Safety Features
233
267
 
234
- ```mermaid
235
- graph LR
236
- A[ Scan Directory] --> B[ Parse Content]
237
- B --> C[ AI Analysis]
238
- C --> D[️ Generate Name]
239
- D --> E[ Validate & Rename]
240
- ```
241
-
242
- 1. ** File Discovery**: Scans directory for supported file types
243
- 2. ** Content Extraction**: Uses specialized parsers to extract text content
244
- 3. ** AI Processing**: Sends content to AI provider for filename suggestions
245
- 4. **️ Filename Generation**: Creates clean, kebab-case names
246
- 5. ** Safety Checks**: Validates conflicts and performs renaming
247
-
248
- ## ️ Safety Features
249
-
250
- - **Dry Run Mode**: Always preview changes first
251
- - **File Size Limits**: Prevents processing overly large files
252
- - **Conflict Detection**: Won't overwrite existing files
253
- - **Error Handling**: Graceful handling of parsing and API errors
254
- - **Extension Preservation**: Keeps original file extensions
255
- - **Comprehensive Testing**: 325 tests with 100% coverage
268
+ - **Dry Run Mode**: Always preview changes first with `--dry-run`
269
+ - **Undo**: Reverse any session with `namewise undo`
270
+ - **Conflict Auto-Numbering**: Never overwrites an existing file
271
+ - **File Size Limits**: Skips files above `--max-size`
272
+ - **Extension Preservation**: Original file extensions are never changed
273
+ - **Comprehensive Testing**: 428 tests with 100% coverage
256
274
 
257
275
  ## Testing & Development
258
276
 
259
277
  ```bash
260
278
  # Development
261
- npm run dev # Run in development mode
262
- npm run build # Build TypeScript
263
- npm start # Run built version
279
+ npm run dev # Run in development mode
280
+ npm run build # Build TypeScript
281
+ npm start # Run built version
264
282
 
265
- # Testing
266
- npm test # Run all tests
283
+ # Testing
284
+ npm test # Run all tests (watch mode)
285
+ npm run test:run # Run tests once
267
286
  npm run test:coverage # Coverage report
268
- npm run test:ui # Interactive test UI
287
+ npm run test:unit # Unit tests only
288
+ npm run test:integration # Integration tests only
269
289
  ```
270
290
 
271
- The project includes comprehensive tests with 325 test cases covering all functionality except AI API calls (which are mocked).
272
-
273
291
  ## Contributing
274
292
 
275
293
  1. Fork the repository
@@ -281,10 +299,9 @@ The project includes comprehensive tests with 325 test cases covering all functi
281
299
  ## Requirements
282
300
 
283
301
  - **Node.js**: 20.0.0 or higher
284
- - **TypeScript**: 5.0.0 or higher
285
302
  - **AI Provider**: Choose one:
286
- - **Local**: Ollama or LMStudio (no API key needed)
287
- - **Cloud**: Claude (Anthropic) or OpenAI API key
303
+ - **Local**: Ollama or LMStudio (no API key needed)
304
+ - **Cloud**: Claude (Anthropic) or OpenAI API key
288
305
 
289
306
  ## Troubleshooting
290
307
 
@@ -292,36 +309,32 @@ The project includes comprehensive tests with 325 test cases covering all functi
292
309
  <summary>Common Issues</summary>
293
310
 
294
311
  **PDF parsing errors:**
295
- - Ensure PDF is not password protected
296
- - Check file is not corrupted
297
- - Try reducing max-size limit
312
+ - Ensure the PDF is not password protected
313
+ - Check the file is not corrupted
314
+ - Try reducing the `--max-size` limit
298
315
 
299
- **API errors (Cloud providers):**
300
- - Verify API key is valid
301
- - Check internet connection
316
+ **API errors (cloud providers):**
317
+ - Verify the API key is valid
318
+ - Check your internet connection
302
319
  - Ensure sufficient API credits
303
320
 
304
321
  **Local LLM connection errors:**
305
322
  - Ensure Ollama server is running (`ollama serve`)
306
323
  - Check LMStudio local server is enabled
307
324
  - Verify correct base URL and port
308
- - Confirm model is loaded/available
325
+ - Confirm the model is loaded and available
309
326
 
310
327
  **Permission errors:**
311
328
  - Check file permissions
312
329
  - Run with appropriate user privileges
313
- - Ensure files aren't in use by other applications
330
+ - Ensure files are not open in another application
314
331
 
315
332
  </details>
316
333
 
317
334
  ## License
318
335
 
319
- [MIT License](./LICENSE) - Feel free to use, modify, and distribute this project.
336
+ [MIT License](./LICENSE) Feel free to use, modify, and distribute this project.
320
337
 
321
338
  ---
322
339
 
323
- <div align="center">
324
- <strong>⭐ Star this repo if it helped you organize your files! ⭐</strong>
325
-
326
340
  [Report Bug](https://github.com/amirdaraee/namewise/issues) • [Request Feature](https://github.com/amirdaraee/namewise/issues)
327
- </div>
@@ -1 +1 @@
1
- {"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/cli/commands.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA4DpD"}
1
+ {"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/cli/commands.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA8EpD"}