Reorganize repository structure and clean up documentation
Clean up and organize the flask-shopdb repository for better maintainability and discoverability: ## Changes - Update .gitignore for build artifacts (publish/, data/, 122M total) - Reorganize .claude/ into 6 subdirectories with README navigation - Consolidate overlapping MCP setup guides into MCP-QUICK-START.md - Move deployment docs from root to docs/deployment/ - Archive dated status reports to .claude/archived/ - Delete temporary files (logs, backups, empty reports, ~50K) ## New Structure .claude/ organized into: - setup/ - MCP, VM, Hyper-V, GitHub setup guides + scripts (17 files) - plans/ - Feature plans and protocols (5 files) - maintenance/ - Deployment checklists and reports (4 files) - archived/ - Historical documentation (9 files) - skills/ - Claude Code automation (5 files) - workflows/ - Security audit workflow (1 file) docs/deployment/ created with 6 deployment guides: - LOCAL-DEV-SETUP.md, DOCKER-SETUP.md, DOCKER-PREBUILT-APPROACH.md - PRODUCTION-READINESS.md, DEPLOY-TO-VM.md, README.md Root directory cleaned to essential docs only: - CLAUDE.md, README.md, CONTRIBUTING.md, CHANGELOG.md Benefits: - Clear navigation via README.md in each subdirectory - No duplicate/overlapping documentation - Large artifacts properly gitignored (won't bloat repository) - Historical context preserved in archived/ See .claude/CLEANUP-SUMMARY.md for complete details. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Proudlock
78
.claude/skills/README.md
Normal file
78
.claude/skills/README.md
Normal file
@@ -0,0 +1,78 @@
|
||||
# ShopDB Skills
|
||||
|
||||
Custom slash commands for common workflows.
|
||||
|
||||
## Available Skills
|
||||
|
||||
### `/build-agent`
|
||||
Build and publish agent and tray executables to Documents/shopdb-builds folder.
|
||||
|
||||
**When to use:** After making changes to agent or tray C# code, before deployment.
|
||||
|
||||
**What it does:**
|
||||
- Compiles both executables
|
||||
- Creates dated folder in Documents
|
||||
- Generates VERSION.txt with release notes
|
||||
- Copies .exe files ready for deployment
|
||||
|
||||
### `/merge-wilm`
|
||||
Merge latest wilm branch commits into wj with proper conflict resolution.
|
||||
|
||||
**When to use:** Periodically to bring wilm improvements into wj prod branch.
|
||||
|
||||
**What it does:**
|
||||
- Fetches latest from origin
|
||||
- Shows commits to be merged
|
||||
- Handles common conflicts (csproj, routes.py)
|
||||
- Coordinates agent/tray versions
|
||||
- Creates merge commit
|
||||
|
||||
### `/deploy-frontend`
|
||||
Build frontend and deploy to prod server via Y drive.
|
||||
|
||||
**When to use:** After making Vue/frontend changes that need to go to production.
|
||||
|
||||
**What it does:**
|
||||
- Runs production build with correct VITE_BASE_PATH
|
||||
- Copies dist/ to Y: drive
|
||||
- Provides instructions for IIS restart
|
||||
- Verifies build output
|
||||
|
||||
### `/test-changes`
|
||||
Run pytest and frontend build checks before committing.
|
||||
|
||||
**When to use:** Before claiming work is complete or pushing commits.
|
||||
|
||||
**What it does:**
|
||||
- Runs pytest for backend
|
||||
- Builds frontend to catch errors
|
||||
- Runs style/naming checker
|
||||
- Provides targeted test commands
|
||||
|
||||
## How Skills Work
|
||||
|
||||
Skills are markdown files that provide structured instructions. When you type `/skill-name`, Claude:
|
||||
1. Loads the skill instructions
|
||||
2. Follows the steps defined in the skill
|
||||
3. Adapts to the current situation
|
||||
|
||||
Skills save tokens by avoiding repeated explanations of common workflows.
|
||||
|
||||
## Tips
|
||||
|
||||
- Use skills for repetitive tasks
|
||||
- Skills preserve context about your environment
|
||||
- You can still ask Claude to deviate from skill steps if needed
|
||||
- Skills work best when the workflow is consistent
|
||||
|
||||
## Adding New Skills
|
||||
|
||||
Create a new `.md` file in `.claude/skills/` with:
|
||||
```markdown
|
||||
---
|
||||
name: skill-name
|
||||
description: Brief description
|
||||
---
|
||||
|
||||
Instructions for Claude to follow...
|
||||
```
|
||||
49
.claude/skills/build-agent.md
Normal file
49
.claude/skills/build-agent.md
Normal file
@@ -0,0 +1,49 @@
|
||||
---
|
||||
name: build-agent
|
||||
description: Build and publish ShopDB agent and tray executables to Documents folder
|
||||
---
|
||||
|
||||
Build the ShopDB endpoint agent and tray applications, then copy them to Documents/shopdb-builds with version information.
|
||||
|
||||
## Steps
|
||||
|
||||
1. Navigate to agent directory: `C:\Users\270015376\Documents\github\flask-shopdb\agent`
|
||||
|
||||
2. Publish the agent service:
|
||||
```
|
||||
dotnet publish ShopDbEndpointAgent/ShopDbEndpointAgent.csproj -c Release -o publish/agent
|
||||
```
|
||||
|
||||
3. Publish the tray application:
|
||||
```
|
||||
dotnet publish ShopDbEndpointAgent.Tray/ShopDbEndpointAgent.Tray.csproj -c Release -o publish/tray
|
||||
```
|
||||
|
||||
4. Create dated build folder:
|
||||
```
|
||||
mkdir -p C:/Users/270015376/Documents/shopdb-builds/$(date +%Y%m%d)
|
||||
```
|
||||
|
||||
5. Copy executables to build folder:
|
||||
- `publish/agent/shopdbagent.exe`
|
||||
- `publish/tray/shopdb-endpoint-tray.exe`
|
||||
|
||||
6. Create VERSION.txt with:
|
||||
- Agent version from ShopDbEndpointAgent.csproj
|
||||
- Tray version from ShopDbEndpointAgent.Tray.csproj
|
||||
- Git commit hash (short)
|
||||
- Branch name
|
||||
- Summary of changes in this release
|
||||
|
||||
## Expected Output
|
||||
|
||||
- Executables in: `C:\Users\270015376\Documents\shopdb-builds\YYYYMMDD\`
|
||||
- shopdbagent.exe (typically ~35MB)
|
||||
- shopdb-endpoint-tray.exe (typically ~69MB)
|
||||
- VERSION.txt with release notes
|
||||
|
||||
## Notes
|
||||
|
||||
- Agent and tray versions must be coordinated (bumped together)
|
||||
- If tray publish fails with "file in use", the agent build is still running - wait and retry
|
||||
- Build takes 2-3 minutes total
|
||||
72
.claude/skills/deploy-frontend.md
Normal file
72
.claude/skills/deploy-frontend.md
Normal file
@@ -0,0 +1,72 @@
|
||||
---
|
||||
name: deploy-frontend
|
||||
description: Build frontend and deploy to prod server via Y drive
|
||||
---
|
||||
|
||||
Build the Vue 3 frontend with production settings and copy to the Y drive for prod server deployment.
|
||||
|
||||
## Steps
|
||||
|
||||
1. Navigate to frontend directory:
|
||||
```
|
||||
cd C:\Users\270015376\Documents\github\flask-shopdb\frontend
|
||||
```
|
||||
|
||||
2. Run production build:
|
||||
```
|
||||
build-prod.cmd
|
||||
```
|
||||
This runs `npm run build` with `VITE_BASE_PATH=/shopdb/` environment variable.
|
||||
|
||||
3. Verify build output:
|
||||
```
|
||||
ls -lh dist/
|
||||
```
|
||||
Should see index.html, assets/, and other bundled files.
|
||||
|
||||
4. Copy to Y drive (prod server):
|
||||
```
|
||||
update-prod-server.cmd
|
||||
```
|
||||
This copies frontend/dist/ to Y:/frontend/ (the SMB share that syncs to prod).
|
||||
|
||||
5. Restart IIS app pool on prod server:
|
||||
- Connect to prod server
|
||||
- Restart "ShopDB" application pool
|
||||
- Or use remote command if configured
|
||||
|
||||
## Files and Paths
|
||||
|
||||
**Work PC (this machine)**:
|
||||
- Source: `C:\Users\270015376\Documents\github\flask-shopdb\frontend`
|
||||
- Build output: `frontend/dist/`
|
||||
|
||||
**Y Drive (SMB share)**:
|
||||
- Target: `Y:/frontend/`
|
||||
- This is the staging area that syncs to prod
|
||||
|
||||
**Prod Server**:
|
||||
- Final location: `/shopdb/` (served by IIS)
|
||||
- Access via: `https://tsgwp00525.wjs.geaerospace.net/shopdb/`
|
||||
|
||||
## Important Notes
|
||||
|
||||
- Frontend must be built on THIS PC (work PC has the right environment)
|
||||
- Build output goes to frontend/dist/
|
||||
- Y: drive is an SMB share mounted on this machine
|
||||
- After copy to Y:, restart the IIS app pool on prod server
|
||||
- Always test after deployment by loading the shopdb webpage
|
||||
|
||||
## Common Issues
|
||||
|
||||
- **White screen**: Frontend build path wrong, check VITE_BASE_PATH
|
||||
- **Assets not loading**: Check dist/ was fully copied to Y:
|
||||
- **Stale cache**: Hard refresh browser (Ctrl+F5)
|
||||
|
||||
## Deployment Workflow
|
||||
|
||||
1. Make frontend changes
|
||||
2. Commit to git
|
||||
3. Run this skill to build and deploy
|
||||
4. Restart IIS app pool
|
||||
5. Test in browser
|
||||
82
.claude/skills/merge-wilm.md
Normal file
82
.claude/skills/merge-wilm.md
Normal file
@@ -0,0 +1,82 @@
|
||||
---
|
||||
name: merge-wilm
|
||||
description: Merge wilm branch into wj with proper version coordination
|
||||
---
|
||||
|
||||
Merge the latest commits from wilm branch into wj branch, resolving common conflicts and coordinating agent/tray versions.
|
||||
|
||||
## Steps
|
||||
|
||||
1. Ensure we're on wj branch and up to date:
|
||||
```
|
||||
git checkout wj
|
||||
git fetch origin
|
||||
```
|
||||
|
||||
2. Check what's new on wilm:
|
||||
```
|
||||
git log wj..origin/wilm --oneline
|
||||
```
|
||||
Show the user what commits will be merged.
|
||||
|
||||
3. Attempt the merge:
|
||||
```
|
||||
git merge origin/wilm --no-edit
|
||||
```
|
||||
|
||||
4. If conflicts occur (common files):
|
||||
- **agent/ShopDbEndpointAgent/ShopDbEndpointAgent.csproj**: Most common conflict
|
||||
- **plugins/endpoints/api/routes.py**: If both branches touched operator reports or fleet alerts
|
||||
|
||||
5. Resolve csproj conflicts:
|
||||
- Keep ALL version history comments from both branches
|
||||
- Merge version numbers by taking higher version and bumping patch
|
||||
- Example: wj has 1.13.5, wilm has 1.14.0 → result is 1.14.1 or 1.14.2
|
||||
- Add merge comment explaining what was combined
|
||||
|
||||
6. Resolve routes.py conflicts:
|
||||
- Usually wilm has infrastructure changes, wj has feature changes
|
||||
- Preserve both sets of changes
|
||||
- Check imports at top of file are complete
|
||||
|
||||
7. Stage resolved files and commit:
|
||||
```
|
||||
git add <resolved-files>
|
||||
git commit -m "Merge wilm into wj"
|
||||
```
|
||||
|
||||
8. Bump tray version to match agent:
|
||||
- Edit ShopDbEndpointAgent.Tray/ShopDbEndpointAgent.Tray.csproj
|
||||
- Add version comment
|
||||
- Commit separately
|
||||
|
||||
9. Show summary:
|
||||
```
|
||||
git log --oneline --graph -10
|
||||
```
|
||||
|
||||
## Common Conflicts
|
||||
|
||||
**Agent csproj version block**:
|
||||
- Preserve all version history from both branches
|
||||
- Increment version number combining both
|
||||
- Document what was merged
|
||||
|
||||
**Operator report email function**:
|
||||
- wilm usually refactors structure
|
||||
- wj usually adds features (FQDN, machine relationships)
|
||||
- Combine both approaches
|
||||
|
||||
## Version Numbering Rules
|
||||
|
||||
- Agent and tray MUST be bumped together
|
||||
- Format: X.Y.Z
|
||||
- Merge scenarios:
|
||||
- wj 1.13.5 + wilm 1.14.0 → 1.14.1 (take wilm minor, bump patch)
|
||||
- Add comment: "Merge wilm X.Y.Z changes with wj coordination releases"
|
||||
|
||||
## Notes
|
||||
|
||||
- Always review the wilm commits before merging
|
||||
- Test after merge if possible
|
||||
- Tray version lags agent by pattern: agent 1.14.2 pairs with tray 1.6.8
|
||||
101
.claude/skills/test-changes.md
Normal file
101
.claude/skills/test-changes.md
Normal file
@@ -0,0 +1,101 @@
|
||||
---
|
||||
name: test-changes
|
||||
description: Run tests for recent changes before committing
|
||||
---
|
||||
|
||||
Run pytest for backend changes and check frontend builds successfully. Always run before claiming work is complete.
|
||||
|
||||
## Backend Tests
|
||||
|
||||
1. Navigate to repo root:
|
||||
```
|
||||
cd C:\Users\270015376\Documents\github\flask-shopdb
|
||||
```
|
||||
|
||||
2. Run full test suite:
|
||||
```
|
||||
pytest -v
|
||||
```
|
||||
|
||||
3. If focusing on specific plugin:
|
||||
```
|
||||
pytest tests/test_plugins/test_endpoints*.py -v
|
||||
pytest tests/test_plugins/test_notifications*.py -v
|
||||
```
|
||||
|
||||
4. For migration tests:
|
||||
```
|
||||
pytest tests/test_plugin_migrations.py -v
|
||||
```
|
||||
|
||||
## Frontend Checks
|
||||
|
||||
1. Navigate to frontend:
|
||||
```
|
||||
cd C:\Users\270015376\Documents\github\flask-shopdb\frontend
|
||||
```
|
||||
|
||||
2. Run frontend build to catch errors:
|
||||
```
|
||||
npm run build
|
||||
```
|
||||
This will catch Vue template errors, TypeScript issues, etc.
|
||||
|
||||
3. If tests exist:
|
||||
```
|
||||
npm test
|
||||
```
|
||||
|
||||
## Pre-Commit Checks
|
||||
|
||||
Run the naming/style checker:
|
||||
```
|
||||
./scripts/check-naming-and-style.sh
|
||||
```
|
||||
|
||||
This verifies:
|
||||
- Database table names are lowercase concatenated
|
||||
- No unicode/emojis in code
|
||||
- Column names are snake_case
|
||||
|
||||
## What to Check Based on Changes
|
||||
|
||||
**Database migrations**:
|
||||
- Run `pytest tests/test_plugin_migrations.py -v`
|
||||
- Verify migration runs forward and backward
|
||||
- Check no JSONB (use TEXT for MySQL)
|
||||
|
||||
**API endpoints**:
|
||||
- Run tests for the specific plugin
|
||||
- Test authentication/authorization
|
||||
- Check XSS escaping if handling user input
|
||||
|
||||
**Frontend components**:
|
||||
- Run `npm run build` to catch template errors
|
||||
- Check browser console for runtime errors
|
||||
- Test in actual browser if UI change
|
||||
|
||||
**Agent/Tray**:
|
||||
- Build with `dotnet build` to catch compile errors
|
||||
- No automated tests yet, test manually
|
||||
|
||||
## Common Test Failures
|
||||
|
||||
**Migration conflicts**:
|
||||
- Two branches both added migrations
|
||||
- Renumber the newer one
|
||||
|
||||
**Import errors**:
|
||||
- Missing `from shopdb.api import ...`
|
||||
- Should use API surface, not internal imports
|
||||
|
||||
**Database name violations**:
|
||||
- Table name has underscores (should be concatenated lowercase)
|
||||
- Column name not snake_case
|
||||
|
||||
## Notes
|
||||
|
||||
- Tests must pass before pushing to origin
|
||||
- Frontend build must complete without errors
|
||||
- Style checker must pass
|
||||
- Manual testing for agent/tray changes
|
||||
Reference in New Issue
Block a user