🧹 Workspace Cleanup Workflow (Linux Standard)

This workflow maintains the health, speed, and hygiene of the local developer workspace. It targets redundant build caches, compiler logs, Python bytecode, and temporary draft files.

WARNING

Always verify that your active draft files in scratch/ are either committed, promoted to production, or no longer needed before executing deep cleanup routines.

---

🚀 1. Automated Cleanup (Recommended)

A self-contained Bash automation utility has been established at scripts/project-cleanup.sh. This script safely handles all cleanup phases with built-in safety prompts and dry-run previews.

A. Preview Changes (Dry-Run)

To see exactly what files and folders would be deleted before actually deleting them:

./scripts/project-cleanup.sh --dry-run

B. Safe/Routine Clean (Default)

Removes VitePress build folders, dev server caches, Python bytecode directories, TypeScript compilation logs, and prunes stale draft files in scratch/ older than 14 days. It also removes the JSON lockfile (package-lock.json) as requested for a completely fresh start.

./scripts/project-cleanup.sh --safe

C. Deep Clean (Destructive Environment Wipe)

Performs all standard clean actions, completely wipes the scratch/ directory, and deletes all node_modules/ folders to resolve caching errors or start fresh.

./scripts/project-cleanup.sh --deep

IMPORTANT

After running a --deep clean, you MUST run npm install at the workspace root to restore all dependencies.

---

🛠️ 2. Manual Bash Command Equivalents

For maximum transparency and troubleshooting, here are the raw Linux terminal commands utilized under the hood:

Routine Clean (Safe)

# 1. Remove VitePress build output and caches
rm -rf docs/.vitepress/dist
rm -rf docs/.vitepress/cache
rm -rf workspaces/data-backup/dist

# 2. Remove TypeScript compilation build info
find . -name "*.tsbuildinfo" -not -path "*/node_modules/*" -delete

# 3. Clean Python bytecode and caches
find . -type d -name "__pycache__" -not -path "*/node_modules/*" -exec rm -rf {} + 2>/dev/null
find . -type f -name "*.pyc" -not -path "*/node_modules/*" -delete 2>/dev/null

# 4. Remove JSON Lockfiles
rm -f package-lock.json

# 5. Clean log files
find . -name "*.log" -not -path "*/.git/*" -not -path "*/node_modules/*" -delete 2>/dev/null

# 6. Prune scratch drafts older than 14 days
find scratch -type f -mtime +14 -delete 2>/dev/null

Deep Clean (Destructive)

# 1. Completely wipe scratch/ folder
rm -rf scratch

# 2. Delete all node modules
rm -rf node_modules
rm -rf workspaces/data-backup/node_modules

---

🛡️ 3. Scratchpad Best Practices

• Git Security: The scratch/ folder is actively ignored by .gitignore so your private draft scripts, keys, and logs can never be accidentally committed to GitHub.
• Promotion Flow: When an experimental draft inside scratch/ proves its long-term value, promote it by moving it to scripts/ or library/, then safely delete the scratch version.