Skip to content

Commit ca9de66

Browse files
Copilotcubap
Copilot
and
cubap
authored
Add comprehensive GitHub Copilot instructions for TPEN-services repository (#304)
* Initial plan * Complete GitHub Copilot instructions with comprehensive validation Co-authored-by: cubap <1119165+cubap@users.noreply.github.com> * Update copilot instructions with branching guidelines Added guidelines for branching and hotfixes. --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: cubap <1119165+cubap@users.noreply.github.com> Co-authored-by: Patrick Cuba <cubap@slu.edu>
1 parent ce7a26a commit ca9de66

1 file changed

Lines changed: 204 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# TPEN Services
2+
3+
TPEN Services is a Node.js Express API service for TPEN3 (Transcription for Paleographical and Editorial Notation). This provides RESTful APIs for digital humanities, cultural heritage, annotation services, and IIIF manifest handling. The service supports multiple database backends (MongoDB, MariaDB) and uses Auth0 for authentication.
4+
5+
Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
6+
7+
## Working Effectively
8+
9+
### Bootstrap, Build, and Test the Repository
10+
- Copy environment configuration: `cp sample.env .env`
11+
- Install dependencies: `npm install` -- takes up to 20 seconds. NEVER CANCEL. Set timeout to 60+ seconds.
12+
- Run unit tests: `npm run unitTests` -- takes 12 seconds. NEVER CANCEL. Set timeout to 30+ seconds.
13+
- Run existence tests: `npm run existsTests` -- takes 7 seconds. NEVER CANCEL. Set timeout to 30+ seconds.
14+
- Run all tests: `npm run allTests` -- takes 12 seconds. NEVER CANCEL. Set timeout to 30+ seconds.
15+
16+
### Run the Application
17+
- ALWAYS run the bootstrapping steps first.
18+
- Production server: `npm start` -- starts on port 3001
19+
- Development server: `npm run dev` -- starts with nodemon auto-reload on port 3001
20+
- Test basic functionality: `curl http://localhost:3001/` should return "TPEN3 SERVICES BABY!!!"
21+
22+
### Environment Requirements
23+
- Node.js >= 22.14.0 (works with v20.19.4 but shows warnings)
24+
- MongoDB (for database tests and full functionality)
25+
- MariaDB (for database tests and full functionality)
26+
- Copy `sample.env` to `.env` for basic functionality
27+
- For full functionality, configure database connection strings in `.env`
28+
29+
## Validation
30+
31+
### Always Validate Core Functionality After Changes
32+
- Start the application: `npm start` or `npm run dev`
33+
- Test the root endpoint: `curl http://localhost:3001/` -- should return HTML with "TPEN3 SERVICES BABY!!!"
34+
- Run unit tests that don't require databases: `npm run unitTests` -- many tests pass without database connections
35+
- Run existence tests: `npm run existsTests` -- validates route registration and class imports
36+
- ALWAYS wait for full test completion. Tests may appear to hang but will complete within 12 seconds.
37+
- NOTE: Application may crash after serving initial requests due to database connection attempts - this is expected behavior without running MongoDB/MariaDB.
38+
39+
### Test Categories Available
40+
- `npm run unitTests` -- Core unit tests (some require databases)
41+
- `npm run existsTests` -- Route and class existence validation (database-independent)
42+
- `npm run functionsTests` -- Function-level tests
43+
- `npm run E2Etests` -- End-to-end API tests
44+
- `npm run dbTests` -- Database-specific tests (require running databases)
45+
- `npm run authTest` -- Authentication tests (require Auth0 configuration)
46+
47+
### Expected Test Behavior
48+
- Tests requiring databases will timeout/fail without MongoDB/MariaDB running
49+
- Auth tests fail without proper AUDIENCE and DOMAIN environment variables
50+
- Core functionality tests (exists, basic units) should pass with minimal `.env` setup
51+
- Database-independent tests complete in 6-15 seconds
52+
53+
## Common Tasks
54+
55+
### Repository Structure
56+
```
57+
/home/runner/work/TPEN-services/TPEN-services/
58+
├── app.js # Express application setup
59+
├── bin/tpen3_services.js # Server entry point
60+
├── package.json # Dependencies and scripts
61+
├── jest.config.js # Test configuration
62+
├── sample.env # Environment template
63+
├── API.md # API documentation
64+
├── classes/ # Domain model classes
65+
│ ├── Project/ # Project management
66+
│ ├── User/ # User management
67+
│ ├── Group/ # Group management
68+
│ ├── Layer/ # Annotation layers
69+
│ ├── Line/ # Text line handling
70+
│ ├── Page/ # Page management
71+
│ └── Manifest/ # IIIF manifest handling
72+
├── database/ # Database drivers
73+
│ ├── mongo/ # MongoDB controller
74+
│ ├── maria/ # MariaDB controller
75+
│ └── tiny/ # TinyPEN API controller
76+
├── auth/ # Auth0 authentication
77+
├── project/ # Project API routes
78+
├── manifest/ # Manifest API routes
79+
├── userProfile/ # User API routes
80+
├── line/ # Line API routes
81+
├── page/ # Page API routes
82+
└── utilities/ # Helper functions
83+
```
84+
85+
### Key API Endpoints
86+
- `GET /` -- Service status (returns "TPEN3 SERVICES BABY!!!")
87+
- `GET /project/:id` -- Get project by ID (requires authentication)
88+
- `POST /project/create` -- Create new project (requires authentication)
89+
- `POST /project/import?createFrom=URL` -- Import project from IIIF manifest
90+
- `GET /user/:id` -- Get user profile (public)
91+
- `GET /my/profile` -- Get authenticated user profile
92+
- `GET /manifest/:id` -- Get IIIF manifest
93+
- `GET /line/:id` -- Get text line annotation
94+
- `GET /page/:id` -- Get annotation page
95+
96+
### Authentication
97+
- Uses Auth0 JWT bearer tokens
98+
- Protected endpoints require `Authorization: Bearer <token>` header
99+
- Environment variables AUDIENCE and DOMAIN must be configured for auth tests
100+
- Public endpoints: `/`, `/user/:id`, `/manifest/:id`
101+
- Protected endpoints: `/project/*`, `/my/*`, most POST/PUT/DELETE operations
102+
103+
### Database Configuration
104+
- MongoDB: Configure MONGODB and MONGODBNAME in `.env`
105+
- MariaDB: Configure MARIADB, MARIADBNAME, MARIADBUSER, MARIADBPASSWORD in `.env`
106+
- TinyPEN API: Configure TINYPEN in `.env`
107+
- Default configurations in `sample.env` point to development services
108+
109+
### Development Workflow
110+
1. Always start with: `cp sample.env .env && npm install`
111+
2. Make code changes
112+
3. Test with: `npm run existsTests` (fast, database-independent)
113+
4. For database changes: ensure MongoDB/MariaDB running, then `npm run dbTests`
114+
5. For API changes: `npm run E2Etests`
115+
6. Start dev server: `npm run dev`
116+
7. Test manually: `curl http://localhost:3001/` and relevant endpoints
117+
118+
### Debugging and Troubleshooting
119+
- Application logs appear in console when running `npm start` or `npm run dev`
120+
- Database connection errors indicate missing database services
121+
- Auth errors indicate missing AUDIENCE/DOMAIN environment variables
122+
- 404 errors on routes indicate route registration issues
123+
- Check `app.js` for middleware and route registration
124+
- Jest warnings about experimental VM modules are expected (ES module usage)
125+
126+
### CI/CD Integration
127+
- GitHub Actions workflows in `.github/workflows/`
128+
- `test_pushes.yaml` runs unit tests on pushes
129+
- `ci_dev.yaml` runs E2E tests on PRs to development
130+
- Tests require environment secrets configured in GitHub repository settings
131+
132+
### Performance Notes
133+
- Application startup: 2-3 seconds
134+
- npm install: ~1-20 seconds depending on cache (timeout: 60+ seconds)
135+
- Unit tests: ~12 seconds (timeout: 30+ seconds)
136+
- Existence tests: ~7 seconds (timeout: 30+ seconds)
137+
- Database tests: variable depending on database response times
138+
139+
### Critical Environment Variables
140+
Required for basic functionality:
141+
- `PORT` (default: 3001)
142+
- `SERVERURL` (default: http://localhost:3001)
143+
144+
Required for database functionality:
145+
- `MONGODB` (MongoDB connection string)
146+
- `MONGODBNAME` (MongoDB database name)
147+
- `MARIADB` (MariaDB host)
148+
- `MARIADBNAME`, `MARIADBUSER`, `MARIADBPASSWORD` (MariaDB credentials)
149+
150+
Required for authentication:
151+
- `AUDIENCE` (Auth0 audience)
152+
- `DOMAIN` (Auth0 domain)
153+
154+
Required for external services:
155+
- `TINYPEN` (TinyPEN API base URL)
156+
- `RERUMURL` (RERUM repository URL)
157+
158+
### Manual Testing Scenarios
159+
After making changes, always validate:
160+
1. **Basic Service**: Start server with `npm start`, test with `curl http://localhost:3001/` - should return HTML containing "TPEN3 SERVICES BABY!!!" in the response body
161+
2. **Route Registration**: `npm run existsTests` passes without errors
162+
3. **Core Logic**: `npm run unitTests` passes tests that don't require databases (some MongoDB tests will timeout - this is expected)
163+
4. **API Authentication**: Protected endpoints like `/my/profile` return 401 status code without valid tokens
164+
5. **Application Behavior**: Server may crash after serving requests when MongoDB is not available - this is expected and indicates database connection attempts are working correctly
165+
166+
### Complete Validation Workflow Example
167+
```bash
168+
# Basic setup
169+
cp sample.env .env
170+
npm install
171+
172+
# Test core functionality without databases
173+
npm run existsTests # Should pass completely
174+
npm run unitTests # Should pass most tests, MongoDB tests will timeout
175+
176+
# Test application serving
177+
npm start &
178+
sleep 3
179+
curl http://localhost:3001/ # Should return HTML with service name
180+
curl -w "Status: %{http_code}\n" http://localhost:3001/my/profile # Should return 401
181+
kill %1 # Stop the background server
182+
```
183+
184+
### Common File Locations
185+
- Main application entry: `bin/tpen3_services.js`
186+
- Express app setup: `app.js`
187+
- Route definitions: `project/index.js`, `userProfile/index.js`, etc.
188+
- Database controllers: `database/mongo/controller.js`, `database/maria/controller.js`
189+
- Authentication middleware: `auth/index.js`
190+
- Domain models: `classes/[Entity]/[Entity].js`
191+
- Configuration: `sample.env` (template), `.env` (local config)
192+
193+
### Dependencies and Versions
194+
- Express.js for REST API framework
195+
- MongoDB driver for document storage
196+
- MariaDB driver for relational storage
197+
- Auth0 libraries for JWT authentication
198+
- Jest for testing framework
199+
- Nodemon for development auto-reload
200+
- IIIF libraries for manifest handling
201+
202+
NEVER CANCEL long-running commands. Application builds and tests are designed to complete within documented timeouts. Always wait for completion to ensure accurate validation of changes.
203+
204+
All work on issues for bugs, features, and enhancements will target the `development` branch. The `main` branch will only be targetted with hotfixes by admins or by PRs from the `development` branch. New work should branch from `development`.

0 commit comments

Comments
 (0)