repoimage 0.2.0

package/client/src/lib/api.ts

@@ -0,0 +1,69 @@
+import type { ImageRow, ScanIssue } from '@repoimage/shared';
+
+const FILE_PROTOCOL_ERR =
+  'This page was opened as a local file (file://). Folder browse and server scan need the RepoImage GUI. Run npm run dev or npm run gui from the repo, then open the URL it prints.';
+
+export function resolveApiOrigin(): string | null {
+  const p = location.protocol;
+  if (p === 'http:' || p === 'https:') return '';
+  return null;
+}
+
+export const API_ORIGIN = resolveApiOrigin();
+
+export function apiUrl(resourcePath: string): string {
+  const rel = resourcePath.startsWith('/') ? resourcePath : `/${resourcePath}`;
+  if (API_ORIGIN === null) throw new Error(FILE_PROTOCOL_ERR);
+  return API_ORIGIN ? `${API_ORIGIN}${rel}` : rel;
+}
+
+export const FILE_PROTOCOL_ERROR = FILE_PROTOCOL_ERR;
+
+async function parseJsonResponse(res: Response): Promise<Record<string, unknown>> {
+  const text = await res.text();
+  let data: Record<string, unknown>;
+  try {
+    data = JSON.parse(text) as Record<string, unknown>;
+  } catch {
+    throw new Error(
+      text.trim().slice(0, 200) || `HTTP ${res.status} — is the API server running?`
+    );
+  }
+  if (!res.ok) {
+    throw new Error((data.error as string) || `HTTP ${res.status}`);
+  }
+  return data;
+}
+
+export async function fetchApiJson(url: string): Promise<Record<string, unknown>> {
+  const res = await fetch(apiUrl(url));
+  return parseJsonResponse(res);
+}
+
+export async function fetchScanFolder(
+  folder: string,
+  options: { excludeCommonFolders?: boolean } = {}
+): Promise<{
+  images: ImageRow[];
+  issues: ScanIssue[];
+}> {
+  const res = await fetch(apiUrl('/api/scan'), {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ folder, excludeCommonFolders: options.excludeCommonFolders })
+  });
+  const data = await parseJsonResponse(res);
+  return data as { images: ImageRow[]; issues: ScanIssue[] };
+}
+
+export async function fetchScanEntries(
+  entries: Array<{ path: string; size: number; width?: number | null; height?: number | null }>
+): Promise<{ images: ImageRow[]; issues: ScanIssue[] }> {
+  const res = await fetch(apiUrl('/api/scan-entries'), {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ entries })
+  });
+  const data = await parseJsonResponse(res);
+  return data as { images: ImageRow[]; issues: ScanIssue[] };
+}

package/client/src/lib/collect.ts

@@ -0,0 +1,204 @@
+import { IMAGE_EXTENSIONS } from '@repoimage/shared';
+
+export const DIM_BATCH = 8;
+export const WALK_REPORT_EVERY = 48;
+export const FILELIST_CHUNK = 120;
+
+export interface PickedFile {
+  path: string;
+  file: File;
+}
+
+export function yieldToPaint(): Promise<void> {
+  return new Promise(resolve => {
+    requestAnimationFrame(() => {
+      setTimeout(() => {
+        requestAnimationFrame(() => resolve());
+      }, 0);
+    });
+  });
+}
+
+export function isImageFileName(name: string): boolean {
+  const lower = name.toLowerCase();
+  const dot = lower.lastIndexOf('.');
+  if (dot === -1) return false;
+  return (IMAGE_EXTENSIONS as readonly string[]).includes(lower.slice(dot));
+}
+
+export async function collectFromDirectoryHandle(
+  dirHandle: FileSystemDirectoryHandle,
+  basePath: string,
+  onProgress?: (visited: number, imageCount: number) => void
+): Promise<PickedFile[]> {
+  const out: PickedFile[] = [];
+  let visited = 0;
+
+  if (onProgress) {
+    onProgress(0, 0);
+    await yieldToPaint();
+  }
+
+  async function walk(dh: FileSystemDirectoryHandle, bp: string): Promise<void> {
+    for await (const entry of dh.values()) {
+      visited++;
+      if (
+        onProgress &&
+        (visited % WALK_REPORT_EVERY === 0 || (out.length > 0 && out.length % 24 === 0))
+      ) {
+        onProgress(visited, out.length);
+        await yieldToPaint();
+      }
+
+      const name = entry.name;
+      const rel = bp ? `${bp}/${name}` : name;
+      if (entry.kind === 'directory') {
+        await walk(entry, rel);
+      } else if (entry.kind === 'file' && isImageFileName(name)) {
+        const file = await entry.getFile();
+        out.push({ path: rel.split('\\').join('/'), file });
+        if (onProgress && out.length % 28 === 0) {
+          onProgress(visited, out.length);
+          await yieldToPaint();
+        }
+      }
+    }
+  }
+
+  await walk(dirHandle, basePath);
+  if (onProgress) onProgress(visited, out.length);
+  return out;
+}
+
+export async function collectFromFileInputListAsync(
+  fileList: FileList,
+  onProgress?: (processed: number, total: number, imageCount: number) => void
+): Promise<PickedFile[]> {
+  const out: PickedFile[] = [];
+  const n = fileList.length;
+  await yieldToPaint();
+  for (let i = 0; i < n; i += FILELIST_CHUNK) {
+    const end = Math.min(i + FILELIST_CHUNK, n);
+    for (let j = i; j < end; j++) {
+      const file = fileList[j];
+      const rel = (file.webkitRelativePath || file.name).split('\\').join('/');
+      const seg = rel.split('/');
+      const baseName = seg[seg.length - 1] || file.name;
+      if (!isImageFileName(baseName)) continue;
+      out.push({ path: rel, file });
+    }
+    if (onProgress) onProgress(end, n, out.length);
+    await yieldToPaint();
+  }
+  return out;
+}
+
+export async function readImageDimensions(
+  file: File
+): Promise<{ width: number | null; height: number | null }> {
+  try {
+    const bmp = await createImageBitmap(file);
+    try {
+      return { width: bmp.width, height: bmp.height };
+    } finally {
+      bmp.close();
+    }
+  } catch {
+    return new Promise(resolve => {
+      const url = URL.createObjectURL(file);
+      const img = new Image();
+      img.onload = () => {
+        URL.revokeObjectURL(url);
+        resolve({
+          width: img.naturalWidth || null,
+          height: img.naturalHeight || null
+        });
+      };
+      img.onerror = () => {
+        URL.revokeObjectURL(url);
+        resolve({ width: null, height: null });
+      };
+      img.src = url;
+    });
+  }
+}
+
+export async function buildEntriesFromPicked(
+  picked: PickedFile[],
+  onProgress?: (done: number, total: number) => void
+): Promise<
+  Array<{ path: string; size: number; width: number | null; height: number | null }>
+> {
+  const entries: Array<{
+    path: string;
+    size: number;
+    width: number | null;
+    height: number | null;
+  }> = [];
+  const total = picked.length;
+  let done = 0;
+  for (let i = 0; i < picked.length; i += DIM_BATCH) {
+    const slice = picked.slice(i, i + DIM_BATCH);
+    const batch = await Promise.all(
+      slice.map(async ({ path: relPath, file }) => {
+        const dims = await readImageDimensions(file);
+        return {
+          path: relPath.split('\\').join('/'),
+          size: file.size,
+          width: dims.width,
+          height: dims.height
+        };
+      })
+    );
+    entries.push(...batch);
+    done += slice.length;
+    if (onProgress) onProgress(done, total);
+    await yieldToPaint();
+  }
+  return entries;
+}
+
+export function pickerRootLabelFromPaths(paths: PickedFile[]): string {
+  if (!paths.length) return '';
+  const first = paths[0].path.split('/')[0];
+  return first || '';
+}
+
+export function pathNorm(p: string): string {
+  return String(p || '').replace(/\\/g, '/');
+}
+
+export function pathDirname(norm: string): string {
+  const trimmed = norm.replace(/\/+$/, '');
+  const i = trimmed.lastIndexOf('/');
+  if (i === -1) return '.';
+  if (i === 0) return '/';
+  return trimmed.slice(0, i);
+}
+
+export function commonAncestorDir(absPaths: string[]): string {
+  const dirs = absPaths.map(pathNorm).map(pathDirname);
+  let r = dirs[0];
+  if (!r) return '';
+  for (let i = 1; i < dirs.length; i++) {
+    let d = dirs[i];
+    while (d && r && d !== r && !d.startsWith(r + '/')) {
+      const next = pathDirname(r);
+      if (next === r) break;
+      r = next;
+    }
+  }
+  return r || '';
+}
+
+export function tryDeriveAbsoluteRootFromPicked(list: PickedFile[]): string {
+  const abs: string[] = [];
+  for (const item of list) {
+    const f = item.file as File & { path?: string };
+    if (f.path && f.path.length) {
+      abs.push(f.path);
+    }
+  }
+  if (!abs.length) return '';
+  return commonAncestorDir(abs);
+}

package/client/src/lib/format.ts

@@ -0,0 +1,96 @@
+import type { ImageRow } from '@repoimage/shared';
+
+export function formatFileSize(bytes: number | null | undefined): string {
+  if (bytes == null) return '—';
+  if (bytes === 0) return '0 B';
+  const k = 1024;
+  const units = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return `${parseFloat((bytes / k ** i).toFixed(2))} ${units[i]}`;
+}
+
+export function scoreClass(score: string | null): string {
+  if (score == null) return 'score--na';
+  const n = parseFloat(score);
+  if (n >= 3.5) return 'score--good';
+  if (n >= 2.0) return 'score--mid';
+  return 'score--bad';
+}
+
+export function barFillClass(score: string | null): string {
+  if (score == null) return '';
+  const n = parseFloat(score);
+  if (n >= 3.5) return 'bar__fill--good';
+  if (n >= 2.0) return 'bar__fill--mid';
+  return 'bar__fill--bad';
+}
+
+export function splitPath(p: string): { dir: string; file: string } {
+  const lastSlash = Math.max(p.lastIndexOf('/'), p.lastIndexOf('\\'));
+  if (lastSlash === -1) return { dir: '', file: p };
+  return { dir: p.substring(0, lastSlash + 1), file: p.substring(lastSlash + 1) };
+}
+
+export function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+export type SortKey =
+  | 'path-asc'
+  | 'path-desc'
+  | 'size-desc'
+  | 'size-asc'
+  | 'score-desc'
+  | 'score-asc'
+  | 'dimensions-desc'
+  | 'dimensions-asc';
+
+export function applyFilters(
+  images: ImageRow[],
+  filterText: string,
+  minScore: string,
+  maxScore: string
+): ImageRow[] {
+  const ft = filterText.trim().toLowerCase();
+  const min = minScore !== '' ? parseFloat(minScore) : null;
+  const max = maxScore !== '' ? parseFloat(maxScore) : null;
+
+  return images.filter(img => {
+    if (ft && !img.path.toLowerCase().includes(ft)) return false;
+    const s = img.compressionRatio != null ? parseFloat(img.compressionRatio) : null;
+    if (min != null && (s == null || s < min)) return false;
+    if (max != null && (s == null || s > max)) return false;
+    return true;
+  });
+}
+
+export function applySort(images: ImageRow[], key: SortKey): ImageRow[] {
+  const sorted = [...images];
+  sorted.sort((a, b) => {
+    switch (key) {
+      case 'path-asc':
+        return a.path.localeCompare(b.path);
+      case 'path-desc':
+        return b.path.localeCompare(a.path);
+      case 'size-desc':
+        return (b.size || 0) - (a.size || 0);
+      case 'size-asc':
+        return (a.size || 0) - (b.size || 0);
+      case 'score-desc':
+        return (parseFloat(b.compressionRatio ?? '') || 0) - (parseFloat(a.compressionRatio ?? '') || 0);
+      case 'score-asc':
+        return (parseFloat(a.compressionRatio ?? '') || 0) - (parseFloat(b.compressionRatio ?? '') || 0);
+      case 'dimensions-desc':
+        return (b.width || 0) * (b.height || 0) - (a.width || 0) * (a.height || 0);
+      case 'dimensions-asc':
+        return (a.width || 0) * (a.height || 0) - (b.width || 0) * (b.height || 0);
+      default:
+        return 0;
+    }
+  });
+  return sorted;
+}

package/client/src/lib/session.ts

@@ -0,0 +1,58 @@
+import type { ImageRow } from '@repoimage/shared';
+
+export interface SessionState {
+  folderInput: string;
+  excludeCommonFolders: boolean;
+  cachedScanResults: ImageRow[];
+}
+
+const KEYS = {
+  folderInput: 'folderInput',
+  excludeCommonFolders: 'excludeCommonFolders',
+  cachedScanResults: 'cachedScanResults'
+};
+
+export function loadSessionState(): Partial<SessionState> {
+  const state: Partial<SessionState> = {};
+
+  const folder = localStorage.getItem(KEYS.folderInput);
+  if (folder) {
+    state.folderInput = folder;
+  }
+
+  const exclude = localStorage.getItem(KEYS.excludeCommonFolders);
+  if (exclude === 'true') {
+    state.excludeCommonFolders = true;
+  }
+
+  const cached = localStorage.getItem(KEYS.cachedScanResults);
+  if (cached) {
+    try {
+      state.cachedScanResults = JSON.parse(cached) as ImageRow[];
+    } catch {
+      // ignore invalid cache
+    }
+  }
+
+  return state;
+}
+
+export function saveSessionFolder(folder: string): void {
+  localStorage.setItem(KEYS.folderInput, folder);
+}
+
+export function saveSessionExclude(exclude: boolean): void {
+  localStorage.setItem(KEYS.excludeCommonFolders, String(exclude));
+}
+
+export function saveSessionScanResults(images: ImageRow[]): void {
+  if (images.length > 0) {
+    localStorage.setItem(KEYS.cachedScanResults, JSON.stringify(images));
+  }
+}
+
+export function clearSessionData(): void {
+  localStorage.removeItem(KEYS.folderInput);
+  localStorage.removeItem(KEYS.excludeCommonFolders);
+  localStorage.removeItem(KEYS.cachedScanResults);
+}

package/client/src/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import App from './App';
+import './index.css';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>
+);

package/client/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/client/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "jsx": "react-jsx",
+    "noEmit": true,
+    "isolatedModules": true,
+    "paths": {
+      "@repoimage/shared": ["../shared/src/index.ts"]
+    }
+  },
+  "include": ["src"],
+  "references": [{ "path": "../shared" }]
+}

package/client/vite.config.ts

@@ -0,0 +1,27 @@
+import path from 'path';
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+const apiPort = process.env.REPOIMAGE_API_PORT || '3847';
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@repoimage/shared': path.resolve(__dirname, '../shared/src/index.ts')
+    }
+  },
+  server: {
+    port: 5173,
+    proxy: {
+      '/api': {
+        target: `http://127.0.0.1:${apiPort}`,
+        changeOrigin: true
+      }
+    }
+  },
+  build: {
+    outDir: 'dist',
+    emptyOutDir: true
+  }
+});

package/docs/README.md

@@ -0,0 +1,28 @@
+# RepoImage Documentation
+
+Welcome to the RepoImage developer documentation. This folder contains guides for understanding the architecture, working with the API, and developing features.
+
+## Quick Links
+
+- **[Architecture](architecture.md)** — Workspace layout, data flow, package responsibilities
+- **[API Reference](api/)** — HTTP endpoints, parameters, and response formats
+- **[Development](development/)** — Local setup, testing strategies, and feature development
+- **[Features](features/)** — User-facing feature documentation
+- **[Design](design/)** — Architectural decisions and global invariants
+
+## Key Concepts
+
+**Image Roles:** Every image can have a suggested role (`hero`, `content`, `thumbnail`, `unknown`) based on heuristics, and an optional confirmed role set by users in `.repoimage.json`.
+
+**Compression Score:** A 0–10 scale where higher scores indicate larger-than-expected file size relative to image dimensions. Used to identify poorly compressed assets.
+
+**Partial Catalog:** The sidecar file (`.repoimage.json`) stores only manually confirmed images, not the full scan results. It's a user-curated subset.
+
+**Path Exclusion:** Users can toggle exclusion of common dependency folders (`node_modules`, `dist`, `.git`, etc.) to focus on asset images.
+
+## For Contributors
+
+- Start with [Architecture](architecture.md) to understand the codebase structure
+- See [PROJECT-AGENTS.md](../PROJECT-AGENTS.md) for project-specific development policies
+- Review [design/invariants.md](design/invariants.md) for architectural constraints that must always hold
+- Follow the testing and documentation requirements in [PROJECT-AGENTS.md](../PROJECT-AGENTS.md)

package/docs/api/overview.md

@@ -0,0 +1,65 @@
+# API Reference
+
+RepoImage provides an HTTP API for scanning images, listing files, and serving image thumbnails. The API server runs on port 3847 (configurable via `PORT` env var).
+
+## Endpoints
+
+### Scan Endpoints
+
+- **[POST /api/scan](scan.md)** — Scan one or more directories for images
+- **POST /api/scan-entries** — Enrich client-provided rows with compression metrics
+
+### File Browser
+
+- **GET /api/fs/home** — Get user's home directory path
+- **GET /api/fs/list** — List directory contents (directory browser)
+- **POST /api/fs/list** — Alternative: send path in JSON body
+
+### Image Serving
+
+- **GET /api/file** — Serve an image file by absolute path
+
+### Static Files
+
+- **GET /** — Serve the React app (index.html and assets)
+
+## Response Format
+
+All endpoints return JSON. Successful responses include:
+
+```json
+{
+  "images": [...],     // or entries, or single result
+  "issues": [...]      // if applicable
+}
+```
+
+Error responses:
+
+```json
+{
+  "error": "string",
+  "detail": "optional detail message"
+}
+```
+
+## Security
+
+- **Path validation** — All file paths are validated; `..` and escapes outside project root are rejected.
+- **Loopback restriction** — Filesystem APIs (`/api/fs/*`, `/api/file`) are restricted to loopback clients (127.0.0.1, ::1) by default. Set `REPOIMAGE_FS_TRUST_REMOTE=1` to allow remote clients (not recommended).
+
+## Environment Variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `PORT` | `3847` | HTTP server port |
+| `REPOIMAGE_BIND` | `127.0.0.1` | Bind address (e.g., `0.0.0.0` for all interfaces) |
+| `REPOIMAGE_FS_TRUST_REMOTE` | (unset) | Set to `1` to allow non-loopback clients to use `/api/fs/*` |
+| `REPOIMAGE_API_PORT` | `3847` | API port targeted by the Vite dev proxy |
+
+## Future Endpoints
+
+As features are implemented, new endpoints will be added:
+
+- **POST /api/repoimage** — Save confirmed roles to `.repoimage.json`
+- **GET /api/repoimage** — Load and validate config file