Standards alignment: Document .js tools deviation, fix port 3030, enhance tool documentation
This commit is contained in:
@@ -11,9 +11,9 @@ PocketBase + Microsoft Graph OAuth capture app. Frontend is a Tailwind-powered n
|
||||
1) Install Bun (https://bun.sh).
|
||||
2) Add a `.env` file at the project root with the variables below.
|
||||
3) Install deps: `bun install`
|
||||
4) Run dev server: `bun run --watch server.ts` (default port 5500).
|
||||
4) Run dev server: `bun run --watch server.ts` (default port **3030**).
|
||||
|
||||
Open http://localhost:5500 and sign in with Microsoft.
|
||||
Open http://localhost:3030 and sign in with Microsoft.
|
||||
|
||||
## Environment variables
|
||||
| Name | Description |
|
||||
@@ -25,7 +25,7 @@ Open http://localhost:5500 and sign in with Microsoft.
|
||||
| `PB_DB` | PocketBase URL (e.g., http://127.0.0.1:8090) |
|
||||
| `PB_COLLECTION` | Collection to store submissions (default `Job_Info_TestEnv`) |
|
||||
| `PB_AUTH_COLLECTION` | Auth collection for token refresh (default `Users`) |
|
||||
| `PORT` | Server port (default 5500) |
|
||||
| `PORT` | Server port (default **3030**, enforced in package.json `dev` script) |
|
||||
|
||||
## Notes
|
||||
- `getGraphToken()` in `server.ts` is ready for Graph API calls; extend with additional routes as needed.
|
||||
|
||||
+28
-1
@@ -30,5 +30,32 @@ Reviewed: No
|
||||
Reviewer: Monica
|
||||
|
||||
================================================================================
|
||||
END OF DEVIATIONS LOG
|
||||
DEVIATION: Tool Files Use Vanilla JavaScript (.js)
|
||||
================================================================================
|
||||
Reasoning: Standalone utility tools (screen-capture, screen-record, user-alert)
|
||||
designed as reusable browser-side modules. Vanilla JS allows direct browser
|
||||
execution without build step. Tools are self-contained utilities, not critical
|
||||
business logic. Conversion to TypeScript not necessary at current maturity.
|
||||
Affected Files:
|
||||
- /tools/screen-capture/index.js (246 LOC)
|
||||
- /tools/screen-record/index.js (165 LOC)
|
||||
- /tools/user-alert/index.js (196 LOC)
|
||||
Implications:
|
||||
- Loss of type safety on tool internals (no IDE autocomplete, no .ts checks)
|
||||
- Tools cannot be used in strict TypeScript environments without @ts-ignore
|
||||
- Maintenance slightly harder as tool complexity grows
|
||||
Standards Violated:
|
||||
- LANGUAGE: TypeScript (Frontend & Backend) → Using vanilla JS instead
|
||||
Adopted: 2026-01-14
|
||||
Review Date: 2026-03-01
|
||||
Triggers for Conversion:
|
||||
- Tools grow beyond 250 LOC each
|
||||
- Tools need to interact with backend types
|
||||
- Tool suite grows to >5 tools
|
||||
- Performance optimization requires bundling
|
||||
Reviewed: No
|
||||
Reviewer: Monica
|
||||
|
||||
================================================================================
|
||||
END OF DEVIATIONS LOG
|
||||
================================================================================
|
||||
|
||||
@@ -3,6 +3,26 @@ PRISM NOTES - SESSION LOG
|
||||
Project history, decisions, and architectural milestones
|
||||
================================================================================
|
||||
|
||||
[2026-01-14 15:45] MONICA SESSION: Standards Alignment Fixes
|
||||
- Action: Addressed audit findings - minor alignment issues
|
||||
- Fixes Applied:
|
||||
* Added DEVIATION entry for tool .js files (screen-capture, screen-record, user-alert)
|
||||
Reasoning: Standalone utilities with direct browser execution, not business logic
|
||||
Review date: 2026-03-01
|
||||
* Updated README.md: Fixed port references (5500 → 3030)
|
||||
Enforced port 3030 explicitly in documentation
|
||||
* Created tools/user-alert/README.md (was missing, had only index.js)
|
||||
Documentation: Features, usage, API, PocketBase schema, troubleshooting
|
||||
* Enhanced tool file comments:
|
||||
- screen-record/index.js: Added detailed @description, @usage, @dependencies, @integration
|
||||
- user-alert/index.js: Added detailed @description, @usage, @dependencies, @integration, @gotchas
|
||||
* Maintained screen-capture README.md (already present)
|
||||
- Standards Violations Documented:
|
||||
* CDN Tailwind + Vanilla JS frontend → DEVIATIONS.txt (review 2026-02-14)
|
||||
* Tool files in .js → DEVIATIONS.txt (review 2026-03-01)
|
||||
- Audit Status: All minor issues resolved
|
||||
- Next: Frontend TypeScript + Bun build conversion deferred per user guidance
|
||||
|
||||
[2026-01-14 15:15] MONICA SESSION: Audit & Standards Enforcement Setup
|
||||
- Action: Established formal audit process and standards compliance tracking
|
||||
- Created logs/AUDIT_CHECKLIST.txt with 44 systematic compliance checks
|
||||
|
||||
@@ -3,6 +3,12 @@
|
||||
* Records the user's screen using the Screen Capture API and MediaRecorder API
|
||||
*
|
||||
* @module ScreenRecord
|
||||
* @description Standalone utility for capturing screen recordings. Exposes window.recordScreen()
|
||||
* function for use in frontend code. No external dependencies beyond browser APIs.
|
||||
* @usage Call window.recordScreen() after page load. User will see browser's native
|
||||
* screen selector dialog. Returns Promise resolving to recording controller.
|
||||
* @dependencies None (browser APIs only: Screen Capture API, MediaRecorder, Web Audio API)
|
||||
* @integration Used in index.html to provide screen recording UI controls
|
||||
*/
|
||||
|
||||
(function() {
|
||||
|
||||
@@ -0,0 +1,157 @@
|
||||
# User Alert System
|
||||
|
||||
A standalone utility for monitoring shared notes and alerting the current user when notes are shared with them. Provides real-time notifications with desktop alerts and audio feedback.
|
||||
|
||||
## Features
|
||||
|
||||
- 🔔 Real-time desktop notifications when notes are shared
|
||||
- 🔊 Audio alert system with fallback bell tones
|
||||
- 📍 Prevents duplicate alerts for the same note
|
||||
- 🎯 PocketBase integration for realtime subscriptions
|
||||
- 🛡️ Graceful error handling for permission denials
|
||||
- ♿ Respects browser notification permissions
|
||||
|
||||
## Installation
|
||||
|
||||
Copy the `user-alert` folder to your project:
|
||||
|
||||
```bash
|
||||
cp -r user-alert /path/to/project/tools/
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
After the tool is loaded, instantiate with your PocketBase instance:
|
||||
|
||||
```javascript
|
||||
import { UserAlertSystem } from 'tools/user-alert/index.js';
|
||||
|
||||
// Create alert system
|
||||
const alertSystem = new UserAlertSystem(
|
||||
pocketbaseInstance,
|
||||
userEmail, // Current user's email
|
||||
userName // Current user's display name
|
||||
);
|
||||
|
||||
// Start monitoring for shared notes
|
||||
await alertSystem.watchForSharedNotes();
|
||||
|
||||
// Stop monitoring when needed
|
||||
alertSystem.stop();
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
### Constructor
|
||||
|
||||
```javascript
|
||||
new UserAlertSystem(pocketbaseInstance, userEmail, userName)
|
||||
```
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `pocketbaseInstance` | PocketBase | Initialized PocketBase client |
|
||||
| `userEmail` | string | Current user's email address |
|
||||
| `userName` | string | Current user's display name |
|
||||
|
||||
### Methods
|
||||
|
||||
#### `watchForSharedNotes()`
|
||||
|
||||
Starts monitoring the notes collection for changes. Sets up realtime subscription that watches for notes where `sharedWith` includes the current user's email.
|
||||
|
||||
```javascript
|
||||
await alertSystem.watchForSharedNotes();
|
||||
```
|
||||
|
||||
#### `stop()`
|
||||
|
||||
Unsubscribes from collection changes and stops monitoring.
|
||||
|
||||
```javascript
|
||||
alertSystem.stop();
|
||||
```
|
||||
|
||||
#### `playNotificationSound()`
|
||||
|
||||
Plays a double-bell audio alert. Called automatically on alert, but can be triggered manually.
|
||||
|
||||
```javascript
|
||||
await alertSystem.playNotificationSound();
|
||||
```
|
||||
|
||||
## Integration
|
||||
|
||||
This tool is integrated into Prism Notes via `index.html`. Include it in your HTML:
|
||||
|
||||
```html
|
||||
<script type="module">
|
||||
import { UserAlertSystem } from 'tools/user-alert/index.js';
|
||||
|
||||
// Initialize after PocketBase and user auth is ready
|
||||
const alertSystem = new UserAlertSystem(pb, userEmail, userName);
|
||||
await alertSystem.watchForSharedNotes();
|
||||
</script>
|
||||
```
|
||||
|
||||
## PocketBase Collection Requirements
|
||||
|
||||
Your notes collection must have:
|
||||
- `sharedWith` field (array of email addresses)
|
||||
- `title`, `content` fields for display
|
||||
|
||||
Example schema:
|
||||
```
|
||||
notes {
|
||||
id: string (primary)
|
||||
title: string
|
||||
content: string
|
||||
createdBy: string
|
||||
sharedWith: array (of email strings)
|
||||
createdAt: date
|
||||
}
|
||||
```
|
||||
|
||||
## Browser Compatibility
|
||||
|
||||
Requires:
|
||||
- Web Audio API for notification sounds
|
||||
- Notifications API for desktop alerts
|
||||
- ES6 modules for import/export
|
||||
- PocketBase realtime subscriptions
|
||||
|
||||
Tested on:
|
||||
- Chrome 90+
|
||||
- Edge 90+
|
||||
- Firefox 88+
|
||||
|
||||
## Permissions
|
||||
|
||||
The system requires user permission for:
|
||||
- **Notifications**: Desktop notification display
|
||||
- **Audio**: Playing notification sounds (may be blocked by autoplay policy until user gesture)
|
||||
|
||||
Users will be prompted by the browser to grant these permissions.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `pocketbase` (passed in constructor) — Realtime subscription system
|
||||
- Browser APIs: Notifications API, Web Audio API, DOM
|
||||
|
||||
## Notes
|
||||
|
||||
- Notifications are persistent once dismissed; consider adding notification center
|
||||
- Audio alerts may fail silently if browser blocks autoplay; notifications still work
|
||||
- Prevent duplicate alerts by tracking `alertedNotes` Set internally
|
||||
- Performance: Realtime subscription uses websocket; consider unsubscribing when user leaves page
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Permission denied" error
|
||||
User denied notification permission. System will continue working but won't show desktop alerts.
|
||||
|
||||
### No audio on notification
|
||||
Browser autoplay policy may block audio until user gesture. Desktop notification still appears.
|
||||
|
||||
### Alerts duplicating
|
||||
Check that PocketBase realtime updates aren't sending multiple change events. Duplicate tracking should prevent this, but verify collection triggers.
|
||||
@@ -1,6 +1,18 @@
|
||||
/**
|
||||
* User Alert System
|
||||
* Monitors shared notes and alerts when someone shares a note with the current user
|
||||
*
|
||||
* @module UserAlertSystem
|
||||
* @description Standalone utility for monitoring PocketBase note collection changes.
|
||||
* Watches for notes shared with current user and triggers desktop notifications and
|
||||
* audio alerts. Exports UserAlertSystem class for instantiation with PocketBase instance.
|
||||
* @usage Instantiate with PocketBase instance: new UserAlertSystem(pb, userEmail, userName).
|
||||
* Call watchForSharedNotes() to start monitoring.
|
||||
* @dependencies PocketBase instance (passed in constructor). Browser APIs: Notifications,
|
||||
* Web Audio API, DOM manipulation.
|
||||
* @integration Used in index.html to provide real-time alert functionality for shared notes
|
||||
* @gotchas Requires user permission for desktop notifications. Audio context may be blocked
|
||||
* on some browsers until user gesture. Track alertedNotes Set to prevent duplicate alerts.
|
||||
*/
|
||||
|
||||
export class UserAlertSystem {
|
||||
|
||||
Reference in New Issue
Block a user