Nathan Schneider
12ac4eb943
- Replace bracketed metadata placeholders with prompting questions - Fix upload error message (response.statusContents -> statusText) - Remove stray debug console.log on reactive screen updates - Document the upload token's security model in the app README Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
166 lines
7.1 KiB
Markdown
166 lines
7.1 KiB
Markdown
# Protocol Bicorder - Web App
|
|
|
|
A Svelte Progressive Web App (PWA) for carrying out protocol diagnostics as defined in `../bicorder.json`.
|
|
|
|
## Features
|
|
|
|
- **Single-page diagnostic tool** with ASCII-styled interface
|
|
- **Touch-friendly controls** optimized for mobile devices
|
|
- **Shortform toggle** - switch between full (23 gradients) and short (10 gradients) versions
|
|
- **Tooltips** on all gradient terms (long-press on mobile, hover on desktop)
|
|
- **Editable metadata** fields with auto-generated timestamps
|
|
- **Auto-calculated analysis** section (hardness/softness, polarized/centrist)
|
|
- **Citation support** for each gradient value
|
|
- **Local storage** - your progress is automatically saved
|
|
- **Export to JSON** - download your completed diagnostic
|
|
- **Share functionality** - use Web Share API on supported devices
|
|
- **Public upload** - submit readings directly to the public repository
|
|
- **Full PWA** - installable, works offline
|
|
- **Privacy-focused** - no telemetry, no external fonts, works completely offline
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Start development server (http://localhost:5173)
|
|
npm run dev
|
|
|
|
# Build for production
|
|
npm run build
|
|
|
|
# Preview production build (http://localhost:4173)
|
|
npm run preview
|
|
```
|
|
|
|
**Important:** The app must be served via HTTP/HTTPS (not opened directly as `file://`). Modern browsers block ES modules and service workers from the file protocol for security reasons. Always use `npm run preview` or deploy to a web server to test the built app.
|
|
|
|
## Build Process
|
|
|
|
The app reads `../bicorder.json` at build time and constructs the interface based on its structure. To update the diagnostic:
|
|
|
|
1. Edit `../bicorder.json`
|
|
2. Run `npm run update` (or `npm run build`)
|
|
3. The app will automatically reflect the new structure
|
|
|
|
Alternatively, run `./update-diagnostic.sh` for a friendlier update experience.
|
|
|
|
## Deployment
|
|
|
|
The built app is in the `dist/` folder. You can deploy it to any static hosting service:
|
|
|
|
- **GitHub Pages**: Push the dist folder
|
|
- **Netlify**: Connect your repo and set build command to `npm run build`
|
|
- **Vercel**: Same as Netlify
|
|
- **Static server**: Copy the dist folder contents to your web server
|
|
|
|
### Quick local server options
|
|
|
|
If you don't have Node.js available, you can serve the `dist/` folder with:
|
|
|
|
```bash
|
|
# Use the provided script (tries Python/PHP automatically)
|
|
./serve-local.sh
|
|
|
|
# Or manually:
|
|
# Python 3
|
|
python3 -m http.server 8000 --directory dist
|
|
|
|
# PHP
|
|
php -S localhost:8000 -t dist
|
|
|
|
# Any other static file server
|
|
```
|
|
|
|
Then open http://localhost:8000 in your browser.
|
|
|
|
## Usage
|
|
|
|
### Filling out the diagnostic
|
|
|
|
1. Fill in the metadata fields (Protocol, Analyst, Standpoint)
|
|
2. **Toggle shortform mode** (optional) to show only the 10 core gradients
|
|
3. For each gradient, tap/click the numbered buttons (1-9) to set values
|
|
- 1 = strongly toward the left term
|
|
- 5 = balanced/neutral
|
|
- 9 = strongly toward the right term
|
|
4. Optionally add citations for each gradient value
|
|
5. The Analysis section is automatically calculated based on your inputs
|
|
|
|
### Exporting and sharing results
|
|
|
|
- **Export JSON**: Downloads the diagnostic as a JSON file
|
|
- **Share**: Uses your device's share functionality (mobile)
|
|
- **Upload**: Submit your readings to the public repository
|
|
|
|
### Public upload
|
|
|
|
When you click **Upload**, your readings will be:
|
|
- Posted to the public repository: [protocol-bicorder-data](https://git.medlab.host/ntnsndr/protocol-bicorder-data)
|
|
- Licensed to the public domain (CC0)
|
|
- Committed with your analyst name and protocol name
|
|
- Stored in the `readings/` directory with a timestamp
|
|
|
|
All uploaded readings are public and available for research and analysis. By uploading, you consent to releasing your diagnostic under a public domain license.
|
|
|
|
#### Upload credentials and security model
|
|
|
|
The upload feature posts directly from the user's browser to the Gitea API using an access token defined in `src/components/ExportControls.svelte` (`GITEA_TOKEN`).
|
|
|
|
**This token is intentionally embedded in the client bundle, and that is acceptable here.** Because this is a purely static app, the browser must make the API call itself — there is no server-side code of ours to hold the token. Any credential the browser uses is therefore necessarily public; build-time environment variables would still be baked into the shipped JavaScript, so they would offer no real protection. The exposure is contained by *what the token can do* rather than by hiding it:
|
|
|
|
- The token belongs to a **dedicated `bicorder-bot` account**, not to a personal account.
|
|
- `bicorder-bot` is a **collaborator with write access only to the public [`protocol-bicorder-data`](https://git.medlab.host/ntnsndr/protocol-bicorder-data) repo**. It cannot push to any other repository.
|
|
- It has **`admin: false`** on that repo, so it can only add/modify files — it cannot delete the repo or change its settings.
|
|
- The token scope is `write:repository` (it cannot even read user account details).
|
|
|
|
The entire worst-case blast radius is therefore: someone extracts the token and spams or vandalizes the contents of the public data repo. This is recoverable (revert the commits) and the repo contains only public submissions.
|
|
|
|
**If the token is ever abused:** revoke it under the `bicorder-bot` account (Gitea → Settings → Applications → Access Tokens — note that tokens live under the *user account*, not the repo), generate a replacement with the same `write:repository` scope, update `GITEA_TOKEN` in `ExportControls.svelte`, and rebuild. Optionally, enable branch protection on the data repo's `main` branch as an additional safeguard.
|
|
|
|
## Browser Support
|
|
|
|
- Modern browsers (Chrome, Firefox, Safari, Edge)
|
|
- Mobile browsers (iOS Safari, Android Chrome)
|
|
- PWA installation supported on Android, iOS 16.4+, and desktop browsers
|
|
|
|
## Customization
|
|
|
|
### Styling
|
|
|
|
The app uses CSS custom properties for theming. Edit `src/app.css` to change colors:
|
|
|
|
```css
|
|
--bg-color: #000000; /* Background */
|
|
--fg-color: #00ff00; /* Foreground/text */
|
|
--border-color: #00ff00; /* Borders */
|
|
--hover-color: #00cc00; /* Hover states */
|
|
```
|
|
|
|
### Icons
|
|
|
|
Replace `public/icon.svg` with your own icon. For better PWA support, also generate PNG versions:
|
|
|
|
```bash
|
|
# Example using ImageMagick (if available)
|
|
convert -background none -resize 192x192 public/icon.svg public/icon-192.png
|
|
convert -background none -resize 512x512 public/icon.svg public/icon-512.png
|
|
```
|
|
|
|
Then update `vite.config.ts` to reference the PNG icons in the manifest.
|
|
|
|
## Architecture
|
|
|
|
- **Framework**: Svelte 4 with TypeScript
|
|
- **Build tool**: Vite 5
|
|
- **PWA**: vite-plugin-pwa with Workbox
|
|
- **State management**: Svelte stores + localStorage
|
|
- **Data source**: bicorder.json (build-time integration)
|
|
|
|
## Authorship and licensing
|
|
|
|
Initiated by [Nathan Schneider](https://nathanschneider.info) and available for use under the [Hippocratic License](https://firstdonoharm.dev/) (do no harm!). Several AI assistants, local and remote, were utilized in developing this tool.
|
|
|
|
[](https://firstdonoharm.dev/version/3/0/core.html)
|