repoimage 0.2.0

package/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm test *)",
+      "Bash(npm run *)"
+    ]
+  }
+}

package/AGENTS.md

@@ -0,0 +1,28 @@
+# Agent instructions
+
+**Note:** This file is generic and transferable across projects. For RepoImage-specific policies, see [PROJECT-AGENTS.md](PROJECT-AGENTS.md).
+
+## Questions are informational only
+
+When the user asks a **question** (including “how”, “what”, “why”, “can”, “does”, “is there”, “should I”, or any phrasing that seeks information, explanation, or advice rather than a direct change request):
+
+- Treat it **only** as a request for information.
+- **Do not** edit, create, or delete files.
+- **Do not** run commands that modify the project (no installs, commits, refactors, or “helpful” fixes unless the user explicitly asks you to make a change in that same message).
+
+If the user wants changes after your answer, they will say so explicitly (e.g. “implement that”, “add this”, “fix it”, “update the README”).
+
+When in doubt whether a message is a question or a task, **assume it is a question** and respond without altering code.
+
+## Tests and documentation
+
+**Policy:** Every TODO item must include tests and documentation updates. This is compulsory, not optional.
+
+- After changing project code, run `npm test` and report the result (pass or fail with a short summary of failing tests).
+- Do not treat a failing suite as an automatic mandate to make tests pass. Decide whether the implementation or the tests should change based on the user’s request.
+- When the user asked for intentional behavior or API changes, update or add tests to match; explain what you changed.
+- Do not weaken, delete, or bypass assertions just to get a green run unless the user explicitly asked for that.
+- If it is unclear whether code or tests are wrong, report the failures and your recommendation; do not guess by silently “fixing” whichever is easier.
+- Tests with fixed input/output expectations (fixtures) may fail after deliberate rule changes; those failures may be expected until expectations are updated with the user’s agreement.
+- When completing a TODO item, update the `docs/` folder with relevant documentation (API endpoints, features, examples, etc.) — this is required before marking as done.
+- If documentation is already present and complete, note this; only add or update docs when the feature is new or behavior has changed.

package/PROJECT-AGENTS.md

@@ -0,0 +1,55 @@
+# Project-Specific Agent Guidelines
+
+This document extends [AGENTS.md](AGENTS.md) with RepoImage-specific policies. Use this alongside the main AGENTS.md when working on this project.
+
+## Design Principles
+
+All work must respect the [Global Invariants](docs/design/invariants.md). Before implementing a feature or fix, check if any invariants apply. If your change would violate an invariant, escalate to the user.
+
+## Testing Strategy
+
+When implementing a TODO section, tests should focus on:
+
+| Area | Focus |
+|------|-------|
+| `shared` / `role-guess` | Fixture table; `unknown` when weak; valid roles only |
+| `server` / config | Load, merge, save, invariants |
+| `server` / scan | `roleGuess`, `role: null`, path `..` rejected |
+| `client` | Extracted banner/save helpers (not full E2E v1) |
+| Integration | API + CLI + config file |
+
+**No test is exempt.** Every TODO item must include tests as a prerequisite to completion (see [AGENTS.md](AGENTS.md) policy). Tests verify both happy path and invariant violations.
+
+## Documentation Requirements
+
+Every completed TODO item must include documentation updates in `docs/`. Specifically:
+
+- API changes → update `docs/api/` (endpoints, params, responses)
+- Features → update `docs/features/` (user guide, examples)
+- Architectural changes → update `docs/architecture.md` or `docs/design/`
+- CLI changes → document in `docs/development/` or feature docs
+
+See [B.docs TODO](TODO.md#bdocs--documentation-structure) for the docs folder structure.
+
+## Path Security
+
+Paths are a security boundary. Always validate:
+- No `..` segments
+- Normalized to project root
+- Reject attempts to escape (see [Invariant #6](docs/design/invariants.md))
+
+## Role Semantics
+
+Role values are enumerated: `hero`, `content`, `thumbnail`, `unknown`. 
+
+- **Guesses** (`roleGuess`) are ephemeral; never persisted.
+- **Confirmed roles** (`role`) in `.repoimage.json` are authoritative and survive re-scans.
+- See [Invariants #1, #2, #3, #7](docs/design/invariants.md) for the full contract.
+
+## Config File Stability
+
+The `.repoimage.json` sidecar is user-editable and may contain manual changes. Treat it as a partial, user-curated document:
+
+- Load with validation (reject stale paths, invalid roles)
+- Never overwrite confirmed roles during re-scan ([Invariant #4](docs/design/invariants.md))
+- Always set `_generator` on write ([Invariant #5](docs/design/invariants.md))

package/README.md

@@ -0,0 +1,153 @@
+# RepoImage
+
+Scan a project (or any folder tree) for image files, measure dimensions and file size, and estimate how well each image is compressed. Useful for finding oversized or poorly compressed assets in a repository.
+
+The **web GUI** is a React app (Vite). A **CLI** is available for scripts and quick terminal scans. The repo uses **npm workspaces**: `shared/`, `server/`, and `client/`.
+
+**For developers:** See [docs/](docs/) for architecture, API reference, and development guides.
+
+## Requirements
+
+- [Node.js](https://nodejs.org/) v18+
+
+## Quick start (production GUI)
+
+```bash
+git clone <repo-url> repoimage
+cd repoimage
+npm install
+npm run build
+npm run gui
+```
+
+The server prints a URL, for example:
+
+```text
+RepoImage GUI: http://127.0.0.1:3847/
+```
+
+Open that URL in your browser. Do not open `client/index.html` directly (`file://`); folder browse and scanning need the API server.
+
+## Development
+
+Run the API server and Vite dev client together (client proxies `/api` to port `3847`):
+
+```bash
+npm install
+npm run dev
+```
+
+- **GUI:** http://127.0.0.1:5173/
+- **API:** http://127.0.0.1:3847/
+
+Build everything and run tests:
+
+```bash
+npm run build
+npm test
+```
+
+## Using the GUI
+
+1. Start with `npm run gui` (production) or `npm run dev` (development).
+2. Open the URL shown (production: port **3847**; dev: port **5173**).
+3. **Choose a project root:** type an absolute path, or **Browse…** (server folder browser or system folder dialog).
+4. Review the table: path, file size, dimensions, estimated uncompressed size, compression score (0–10), and a visual bar.
+5. Use **Sort by**, **Filter path**, and **Min/Max score** to focus on the worst offenders.
+
+Compression score is higher when the file is large relative to an estimated uncompressed size (roughly `width × height × bytes-per-pixel`). SVG files are listed but do not get a score.
+
+### Environment variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `PORT` | `3847` | HTTP port (server / `npm run gui`) |
+| `REPOIMAGE_BIND` | `127.0.0.1` | Bind address (`0.0.0.0` for all interfaces) |
+| `REPOIMAGE_FS_TRUST_REMOTE` | (unset) | Set to `1` to allow non-loopback clients to use `/api/fs/*` (not recommended) |
+| `REPOIMAGE_API_PORT` | `3847` | API port targeted by the Vite dev proxy |
+
+Examples:
+
+```bash
+PORT=8080 npm run gui
+REPOIMAGE_BIND=0.0.0.0 npm run gui
+```
+
+Filesystem listing APIs (`/api/fs/list`, `/api/fs/home`) are restricted to loopback clients unless `REPOIMAGE_FS_TRUST_REMOTE=1`.
+
+## Command line
+
+```bash
+npm start -- /path/to/project
+# or after build:
+node server/dist/cli.js --json /path/to/repo
+# or:
+npx repoimage --json /path/to/repo
+```
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Print `{ images, issues }` as JSON on stdout |
+| `--sort-by-score` | Order results by compression score (worst first) |
+
+Install globally from the repo root (optional):
+
+```bash
+npm install -g .
+repoimage /path/to/project
+```
+
+## Image role suggestions
+
+Each scanned image includes a **heuristic suggested role** (not saved to disk):
+
+| Field | Meaning |
+|-------|---------|
+| `roleGuess` | One of `hero`, `content`, `thumbnail`, or `unknown` |
+| `roleGuessReason` | Short explanation when the guess is not `unknown` |
+| `role` | Always `null` for now — confirmed roles will use `.repoimage.json` (see [TODO.md](TODO.md)) |
+
+Guesses use path segments, small dimension suffixes in filenames, and image dimensions. They are **hints only**.
+
+### Example `--json` row
+
+```json
+{
+  "path": "public/hero-banner.jpg",
+  "size": 245000,
+  "width": 1600,
+  "height": 900,
+  "uncompressedSize": 4320000,
+  "compressionRatio": "4.1",
+  "role": null,
+  "roleGuess": "hero",
+  "roleGuessReason": "path suggests hero or banner"
+}
+```
+
+## Project layout
+
+| Path | Role |
+|------|------|
+| `shared/` | TypeScript types, role schema, `guessRole` heuristics |
+| `server/` | Scan, FS APIs, HTTP server, CLI (`tsc` → `dist/`) |
+| `client/` | Vite + React + TypeScript GUI (`vite build` → `dist/`) |
+| `test/` | Node test runner suites (run after server/shared build) |
+
+## Scripts
+
+| Script | Description |
+|--------|-------------|
+| `npm run build` | Build shared, server, and client |
+| `npm run dev` | Server watch + Vite dev server |
+| `npm run gui` | Build and start production server (serves `client/dist`) |
+| `npm start -- <folders>` | CLI scan |
+| `npm test` | Build shared/server and run tests |
+
+## Supported image types
+
+`.jpg`, `.jpeg`, `.png`, `.gif`, `.bmp`, `.tiff`, `.tif`, `.webp`, `.svg`, `.ico`, `.raw`, `.heic`, `.heif`, `.avif`
+
+## License
+
+MIT

package/TODO.md

@@ -0,0 +1,132 @@
+# RepoImage TODO
+
+Phased plan for the repo. Completed work is documented in [README.md](README.md). Run `npm test` after code changes; see [AGENTS.md](AGENTS.md) for how to handle failures.
+
+---
+
+## A — Load and merge `.repoimage.json`
+
+**Goal:** Read sidecar at project root; merged scan output shows confirmed `role` + `roleGuess`.
+
+**Reference:** [docs/design/role-system.md](docs/design/role-system.md) — role system design decisions.
+
+**⚠️ Invariants:** Never write `roleGuess` to disk (invariant #1). Re-scan must not overwrite confirmed roles (invariant #4). Config `role` wins over guess in output (invariant #3).
+
+- [ ] `server` (or `shared` + server): `loadConfig`, `mergeRoles`
+- [ ] Validate paths and roles; stale config paths reported
+- [ ] `/api/scan`, `/api/scan-entries` (when root known), CLI `--json`: `hasConfigFile`, `confirmedCount`, `totalImages`
+- [ ] Update `docs/api/` with `.repoimage.json` loading contract and response changes
+- [ ] Update `docs/features/` documenting config file format and partial catalog concept
+
+**Tests:** `repoimage-config` tests; extend server/scan/cli tests.
+
+**Done when:** Scan JSON includes manual `role` where configured; catalog stats correct.
+
+---
+
+## B — Save confirmed roles (API)
+
+**Goal:** Persist only on explicit save from UI (or future CLI command).
+
+**Reference:** [docs/design/role-system.md](docs/design/role-system.md) — role system design decisions.
+
+**⚠️ Invariants:** Never write `roleGuess` to disk (invariant #1). Only confirmed roles in `images` (invariant #2). Valid roles only (invariant #7). Always set `_generator` and `version` (invariant #5). Reject paths outside root (invariant #6).
+
+- [ ] `POST /api/repoimage` — `updates`, `remove`; read-modify-write; never write guesses
+- [ ] Maintain `version` + `_generator` on every write
+- [ ] Same path trust rules as scan / fs APIs
+- [ ] Update `docs/api/config.md` documenting save endpoint, payload, and write semantics
+
+**Tests:** create, update, unconfirm, `_generator` insert/replace, security cases.
+
+**Done when:** Sidecar writable via API without GUI.
+
+---
+
+## C — Role review UI (React)
+
+**Goal:** Review guesses and confirm roles in the client.
+
+**Reference:** [docs/design/role-system.md](docs/design/role-system.md) — role system design decisions.
+
+**⚠️ Invariant:** No one-click guess → confirm (invariant #8). Users must explicitly choose and confirm; accept-guess is forbidden.
+
+- [ ] Banner (no file vs partial catalog)
+- [ ] Columns: suggested role (+ reason tooltip), confirmed role ("—" if none)
+- [ ] Row control → popover: suggested (read-only), role select, Save/Cancel, Clear
+- [ ] Filters: e.g. unreviewed only
+- [ ] Stale config entries (path in JSON, file missing) — visible warning
+- [ ] Extract testable helpers (`bannerMessage`, save payload builder) — unit test in `client` or `shared`
+- [ ] Update `docs/features/` documenting role workflow and UI patterns
+
+**Done when:** Full confirm/unconfirm loop; no accept-guess shortcut.
+
+---
+
+## D — CLI and docs polish
+
+- [ ] CLI `--json` documents role + catalog fields (default with `--json`)
+- [ ] README: reference to `.repoimage.json` format in docs/
+- [ ] Re-scan never overwrites confirmed roles on disk
+- [ ] Update `docs/` as needed for CLI behavior and any remaining features
+
+**Tests:** CLI integration with config file; save → CLI sees confirmed role.
+
+---
+
+## E — Role guess tuning (optional)
+
+- [ ] Tune `role-guess` rules from real repos
+- [ ] Richer reasons in UI; sort/filter by suggestion; unreviewed + low score worklist
+- [ ] Update guess fixtures intentionally when rules change
+- [ ] Document updated guessing heuristics in `docs/features/`
+
+---
+
+## F — GUI walkthrough and screenshots
+
+**Goal:** User-friendly walkthrough documentation with screenshots of the GUI and feature workflows.
+
+- [ ] Screenshot: main scan interface (folder selection, results table)
+- [ ] Screenshot: sort/filter controls
+- [ ] Screenshot: compression score tooltip
+- [ ] Screenshot: settings dropdown
+- [ ] Screenshot: role confirmation popover
+- [ ] Write `docs/features/gui-walkthrough.md` with annotated screenshots and user workflows
+- [ ] Update `docs/features/README.md` to link to the walkthrough
+
+**Done when:** Users can understand core features visually before diving into docs.
+
+---
+
+## G — CONTRIBUTING.md
+
+**Goal:** Welcome open source contributors with clear guidelines.
+
+- [ ] Create `CONTRIBUTING.md` at repo root
+- [ ] Link to developer setup (`docs/development/`)
+- [ ] Explain the development process (pick a TODO, read PROJECT-AGENTS.md, tests + docs required)
+- [ ] Link to invariants and design principles
+- [ ] Code of conduct or basic courtesy guidelines
+- [ ] How to submit PRs (tests must pass, docs must be updated)
+
+**Done when:** New contributors know where to start and what's expected.
+
+---
+
+## Suggested order
+
+1. **A** → **B** → **C** → **D** — roles backend, API, UI, CLI (next: start with A)
+2. **E** — role guess tuning (optional, as needed)
+3. **F** — GUI walkthrough and screenshots (after main features complete)
+4. **G** — CONTRIBUTING.md (when ready to invite contributors)
+
+**Gate:** `npm test` after each section; see [AGENTS.md](AGENTS.md) if failures need human review.
+
+---
+
+## Out of scope for v1
+
+- Playwright E2E (optional later)
+- Visual/CSS regression tests
+- Proving heuristic "correctness" on real sites — only fixture-documented rules

package/client/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>RepoImage — Repository Image Analyser</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/client/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@repoimage/client",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@repoimage/shared": "*",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "typescript": "^5.7.2",
+    "vite": "^6.0.3"
+  }
+}