0
# File Cleanup
1

2
Utility for safely removing build artifacts and temporary files with glob pattern support and security safeguards.
3

4
## Capabilities
5

6
### lb-clean Command
7

8
Safely removes files and directories using glob patterns with built-in security checks.
9

10
```typescript { .api }
11
/**
12
 * File cleanup function with glob pattern support and safety checks
13
 * @param argv - Command line arguments including file patterns to remove
14
 * @param options - Execution options for dry run and process control
15
 * @returns String description of removed files
16
 */
17
function clean(argv: string[], options?: RunOptions): string;
18
```
19

20
**CLI Usage:**
21

22
```bash
23
# Remove build directories
24
lb-clean dist lib
25

26
# Remove with glob patterns
27
lb-clean "dist/**" "*.tmp"
28

29
# Remove multiple patterns
30
lb-clean dist coverage temp "*.log"
31

32
# Common cleanup patterns
33
lb-clean dist lib coverage *.tsbuildinfo
34
```
35

36
**Programmatic Usage:**
37

38
```typescript
39
import { clean } from "@loopback/build";
40

41
// Remove build artifacts
42
const result = clean(["dist", "lib"]);
43
console.log(result); // "rm -rf dist lib"
44

45
// Dry run to see what would be removed
46
const dryResult = clean(["dist", "coverage"], { dryRun: true });
47
console.log(dryResult); // "rm -rf dist coverage"
48

49
// Remove files in custom directory
50
const cleanResult = clean(["build"], { cwd: "/path/to/project" });
51
```
52

53
### Security Safeguards
54

55
Built-in protection against accidentally removing files outside the project directory.
56

57
```typescript { .api }
58
// Prevents removal of files outside project root using path traversal (../)
59
// Skips patterns that resolve outside current working directory
60
// Logs warning messages for skipped patterns
61
```
62

63
**Security Features:**
64
- Checks all patterns for path traversal attempts (`../`)
65
- Only removes files within the current working directory
66
- Warns when patterns are skipped for security reasons
67
- Never follows symbolic links outside the project
68

69
**Security Examples:**
70

71
```bash
72
# Safe - removes dist directory in current project
73
lb-clean dist
74

75
# Skipped - would access parent directory
76
lb-clean ../dist
77

78
# Safe - removes nested directories
79
lb-clean src/temp lib/cache
80

81
# Skipped - path traversal attempt
82
lb-clean "../../system-files"
83
```
84

85
### Glob Pattern Support
86

87
Comprehensive glob pattern support for flexible file matching.
88

89
```typescript { .api }
90
interface GlobPatterns {
91
  "**": "Recursive directory match";
92
  "*": "Single directory/file wildcard";
93
  "?": "Single character wildcard";
94
  "[abc]": "Character set matching";
95
  "{a,b,c}": "Alternative matching";
96
  "!pattern": "Negation (not supported in lb-clean)";
97
}
98
```
99

100
**Pattern Examples:**
101

102
```bash
103
# Remove all JavaScript files
104
lb-clean "**/*.js"
105

106
# Remove all build artifacts
107
lb-clean "dist/**" "lib/**" "coverage/**"
108

109
# Remove temporary files
110
lb-clean "*.tmp" "*.log" ".cache"
111

112
# Remove TypeScript build info
113
lb-clean "*.tsbuildinfo" "**/*.tsbuildinfo"
114

115
# Remove test artifacts
116
lb-clean "**/*.test.js.map" "**/coverage-*"
117
```
118

119
### Usage Examples
120

121
**Basic Cleanup:**
122

123
```typescript
124
import { clean } from "@loopback/build";
125

126
// Remove common build directories
127
const result = clean(["dist", "lib", "coverage"]);
128

129
// Remove with glob patterns
130
const globResult = clean(["dist/**", "*.tsbuildinfo"]);
131

132
// Check what would be removed
133
const dryRun = clean(["temp", "cache"], { dryRun: true });
134
console.log(`Would execute: ${dryRun}`);
135
```
136

137
**Package.json Integration:**
138

139
```json
140
{
141
  "scripts": {
142
    "clean": "lb-clean dist lib coverage *.tsbuildinfo",
143
    "clean:all": "lb-clean dist lib coverage temp cache *.log *.tmp",
144
    "clean:build": "lb-clean dist lib",
145
    "clean:coverage": "lb-clean coverage .nyc_output",
146
    "clean:cache": "lb-clean .cache node_modules/.cache",
147
    "prebuild": "npm run clean",
148
    "pretest": "npm run clean && npm run build"
149
  }
150
}
151
```
152

153
**Common Cleanup Patterns:**
154

155
```bash
156
# TypeScript project cleanup
157
lb-clean dist lib *.tsbuildinfo
158

159
# Node.js project cleanup  
160
lb-clean dist coverage .nyc_output *.log
161

162
# Full cleanup (preserve node_modules)
163
lb-clean dist lib coverage temp .cache *.tmp *.log *.tsbuildinfo
164

165
# Cache cleanup
166
lb-clean .cache .nyc_output coverage
167

168
# Development cleanup
169
lb-clean "**/*.js.map" "**/*.d.ts" "!node_modules/**"
170
```
171

172
### Error Handling and Logging
173

174
Comprehensive error handling with informative logging.
175

176
```typescript { .api }
177
// Logs each pattern being processed
178
// Warns about skipped patterns with reasons
179
// Reports successful removals
180
// Handles permission errors gracefully
181
```
182

183
**Error Scenarios:**
184
- **Path traversal**: Logs warning and skips pattern
185
- **Permission denied**: Reports error but continues with other patterns
186
- **File not found**: Silent (not an error)
187
- **Invalid glob pattern**: Reports error and skips pattern
188

189
**Logging Examples:**
190

191
```bash
192
$ lb-clean dist ../config temp
193
# Output:
194
# Skipping ../config as it is not inside the project root directory.
195
# rm -rf dist temp
196
```
197

198
### Integration with Build Tools
199

200
Seamlessly integrates with build processes and development workflows.
201

202
**Build Process Integration:**
203

204
```json
205
{
206
  "scripts": {
207
    "prebuild": "lb-clean dist",
208
    "build": "lb-tsc",
209
    "postbuild": "lb-clean **/*.tsbuildinfo",
210
    
211
    "pretest": "npm run build",
212
    "test": "lb-mocha dist/__tests__",
213
    "posttest": "lb-clean .nyc_output",
214
    
215
    "prepublishOnly": "npm run clean && npm run build && npm test"
216
  }
217
}
218
```
219

220
**Watch Mode Compatibility:**
221

222
```bash
223
# Safe for watch mode - only removes build outputs
224
lb-clean dist
225

226
# Avoid cleaning source files in watch mode
227
# Good: lb-clean dist lib
228
# Bad: lb-clean src (would remove source files)
229
```
230

231
### Performance Considerations
232

233
Optimized for performance with large file sets and complex glob patterns.
234

235
```typescript { .api }
236
// Uses rimraf for efficient file removal
237
// Processes patterns in parallel where safe
238
// Handles large directory trees efficiently
239
// Minimizes file system operations
240
```
241

242
**Performance Tips:**
243
- Use specific patterns instead of broad globs when possible
244
- Clean directories rather than individual files when appropriate
245
- Combine related patterns in single command
246
- Avoid deeply nested recursive patterns when unnecessary
247

248
### Advanced Usage
249

250
Advanced patterns and use cases for complex project structures.
251

252
**Monorepo Cleanup:**
253

254
```bash
255
# Clean all package build outputs
256
lb-clean "packages/*/dist" "packages/*/lib"
257

258
# Clean all test artifacts
259
lb-clean "packages/*/coverage" "**/.nyc_output"
260

261
# Clean TypeScript artifacts
262
lb-clean "**/*.tsbuildinfo" "packages/*/tsconfig.tsbuildinfo"
263
```
264

265
**Conditional Cleanup:**
266

267
```json
268
{
269
  "scripts": {
270
    "clean:dev": "lb-clean dist coverage .cache",
271
    "clean:prod": "lb-clean dist lib coverage .nyc_output *.log",
272
    "clean": "npm run clean:dev"
273
  }
274
}
275
```
276

277
**Custom Cleanup Functions:**
278

279
```typescript
280
import { clean } from "@loopback/build";
281

282
// Create cleanup utility
283
function cleanBuildArtifacts() {
284
  return clean(["dist", "lib", "*.tsbuildinfo"], { dryRun: false });
285
}
286

287
function cleanTestArtifacts() {  
288
  return clean(["coverage", ".nyc_output"], { dryRun: false });
289
}
290

291
// Use in build scripts
292
cleanBuildArtifacts();
293
cleanTestArtifacts();
294
```