repoimage 0.2.0

package/docs/api/scan.md

@@ -0,0 +1,188 @@
+# POST /api/scan
+
+Scan one or more directories for images. Returns an array of image rows with dimensions, compression estimates, and role guesses.
+
+## Request
+
+```json
+{
+  "folder": "/absolute/path/to/project",
+  "folders": ["/path/1", "/path/2"],
+  "sortByScore": false,
+  "excludeCommonFolders": false
+}
+```
+
+### Parameters
+
+| Field | Type | Required | Default | Notes |
+|-------|------|----------|---------|-------|
+| `folder` | string | No* | — | Single directory path (alternative to `folders`) |
+| `folders` | array of strings | No* | — | Multiple directory paths. Either `folder` or `folders` must be provided. |
+| `sortByScore` | boolean | No | `false` | Sort results by compression score (worst first) |
+| `excludeCommonFolders` | boolean | No | `false` | Skip scanning `node_modules`, `dist`, `.git`, etc. |
+
+*Either `folder` or `folders` is required; providing both is allowed (they are merged).
+
+### Path Requirements
+
+- Paths must be absolute
+- Paths are resolved and normalized
+- Path traversal (`..`) is rejected
+- Paths outside the scanned root are rejected
+
+## Response (200 OK)
+
+```json
+{
+  "images": [
+    {
+      "path": "assets/hero.jpg",
+      "size": 245000,
+      "width": 1600,
+      "height": 900,
+      "uncompressedSize": 4320000,
+      "compressionRatio": "4.1",
+      "role": null,
+      "roleGuess": "hero",
+      "roleGuessReason": "path suggests hero or banner"
+    }
+  ],
+  "issues": []
+}
+```
+
+### Response Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `path` | string | Relative path from scan root (using `/` separators) |
+| `size` | number | File size in bytes |
+| `width` | number or null | Image width in pixels (null if unreadable) |
+| `height` | number or null | Image height in pixels (null if unreadable) |
+| `uncompressedSize` | number or null | Estimated uncompressed size (null for SVG or missing dimensions) |
+| `compressionRatio` | string or null | 0–10 score as string (null for SVG or missing dimensions) |
+| `role` | null | Always `null` (confirmed roles come from `.repoimage.json` when implemented) |
+| `roleGuess` | string | One of: `hero`, `content`, `thumbnail`, `unknown` |
+| `roleGuessReason` | string (optional) | Human-readable explanation of the guess (omitted if `unknown`) |
+
+### Issues
+
+The `issues` array reports problems during scanning:
+
+```json
+{
+  "code": "MISSING_FOLDER",
+  "path": "/path/to/folder",
+  "message": "Folder does not exist: /path/to/folder"
+}
+```
+
+Common issue codes:
+- `MISSING_FOLDER` — Directory does not exist
+- `DIR_READ_ERROR` — Error reading directory contents
+
+## Error Responses
+
+### 400 Bad Request
+
+```json
+{
+  "error": "Provide a project root: non-empty string \"folder\" or \"folders\" array."
+}
+```
+
+Missing or empty folder list.
+
+```json
+{
+  "error": "Invalid JSON body",
+  "detail": "error message"
+}
+```
+
+Malformed JSON in request body.
+
+### 405 Method Not Allowed
+
+Only POST is accepted.
+
+## Examples
+
+### Single folder scan
+
+```bash
+curl -X POST http://127.0.0.1:3847/api/scan \
+  -H "Content-Type: application/json" \
+  -d '{"folder": "/home/user/my-project"}'
+```
+
+### Multiple folders, excluding common paths
+
+```bash
+curl -X POST http://127.0.0.1:3847/api/scan \
+  -H "Content-Type: application/json" \
+  -d '{
+    "folders": ["/path/1", "/path/2"],
+    "excludeCommonFolders": true,
+    "sortByScore": true
+  }'
+```
+
+### From Node.js
+
+```javascript
+const response = await fetch('http://127.0.0.1:3847/api/scan', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    folder: '/home/user/my-project',
+    excludeCommonFolders: true
+  })
+});
+const data = await response.json();
+console.log(data.images);
+```
+
+## Compression Score
+
+The `compressionRatio` field is a 0–10 score where higher indicates worse compression (larger file relative to uncompressed estimate):
+
+- **Score 0–2** — Excellent compression
+- **Score 2–5** — Good compression
+- **Score 5–8** — Fair compression (review)
+- **Score 8–10** — Poor compression (candidates for optimization)
+
+Calculation:
+```
+uncompressed_size = width × height × bytes_per_pixel
+  (PNG/GIF: 4 bytes/pixel; others: 3 bytes/pixel)
+compression_ratio = -log2(file_size / uncompressed_size)
+  (clamped to [0, 10])
+```
+
+SVG files do not receive a score.
+
+## Exclude Common Folders
+
+When `excludeCommonFolders: true`, the following directory names are skipped at walk time:
+
+- `node_modules`, `.next`, `dist`, `.git`, `build`, `.bundle`
+- `.cache`, `target`, `vendor`, `.idea`, `.vscode`
+- `__pycache__`, `.pytest_cache`, `.tox`
+- `venv`, `.venv`, `env`, `.env`
+
+Exclusion is by directory name only (e.g., any `dist/` folder, anywhere in the tree).
+
+## Future: Role Confirmation
+
+When `.repoimage.json` is implemented, confirmed roles will be merged into the response:
+
+```json
+{
+  "path": "assets/hero.jpg",
+  "role": "hero",              // ← confirmed from sidecar
+  "roleGuess": "hero",
+  "roleGuessReason": "..."
+}
+```

package/docs/architecture.md

@@ -0,0 +1,155 @@
+# Architecture
+
+RepoImage is organized as an npm workspace with three independent packages: `shared`, `server`, and `client`.
+
+## Workspace Layout
+
+```
+repoimage/
+├── package.json           # Root workspace config
+├── shared/                # Shared types and utilities
+│   ├── src/
+│   │   ├── constants.ts   # Image extensions, exclude paths
+│   │   ├── types.ts       # ImageRow, ScanIssue, etc.
+│   │   ├── schema.ts      # Config file schema, validation
+│   │   ├── role-guess.ts  # Role guessing heuristics
+│   │   └── index.ts       # Public API
+│   └── dist/              # Compiled output (tsc)
+├── server/                # HTTP API and CLI
+│   ├── src/
+│   │   ├── scan.ts        # Image discovery and enrichment
+│   │   ├── fs-list.ts     # Filesystem browsing
+│   │   ├── server.ts      # HTTP server and route handlers
+│   │   ├── cli.ts         # CLI entry point
+│   │   └── paths.ts       # Path utilities
+│   └── dist/              # Compiled output (tsc)
+├── client/                # React GUI
+│   ├── src/
+│   │   ├── App.tsx        # Main React component
+│   │   ├── components/    # UI components
+│   │   └── ...
+│   └── dist/              # Built output (vite build)
+├── test/                  # Test suite (Node test runner)
+└── docs/                  # This documentation
+```
+
+## Data Flow
+
+### Scan Flow
+
+```
+User → /api/scan (HTTP POST)
+  ↓
+server/scan.ts: findImagesInFolders()
+  ↓
+walkDirectory() — recurse, skip excluded paths if enabled
+  ↓
+enrichImageEntry() — add dimensions, compression, roleGuess
+  ↓
+Images array → HTTP response
+  ↓
+Client displays in table
+```
+
+### Role Confirmation Flow
+
+```
+User clicks row, opens popover
+  ↓
+Client shows:
+  - roleGuess (read-only, from scan)
+  - role selector (for confirmed role)
+  ↓
+User selects role and clicks Save
+  ↓
+POST /api/repoimage (save endpoint, when implemented)
+  ↓
+Server writes .repoimage.json (read-modify-write)
+  ↓
+Next scan returns both roleGuess and role
+```
+
+## Package Responsibilities
+
+### shared/
+
+**Pure TypeScript types and constants** — no Node.js dependencies, usable by both server and client.
+
+- `IMAGE_EXTENSIONS` — supported file types (`.jpg`, `.png`, etc.)
+- `COMMON_EXCLUDE_PATHS` — default folder exclusions (`node_modules`, `dist`, etc.)
+- `ImageRow` — scan result row structure
+- `guessRole()` — heuristic role suggestion from path and dimensions
+- `schema.ts` — `.repoimage.json` validation and types
+
+### server/
+
+**HTTP server and CLI** — compiled with `tsc` (not bundled).
+
+- `scan.ts` — walks directory tree, filters by excluded paths, enriches with image metadata
+- `fs-list.ts` — lists directory contents (for the file picker UI)
+- `server.ts` — HTTP server with routes:
+  - `POST /api/scan` — scan folders for images
+  - `POST /api/scan-entries` — enrich client-provided rows
+  - `GET /api/fs/home` — user's home directory
+  - `GET /api/fs/list` — list directory contents
+  - `GET /api/file` — serve image file
+  - `GET /` — serve SPA index.html
+- `cli.ts` — command-line interface for headless scanning
+
+### client/
+
+**React GUI** — built with Vite.
+
+- Handles folder browsing and selection
+- Displays scan results in a sortable, filterable table
+- Manages sort/filter/score range UI
+- Will eventually include role confirmation UI (popover, save button)
+- Communicates with server via `/api/` endpoints
+
+## Development vs Production
+
+### Development
+
+```bash
+npm run dev
+```
+
+Starts:
+- Server on port 3847 (watches TypeScript changes)
+- Vite dev server on port 5173 (hot reload)
+- Client proxies `/api` requests to server:3847
+
+### Production
+
+```bash
+npm run build
+npm run gui
+```
+
+Builds all packages, then:
+- Server compiles and serves `client/dist` as static files
+- Single process, port 3847
+
+## Key Design Decisions
+
+1. **Vite for client only** — Fast HMR during dev; `tsc` for server keeps things simple.
+2. **npm workspaces** — Monorepo for shared code and types; single `node_modules` install.
+3. **Stateless API** — Server doesn't cache state; each request is independent. Config file is the only persistent state.
+4. **Server-side path filtering** — Exclusions applied at walk time, not post-scan, for efficiency.
+5. **Role guesses are ephemeral** — Never persisted to disk; only confirmed roles in `.repoimage.json` survive re-scans.
+
+## Testing
+
+Tests run with Node's built-in test runner:
+
+```bash
+npm test
+```
+
+Tests cover:
+- `shared/` — role guessing, constants, schema validation
+- `server/` — scan logic, file listing, API endpoints
+- `client/` — (helpers only, not full E2E yet)
+- Integration — API + CLI + config file
+
+See [PROJECT-AGENTS.md](../PROJECT-AGENTS.md#testing-strategy) for testing guidelines.

package/docs/design/invariants.md

@@ -0,0 +1,19 @@
+# Global Invariants
+
+These rules must always be true in the system. Violations are bugs.
+
+1. **`roleGuess` never written to `.repoimage.json`** — Only manually confirmed roles persist to disk. Guesses are computed fresh on each scan.
+
+2. **`images` contains only manually confirmed paths** — The sidecar stores only what the user has explicitly confirmed, never the full scan results.
+
+3. **Config `role` wins over guess in merged output** — When a path has both a confirmed role and a guess, the confirmed role is displayed/used. But `roleGuess` is still computed and returned alongside.
+
+4. **Re-scan updates guesses only, not confirmed `role` on disk** — Running a scan never modifies the `.repoimage.json` file. Guesses refresh; confirmed roles are untouched.
+
+5. **Every save sets canonical `_generator` and `version`** — The `_generator` field is the source of truth for which tool created/modified the file. Version is updated on every write.
+
+6. **Reject `..` and paths outside project root** — Path traversal and escapes are forbidden. All paths are relative to the scanned project root.
+
+7. **Persisted roles ∈ `hero` | `content` | `thumbnail` | `unknown`** — Only valid role values can be stored. Invalid values are rejected at save time.
+
+8. **No one-click guess → confirm in UI** — Users must explicitly choose a role and confirm. Accepting a guess is a deliberate action, not a shortcut.

package/docs/design/role-system.md

@@ -0,0 +1,50 @@
+# Image Role System Design
+
+Design decisions for the image role system and `.repoimage.json` sidecar file.
+
+## Overview
+
+Automatic **suggested** roles are computed at scan time. Users can confirm roles, which are persisted in `.repoimage.json`. Guesses are never saved to disk. The UI treats the sidecar as a **partial catalog** (N of M confirmed images).
+
+## Design Decisions
+
+| Topic | Decision |
+|-------|----------|
+| Config path | `<projectRoot>/.repoimage.json` only |
+| Role values | `hero` \| `content` \| `thumbnail` \| `unknown` |
+| Persistence | Only manually confirmed images in `images` array |
+| `_generator` | Canonical string on every write; insert or replace if missing/outdated |
+| Confirm UX | Popover with role picker + Save/Cancel; **no** one-click accept suggestion |
+| Banner | No file → guesses only; file exists → "N of M confirmed" partial catalog |
+
+## Config File Format
+
+```json
+{
+  "version": 1,
+  "_generator": "Roles confirmed with RepoImage — <canonical repo URL>",
+  "images": {
+    "assets/hero.jpg": { "role": "hero" },
+    "public/banner.png": { "role": "hero" },
+    "src/logo.svg": { "role": "content" }
+  }
+}
+```
+
+## Key Constraints
+
+1. `roleGuess` is **never** persisted to disk
+2. `images` contains **only** manually confirmed paths (never bulk guesses)
+3. Config `role` **wins over** guess in merged output; `roleGuess` still computed on each scan
+4. Re-scan **never overwrites** confirmed roles on disk
+5. Every save **updates** `_generator` and `version`
+6. Reject `..` and paths outside project root
+7. Persisted roles must be valid: `hero` | `content` | `thumbnail` | `unknown`
+8. No one-click guess → confirm shortcut in UI
+
+## Related Sections
+
+- **B** — Load and merge config file
+- **C** — Save confirmed roles API
+- **D** — Role review UI implementation
+- **E** — CLI and docs for roles

package/docs/development/README.md

@@ -0,0 +1,94 @@
+# Development Guide
+
+Getting started with developing RepoImage.
+
+## Local Setup
+
+1. **Clone and install**
+   ```bash
+   git clone <repo-url> repoimage
+   cd repoimage
+   npm install
+   ```
+
+2. **Start development servers**
+   ```bash
+   npm run dev
+   ```
+   Opens:
+   - Client: http://127.0.0.1:5173
+   - API: http://127.0.0.1:3847
+   - Client proxies `/api` to server automatically
+
+3. **Build and test**
+   ```bash
+   npm run build
+   npm test
+   ```
+
+## Project Structure
+
+See [Architecture](../architecture.md) for workspace layout and package responsibilities.
+
+## Making Changes
+
+1. **Read the requirements** — Check the TODO item and [PROJECT-AGENTS.md](../../PROJECT-AGENTS.md)
+2. **Understand invariants** — Review [design/invariants.md](../design/invariants.md) if your change affects roles, config, or paths
+3. **Write tests first** — Tests are compulsory; see testing strategy in [PROJECT-AGENTS.md](../../PROJECT-AGENTS.md)
+4. **Implement** — Add feature code in the appropriate workspace (`shared`, `server`, or `client`)
+5. **Update docs** — Document API changes, feature behavior, or architectural decisions in `docs/`
+6. **Run tests** — `npm test` must pass
+7. **Rebuild** — `npm run build` to verify TypeScript and Vite compilation
+
+## Key Files
+
+- `shared/src/constants.ts` — Image extensions, exclude paths
+- `server/src/scan.ts` — Core scanning and filtering logic
+- `server/src/server.ts` — HTTP API routes
+- `test/scan.test.js` — Scan tests (a good reference)
+
+## Testing
+
+Run all tests:
+```bash
+npm test
+```
+
+Tests use Node's built-in test runner. See test files in `test/` for patterns.
+
+**Remember:** Every change requires tests. See [PROJECT-AGENTS.md](../../PROJECT-AGENTS.md#testing-strategy) for what to test.
+
+## CLI
+
+For headless scanning:
+
+```bash
+npm start -- /path/to/project
+# or after build:
+node server/dist/cli.js --json /path/to/project
+```
+
+Flags:
+- `--json` — Output JSON instead of table
+- `--sort-by-score` — Order by compression (worst first)
+
+## Production Build
+
+```bash
+npm run build
+npm run gui
+```
+
+Serves the built client from the server on port 3847 (or `PORT` env var).
+
+## Troubleshooting
+
+**Build fails** — Check TypeScript errors. Run `npm run build` separately for each workspace to isolate issues.
+
+**Tests fail** — Review the test output and [design/invariants.md](../design/invariants.md) to ensure your change respects all rules.
+
+**Client changes not visible** — Make sure `npm run dev` is running and the Vite HMR connection is active.
+
+## Next Steps
+
+Start with [Architecture](../architecture.md), then pick a TODO item and follow the workflow above.

package/docs/features/README.md

@@ -0,0 +1,21 @@
+# Features
+
+User-facing documentation for RepoImage features.
+
+- **[Compression Score](compression-score.md)** — How the compression estimate is calculated
+- **[Path Exclusion](exclusions.md)** — Excluding common dependency folders from scans
+- **[Session Persistence](session.md)** — Browser state recovery between visits
+- **[Image Roles](roles.md)** — Role system and guessing heuristics (TBD)
+
+## Overview
+
+RepoImage helps developers find oversized or poorly compressed images in their projects. Key features:
+
+1. **Scan** — Recursively find all images in a project
+2. **Analyze** — Measure dimensions, file size, and estimate compression quality
+3. **Sort & Filter** — Focus on the worst offenders by score, size, or path
+4. **Exclude** — Hide dependency folders (node_modules, dist, etc.)
+5. **Confirm Roles** — Mark images as hero, content, thumbnail, or other (future)
+6. **Persist** — Save confirmed roles in a `.repoimage.json` sidecar (future)
+
+More details on each feature coming soon.

package/docs/features/compression-score.md

@@ -0,0 +1,75 @@
+# Compression Score
+
+The **compression score** is a 0–10 scale that estimates how well an image is compressed relative to its dimensions.
+
+## How It's Calculated
+
+For each image with readable dimensions:
+
+1. **Estimate uncompressed size**
+   ```
+   uncompressed_size = width × height × bytes_per_pixel
+   ```
+   - PNG/GIF: 4 bytes/pixel (RGBA)
+   - JPG/other: 3 bytes/pixel (RGB)
+
+2. **Calculate compression ratio**
+   ```
+   ratio = file_size / uncompressed_size
+   compression_score = -log2(ratio), clamped to [0, 10]
+   ```
+
+3. **Interpretation**
+   - Lower score = better compressed
+   - Higher score = larger file relative to dimensions (candidate for optimization)
+
+## Score Scale
+
+| Score | Interpretation | Action |
+|-------|---|---|
+| 0–2 | Excellent compression | ✓ No action needed |
+| 2–5 | Good compression | ✓ Acceptable |
+| 5–8 | Fair compression | ⚠ Review and optimize if large |
+| 8–10 | Poor compression | 🔴 High priority for optimization |
+
+## Examples
+
+### Well-compressed JPG (score 2.1)
+
+```
+Dimensions: 1600 × 900
+File size: ~245 KB
+Uncompressed estimate: 1600 × 900 × 3 = 4.32 MB
+Ratio: 245K / 4.32M ≈ 0.057
+Score: -log2(0.057) ≈ 4.1 (good)
+```
+
+### Uncompressed PNG (score 9.8)
+
+```
+Dimensions: 800 × 600
+File size: ~1.4 MB
+Uncompressed estimate: 800 × 600 × 4 = 1.92 MB
+Ratio: 1.4M / 1.92M ≈ 0.73
+Score: -log2(0.73) ≈ 0.45... wait, that's low!
+```
+
+Actually, scores near 0 mean the file is almost uncompressed. A higher ratio (closer to 1) produces a lower score.
+
+## Limitations
+
+- **No score for SVG** — Vector images don't have pixel dimensions; scoring them doesn't make sense.
+- **Estimates only** — The uncompressed size is an estimate based on typical RGBA/RGB. Actual compression depends on pixel data complexity.
+- **No context** — A large, well-compressed background image might have a high score but be perfectly acceptable. Use the score as a starting point, not a rule.
+
+## Tips for Optimization
+
+1. Use appropriate formats: WebP or AVIF for photos, PNG for graphics, SVG for icons
+2. Resize to actual display dimensions (don't serve 4000px wide images for 800px displays)
+3. Use modern lossy compression (JPEG 2000, WebP, AVIF)
+4. Optimize metadata (remove EXIF, thumbnails)
+5. Consider responsive images (`srcset`) for different devices
+
+## See Also
+
+- [API Reference](../api/scan.md#compression-score) — Technical details of the calculation

package/docs/features/exclusions.md

@@ -0,0 +1,63 @@
+# Path Exclusion
+
+The **Exclude common folders** toggle hides images in dependency and build output directories, helping you focus on asset images.
+
+## What Gets Excluded
+
+When enabled, the following directory names are skipped during scanning:
+
+- **Package managers:** `node_modules`, `vendor`
+- **Build outputs:** `dist`, `build`, `.next`, `.bundle`
+- **Version control:** `.git`
+- **Caches:** `.cache`, `target`, `.idea`, `.vscode`
+- **Python:** `__pycache__`, `.pytest_cache`, `.tox`, `venv`, `.venv`, `env`, `.env`
+
+Exclusion is by directory *name* only, so any `dist/` folder anywhere in the tree is skipped.
+
+## Usage
+
+1. Click the ⚙️ (gear) icon in the top-right of the header
+2. Check "Exclude common folders"
+3. Run a new scan
+
+The setting is remembered across browser sessions.
+
+## Behavior
+
+- **Scan time:** Excluded directories are skipped during the walk, improving performance for large projects
+- **Results:** Only images outside excluded paths are displayed
+- **Counts and totals:** Updated to reflect filtered results
+- **Re-scanning:** Toggling the preference re-runs the scan automatically
+
+## Example
+
+Scanning `/myproject` with exclusion **disabled**:
+
+```
+myproject/
+├── node_modules/
+│   └── some-lib/
+│       └── image.png     ← included
+├── src/
+│   └── logo.png          ← included
+└── dist/
+    └── banner.jpg        ← included
+Total: 3 images
+```
+
+Scanning the same project with exclusion **enabled**:
+
+```
+myproject/
+├── node_modules/         ← skipped
+├── src/
+│   └── logo.png          ← included
+└── dist/                 ← skipped
+Total: 1 image
+```
+
+## Notes
+
+- Exclusion is applied **at scan time**, not as a post-filter, so large projects scan faster
+- The list of excluded paths is built into the app and cannot be customized yet (future feature)
+- If you need to include a folder named `dist` or `node_modules`, use the **browser file picker** instead of entering a path directly