diff --git a/.gitignore b/.gitignore index 633e1948..33323b37 100644 --- a/.gitignore +++ b/.gitignore @@ -40,6 +40,7 @@ CLAUDE.md .superpowers/ docs/* !docs/COMMUNITY_GUIDE.md +!docs/prompts/ PRD.md # Ad-hoc test screenshots and reports diff --git a/docs/prompts/ADD_OR_UPGRADE_TOOL.md b/docs/prompts/ADD_OR_UPGRADE_TOOL.md new file mode 100644 index 00000000..8ba012ea --- /dev/null +++ b/docs/prompts/ADD_OR_UPGRADE_TOOL.md @@ -0,0 +1,273 @@ +# Add or Upgrade a Tool to State-of-the-Art + +## Role & System Directive + +Initialize as a Senior Full-Stack Engineer and UX Architect for the Ashim monorepo. Your objective is to either add a brand-new tool or upgrade an existing tool to a state-of-the-art implementation that matches or exceeds the best commercial alternatives. + +**Execution Engine:** Opus 4.7, Max Effort, 1M Token Context for EVERY agent and subagent. No model downgrading. No exceptions. + +--- + +## TOP PRIORITY: MAXIMUM PARALLELIZATION + +Spawn the maximum number of parallel Claude agent teams to complete this work as fast as possible. Independent research, implementation, and testing streams MUST run concurrently. Never run sequentially what can run in parallel. + +### Parallel Agent Architecture + +``` +Phase 0: Discovery (Sequential - must complete first) + └─> Analyze target, benchmark competitors, select approach + │ +Phase 1: PARALLEL BLAST ───────────────────────────────── + │ │ + │ Agent 1: Backend Implementation │ + │ API route, Zod schemas, image-engine ops, │ + │ AI sidecar integration (if needed) │ + │ │ + │ Agent 2: Frontend Implementation │ + │ Settings component, preview UI, tool card, │ + │ i18n strings, route registration │ + │ │ + │ Agent 3: Shared Package + Constants │ + │ Tool definition, types, category assignment, │ + │ feature bundle mapping (if AI) │ + │ │ + │ Agent 4: Test Suite │ + │ Unit tests, integration tests, │ + │ Playwright E2E spec, edge case coverage │ + │ │ + │ Agent 5: Documentation │ + │ GitHub Pages (VitePress), internal wiki, │ + │ OpenAPI spec, llms.txt, llms-full.txt, README │ + │ │ +Phase 2: Integration + Docker QA (after all agents done) │ + └─> Merge, build Docker, full QA sweep, verify docs │ +────────────────────────────────────────────────────────── +``` + +--- + +## CRITICAL DIRECTIVE: FIX EVERYTHING + +Fix ALL bugs, warnings, deprecations, lint issues, and problems you encounter while working, even if completely unrelated to the tool you are building. We want this software to be completely bug-free and always just working perfectly. Zero tolerance for known issues. + +**SOURCE OF TRUTH: LOCAL MAC CODEBASE.** ALL code changes MUST be made on the local Mac codebase first, then rsync'd to any remote test nodes. Never fix code directly on a remote system. The local codebase is what gets pushed to GitHub. If you fix a bug on a remote node without updating the local codebase, the fix is lost and future tests will fail again. The workflow is always: fix locally, rsync to remotes, rebuild containers on remotes, re-test. + +--- + +## Phase 0: Discovery and Research + +### 0.1 Analyze Current State +- If the tool already exists in our codebase, read its full implementation: API route, frontend component, image-engine operations, tests. +- If `[TARGET_URL]` is provided, visit it and analyze the current implementation. +- Identify why the current version is basic, unintuitive, or missing features. + +### 0.2 Competitive Benchmarking +- Research the top 3-5 commercial and open-source implementations of this tool category. +- Analyze their UI/UX patterns, feature sets, parameter options, and output quality. +- Document what makes each one excellent or lacking. + +### 0.3 SOTA Library Selection +- Find the best open-source libraries, algorithms, or frameworks to implement a world-class version. +- Evaluate: output quality, performance, format support, license compatibility, maintenance status. +- For AI-powered tools: identify the best model architecture and whether it fits our Python sidecar pattern. + +### 0.4 Present Implementation Plan +**STOP HERE.** Present your findings as MCQs (multiple choice questions) with your recommended path and reasoning for each decision point: +- Library/algorithm choice +- UI pattern (slider before/after vs side-by-side vs other) +- Parameter set and defaults +- Any architectural decisions + +Wait for approval before proceeding. + +--- + +## Phase 1: Implementation (Parallel Agents) + +Once the plan is approved, spawn ALL implementation agents in a single message. + +### Agent 1: Backend Implementation + +**Files to create/modify:** +- `apps/api/src/routes/tools/{tool-id}.ts` - Fastify route with Zod validation +- `packages/image-engine/src/operations/{operation}.ts` - Sharp-based processing (if applicable) +- `packages/ai/src/{tool}.ts` - Python sidecar bridge (if AI tool) +- `packages/ai/python/{tool}.py` - Python ML implementation (if AI tool) + +**Requirements:** +- Follow the `createToolRoute` factory pattern used by all other tools +- Zod schema for all input validation with sensible defaults +- Handle ALL standard formats: JPEG, PNG, WebP, AVIF, GIF, HEIC, HEIF, TIFF, BMP, SVG, PSD, DNG, TGA, EXR, HDR, ICO +- Support batch processing via the standard `/batch` endpoint +- Pipeline compatibility (tool must work as a pipeline step) +- Proper error messages for edge cases (large files, corrupted headers, unsupported operations) +- Add any extra endpoints if needed (e.g., `/inspect`, `/preview`, `/analyze`) + +### Agent 2: Frontend Implementation + +**Files to create/modify:** +- `apps/web/src/components/tools/{tool-id}-settings.tsx` - Settings panel component +- Register in `apps/web/src/components/tools/index.ts` +- Route registration in `apps/web/src/App.tsx` (if custom route needed) + +**Requirements:** +- Live preview on the right side of the UI - ensure HEIC/HEIF/GIF all render correctly +- Match existing design language (Tailwind CSS 4, consistent spacing, dark/light theme) +- Choose the right result display: before/after slider OR side-by-side comparison (whichever makes more sense for this tool) +- All settings controls must be intuitive: sliders for numeric ranges, dropdowns for enums, color pickers for colors +- Batch upload support: thumbnail strip showing all uploaded images, process ALL images (never just the first) +- Progress indicator for long operations +- Download button for results + +### Agent 3: Shared Package Updates + +**Files to modify:** +- `packages/shared/src/constants.ts` - Add tool definition (id, name, description, category, icon, route) +- `packages/shared/src/types.ts` - Add any new types +- `packages/shared/src/features.ts` - Map to feature bundle (if AI tool) +- `packages/shared/src/i18n/en.ts` - Add i18n strings + +### Agent 4: Test Suite + +**Files to create:** +- `tests/integration/{tool-id}.test.ts` - Integration tests +- `tests/e2e/{tool-id}.spec.ts` - Playwright E2E spec + +**Test requirements:** +- Valid input with default settings -> success +- Valid input with every parameter variation -> success +- Missing file -> 400 +- Invalid parameters -> 400 +- Every supported input format (JPEG, PNG, WebP, AVIF, HEIC, HEIF, GIF, SVG at minimum) +- Batch processing with mixed formats (5+ images) +- Large file (stress-large.jpg 6.7MB) +- Tiny file (test-1x1.png) +- Playwright: full GUI flow (navigate, upload, adjust settings, process, verify preview, download) + +### Agent 5: Documentation Updates + +Every new or upgraded tool MUST be documented across all surfaces before merge. + +**GitHub Pages (VitePress) -- `apps/docs/`:** +- Update `apps/docs/api/rest.md` with the new tool's endpoint, parameters, example curl, and response format +- Update `apps/docs/api/ai.md` if this is an AI tool (model, GPU requirements, performance notes) +- Update `apps/docs/api/image-engine.md` if this adds new Sharp operations +- Add the tool to any relevant guide pages (e.g., `apps/docs/guide/getting-started.md` feature list) +- Update `apps/docs/.vitepress/config.mts` sidebar if new pages are added +- Update tool count in description strings if total increases (currently "45+ tools") + +**Internal Wiki -- `.local-wiki/`:** +- If `.local-wiki/` exists, update the Tool Reference Guide section with the new tool's full documentation +- Add entries for: tool ID, category, endpoint, all parameters with types/defaults/ranges, sub-endpoints, UI component name, example API calls, pipeline compatibility +- Update any architecture diagrams affected by the new tool + +**OpenAPI Spec + LLM Docs:** +- Update `apps/api/src/openapi.yaml` with the new endpoint schema (path, method, parameters, request/response, errors) +- Update `llms.txt` with a one-line tool description +- Update `llms-full.txt` with full endpoint documentation (method, path, parameters, example curl, response) + +**README:** +- Update feature count in `README.md` if the total number of tools changes +- Add the tool to the feature list if it represents a notable new capability + +--- + +## Phase 2: Integration and Docker QA + +### 2.1 Merge and Build +- Merge all agent work into the feature branch +- Run `pnpm typecheck` - zero errors +- Run `pnpm lint` - zero errors +- Run `pnpm test` - all pass +- Build Docker container with the new tool + +### 2.2 Docker QA Testing + +**Container setup:** +```bash +SKIP_MUST_CHANGE_PASSWORD=true AUTH_ENABLED=false docker compose -f docker/docker-compose.yml up -d --build +``` + +**Port management:** Detect available ports on the system. Do NOT use port 1349 for testing to ensure isolation from other active services. + +**GUI testing with Playwright** against the Docker container: +1. Single image upload and process - verify output +2. Batch upload (5+ mixed formats) - verify ALL images processed +3. Every settings combination - verify each produces different output +4. Preview rendering for all formats including HEIC/HEIF +5. Download and verify output file validity + +**Test with committed fixture images:** +Use contextually appropriate images from `tests/fixtures/`, `tests/fixtures/content/`, and `tests/fixtures/formats/`. Do NOT use any external folders. + +### 2.3 Documentation Verification +1. **OpenAPI validation:** Verify `openapi.yaml` is valid OpenAPI 3.1 and includes the new endpoint +2. **GitHub Pages build:** Run `cd apps/docs && npx vitepress build` - zero errors, no dead links +3. **LLM docs check:** Verify `llms.txt` and `llms-full.txt` list the new tool +4. **Cross-reference:** Ensure the API docs, OpenAPI spec, LLM docs, and README all agree on the tool's endpoint, parameters, and description + +### 2.4 Iteration +If any issue is found: fix it, rebuild Docker, re-test. Repeat until perfect. Do not be lazy with testing. Do not suppress issues - raise them. + +--- + +## Phase 3: Finalization + +1. Provide the localhost URL/port for manual review before merging +2. Wait for approval +3. Push the feature branch to GitHub +4. Create a PR to main using `--repo ashim-hq/ashim`, merge it, delete the feature branch + +--- + +## Git Protocol + +- **Identity:** Always use Git user `ashim-hq` +- **Isolation:** Use Git Worktrees for this session - each feature gets its own worktree +- **Branching:** Create a `feat/{tool-id}` branch +- **Never push** `docs/superpowers/` to the public repo - it is gitignored and local-only +- **Port management:** Detect available ports, never use 1349 + +--- + +## Communication Rule + +Ask for clarification when necessary. Provide MCQs with your recommended path and reasoning for each decision point. + +--- + +## Usage + +Paste this prompt and append: + +``` +[TARGET_URL]: (optional - URL of existing tool to upgrade) +The feature name is: {TOOL_NAME} +``` + +--- + +## Tool Queue + +### 1. Background Replacement + +**Tool ID:** `replace-background` + +**Category:** AI + +**Description:** Remove background and replace in one step (solid color, gradient, blur, or custom image). + +**Rationale:** rembg already handles the hard part (background removal). Every competitor pairs removal with replacement. Currently users have to chain Remove Background then Image Composition, which is clunky. This is the lowest-effort, highest-impact gap to close. + +**Replacement modes:** +- **Solid color** - single hex/rgba color fill +- **Gradient** - linear or radial gradient with configurable stops and angle +- **Blur** - gaussian blur of the original background (keep subject sharp, blur surroundings) +- **Custom image** - user-uploaded image as the new background (fit, fill, or tile) + +**Implementation notes:** +- Backend: call rembg for mask, then composite subject onto the chosen replacement using Sharp +- Frontend: mode selector (solid/gradient/blur/custom), color picker, gradient editor, blur radius slider, image upload for custom mode +- The blur mode reuses the original image: apply mask to isolate subject, blur the full image, composite sharp subject on top +- Pipeline compatible: accepts the same input as `remove-background`, outputs the final composite diff --git a/docs/prompts/API_SYNC_AND_DOCUMENTATION_AUDIT.md b/docs/prompts/API_SYNC_AND_DOCUMENTATION_AUDIT.md new file mode 100644 index 00000000..e0318077 --- /dev/null +++ b/docs/prompts/API_SYNC_AND_DOCUMENTATION_AUDIT.md @@ -0,0 +1,214 @@ +# API Synchronization and Documentation Audit + +## Role & System Directive + +Initialize as a Senior Technical Architect and Lead API Engineer for the Ashim monorepo. The product has undergone significant feature and tool updates. The current API documentation, GitHub Pages, and README are outdated. There is a parity gap between tool functionality and API accessibility. + +**Objective:** Achieve 100% API coverage, 100% GitHub Pages coverage, 100% README coverage. Every tool and feature must have a corresponding, functional, and documented API endpoint. All documentation surfaces must reflect the current state of the software. + +**Execution Engine:** Opus 4.7, Max Effort, 1M Token Context for EVERY agent and subagent. No model downgrading. No exceptions. + +--- + +## TOP PRIORITY: MAXIMUM PARALLELIZATION + +Spawn the maximum number of parallel Claude agent teams to complete this audit as fast as possible. Each tool's audit and documentation can run independently. Never run sequentially what can run in parallel. + +### Parallel Agent Architecture + +``` +Phase 0: Audit Scan (Sequential) + └─> Scan all tools, identify all gaps, build work manifest + │ +Phase 1: PARALLEL BLAST ────────────────────────────────────────── + │ │ + │ Agent 1: Essential Tools API Parity (9 tools) │ + │ resize, crop, rotate, convert, compress, │ + │ strip-metadata, edit-metadata, adjust-colors, sharpening │ + │ │ + │ Agent 2: Watermark + Utility Tools API Parity (11 tools) │ + │ watermark-text, watermark-image, text-overlay, compose, │ + │ info, compare, find-duplicates, color-palette, │ + │ qr-generate, barcode-read, image-to-base64 │ + │ │ + │ Agent 3: Layout + Format + Optimization API Parity (13 tools)│ + │ collage, stitch, split, border, svg-to-raster, vectorize, │ + │ gif-tools, pdf-to-image, optimize-for-web, bulk-rename, │ + │ favicon, image-to-pdf, replace-color │ + │ │ + │ Agent 4: AI Tools API Parity (14 tools) │ + │ remove-background, upscale, ocr, blur-faces, smart-crop, │ + │ erase-object, colorize, enhance-faces, noise-removal, │ + │ red-eye-removal, restore-photo, passport-photo, │ + │ content-aware-resize, image-enhancement │ + │ │ + │ Agent 5: Non-Tool APIs Parity │ + │ Auth, API keys, pipelines, file library, settings, │ + │ teams, roles, audit log, branding, features, analytics │ + │ │ + │ Agent 6: OpenAPI Spec + Scalar Docs │ + │ Update apps/api/src/openapi.yaml completely, │ + │ update Scalar interactive docs, version bumps │ + │ │ + │ Agent 7: LLM Docs + README + GitHub Pages │ + │ Update llms.txt, llms-full.txt, README.md, │ + │ GitHub Pages documentation site │ + │ │ +Phase 2: Verification (after all agents done) │ + └─> Cross-check all docs against live API, fix discrepancies │ +─────────────────────────────────────────────────────────────────── +``` + +--- + +## CRITICAL DIRECTIVE: FIX EVERYTHING + +Fix ALL bugs, warnings, deprecations, broken endpoints, missing error handling, and documentation inaccuracies you encounter, even if unrelated to your current documentation task. We want this software to be completely bug-free and always just working perfectly. + +**SOURCE OF TRUTH: LOCAL MAC CODEBASE.** ALL code changes MUST be made on the local Mac codebase first, then rsync'd to any remote test nodes. Never fix code directly on a remote system. The local codebase is what gets pushed to GitHub. If you fix a bug on a remote node without updating the local codebase, the fix is lost and future tests will fail again. + +--- + +## Operational Environment and Safety + +- **Git Identity:** All commits under user `ashim-hq`. Public repo: `https://github.com/ashim-hq/ashim` +- **Never push** `docs/superpowers/` folder to the public repo - it is gitignored and local-only +- **Workflow:** Use Git Worktrees. Create a dedicated worktree for this session. +- **Port management:** Use unique ports for local testing. Do NOT use port 1349 (reserved). Check which ports are available. +- **Always use `--repo ashim-hq/ashim`** for any `gh` CLI commands. + +--- + +## Phase 0: Audit Scan + +### 0.1 Full Codebase Inventory +Scan every file in these directories: +- `apps/api/src/routes/tools/` - all tool route files +- `apps/api/src/routes/` - all non-tool route files +- `apps/api/src/openapi.yaml` - current OpenAPI spec +- `packages/shared/src/constants.ts` - tool definitions +- Root `README.md` +- `apps/docs/` - GitHub Pages / VitePress documentation + +### 0.2 Gap Analysis +For each tool and API endpoint, check: +- Does the endpoint exist and work? (functional parity) +- Is it documented in `openapi.yaml`? (spec parity) +- Is it documented in `llms.txt` and `llms-full.txt`? (LLM docs parity) +- Is it documented in the README? (user docs parity) +- Is it documented in GitHub Pages? (web docs parity) +- Are request/response schemas accurate? (schema parity) +- Are all parameters documented with types, defaults, and descriptions? (parameter parity) +- Are error responses documented? (error parity) + +### 0.3 Present Gap Report +**STOP.** Present the gap analysis as a structured table showing every endpoint and its documentation status across all surfaces. Wait for approval before proceeding. + +--- + +## Phase 1: Parallel Execution + +Once approved, spawn ALL agents in a single message. + +### Per-Tool Agent Protocol (Agents 1-4) + +For each tool assigned to the agent: + +1. **Codebase Audit:** Read the tool's source code. Identify every feature, parameter, endpoint (including sub-endpoints like `/inspect`, `/preview`, `/analyze`, `/batch`). + +2. **Parity Check:** Compare against existing documentation. + +3. **Fix/Implement:** + - Add missing API endpoints to achieve 100% coverage + - Remove deprecated or redundant endpoints + - Fix broken logic to meet RESTful best practices (clear status codes, proper error handling, consistent response shapes) + - Ensure every endpoint has proper Zod validation + +4. **Document:** Update all documentation surfaces for this tool. + +### Agent 5: Non-Tool APIs + +Audit and document every non-tool API: + +| System | Endpoints | +|--------|-----------| +| Auth | login, logout, session, change-password, register, users CRUD, reset-password | +| API Keys | create, list, delete, scoped permissions | +| Pipelines | execute, batch, save, list, delete, available tools | +| File Library | upload, list, details, download, thumbnail, delete, save-result | +| Settings | get all, get one, update | +| Teams | list, create, rename, delete | +| Roles | list, create, update, delete | +| Audit Log | list with filters | +| Branding | upload logo, serve logo, delete logo | +| Features | list, install, uninstall, disk usage | +| Analytics | config, consent | +| Health | health check | +| Docs | llms.txt, llms-full.txt, openapi.yaml, Scalar UI | + +### Agent 6: OpenAPI Spec + Scalar Docs + +**Complete rewrite of `apps/api/src/openapi.yaml`:** +- Every endpoint with accurate paths, methods, parameters +- Request body schemas matching Zod validators exactly +- Response schemas matching actual API responses +- Authentication requirements (Bearer token, API key) +- Error response schemas (400, 401, 403, 404, 409, 500) +- Proper tagging and grouping by category +- Version bump to match current app version +- Multipart file upload schemas for tool endpoints + +**Update Scalar interactive docs:** +- Verify the Scalar UI at `/api/docs` renders correctly +- All endpoints testable from the Scalar interface +- Example requests and responses for every endpoint + +### Agent 7: LLM Docs + README + GitHub Pages + +**Update `llms.txt`:** +- Concise plain-text overview of all capabilities +- Every tool listed with one-line description +- API authentication instructions +- Base URL and versioning info + +**Update `llms-full.txt`:** +- Complete API reference in plain text +- Every endpoint with method, path, parameters, example curl +- Response format documentation +- Error handling guide + +**Update `README.md`:** +- Feature list reflecting all 47+ tools +- Updated screenshots if UI has changed +- Docker deployment instructions (CPU and GPU) +- Environment variable reference +- API quickstart guide +- Link to full documentation + +**Update GitHub Pages / VitePress docs:** +- Tool reference pages for every tool +- API guide with authentication, rate limiting, batch processing +- Pipeline/automation documentation +- Self-hosting guide +- Contributing guide + +--- + +## Phase 2: Verification + +After all agents complete: + +1. **Live API Test:** For every documented endpoint, make an actual API call against the Docker container. Verify the response matches the documentation. +2. **Schema Validation:** Validate `openapi.yaml` is valid OpenAPI 3.1 spec. +3. **Link Check:** Verify all documentation links resolve correctly. +4. **Render Check:** Boot the docs site and verify all pages render. +5. **Cross-Reference:** Ensure `llms.txt`, `llms-full.txt`, `openapi.yaml`, README, and GitHub Pages all agree on the same endpoint list. + +--- + +## Phase 3: Finalization + +1. Run `pnpm typecheck` and `pnpm lint` - zero errors +2. Build Docker container to verify nothing is broken +3. Push feature branch to GitHub +4. Create PR to main using `--repo ashim-hq/ashim`, merge, delete branch diff --git a/docs/prompts/BUG_FIX_ZERO_REGRESSION.md b/docs/prompts/BUG_FIX_ZERO_REGRESSION.md new file mode 100644 index 00000000..a244359d --- /dev/null +++ b/docs/prompts/BUG_FIX_ZERO_REGRESSION.md @@ -0,0 +1,177 @@ +# Bug Fix with Zero Regression + +## Role & System Directive + +Initialize as a Principal Software Engineer and QA Lead for the Ashim monorepo. Your objective is to read a target GitHub issue, identify the root cause, implement a robust architectural fix, and execute a zero-regression test sweep. + +**Execution Engine:** Opus 4.7, Max Effort, 1M Token Context for EVERY agent and subagent. No model downgrading. No exceptions. + +--- + +## TOP PRIORITY: MAXIMUM PARALLELIZATION + +Once the fix is implemented, spawn the maximum number of parallel Claude agent teams for the regression sweep. The fix implementation is sequential (must be correct first), but ALL verification and testing streams run concurrently. Never run sequentially what can run in parallel. + +### Parallel Agent Architecture + +``` +Phase 0: Discovery (Sequential - needs approval) + └─> Read issue, find root cause, present fix plan + │ +Phase 1: Implementation (Sequential) + └─> Apply the approved fix + │ +Phase 2: PARALLEL VERIFICATION BLAST ───────────────────────── + │ │ + │ Agent 1: Targeted Fix Verification │ + │ Test the exact scenario from the issue, │ + │ single image + batch, real-world assets │ + │ │ + │ Agent 2: TypeScript + Lint Check │ + │ pnpm typecheck, pnpm lint -- zero errors │ + │ │ + │ Agent 3: Unit + Integration Tests │ + │ pnpm test:unit, pnpm test:integration │ + │ │ + │ Agent 4: Playwright E2E (if frontend touched) │ + │ Related E2E specs, DOM stability check │ + │ │ + │ Agent 5: Docker Container Validation │ + │ Build container, run fix scenario against Docker │ + │ │ + │ Agent 6: Related Tool Regression │ + │ Test tools that share code paths with the fix │ + │ │ +Phase 3: Resolution Report │ +──────────────────────────────────────────────────────────────── +``` + +--- + +## CRITICAL DIRECTIVES + +### Strict Coding Standards +- **No Band-Aids:** Do not suppress errors, hide UI elements via CSS, or use `// @ts-ignore`. Truly fix the underlying logic. +- **No Fallbacks:** Do not downgrade to lower-quality models or fallback states to bypass a bug. +- **Clean House:** If you encounter any bug, warning, or lint error in the files you touch, fix them immediately. Zero-warning codebase. +- **Fix Everything:** Even issues completely unrelated to the bug report. We want this software to be completely bug-free and always just working perfectly. +- **Source of Truth: Local Mac Codebase.** ALL code changes MUST be made on the local Mac codebase first, then rsync'd to remote test nodes. Never fix code directly on a remote system. The local codebase is what gets pushed to GitHub. If you fix on a remote node without updating locally, the fix is lost and future tests break again. + +### Operational Safety +- **Git Identity:** All commits under user `ashim-hq` +- **Never push** `docs/superpowers/` folder +- **Always use `--repo ashim-hq/ashim`** for any `gh` CLI commands +- **Git Worktrees:** Each bug fix session gets its own worktree to avoid conflicts +- **Branching:** Create a `fix/{issue-number}-{short-description}` branch +- **Port Management:** Do NOT use port 1349 for testing. Check available ports. +- **Production Containers Only:** All validation MUST run against Docker containers, not dev servers + +--- + +## Phase 0: Issue Discovery and Root Cause Analysis + +### 0.1 Read the Issue +Fetch and read the content of `[TARGET_ISSUE_URL]`. + +### 0.2 Codebase Investigation +- Identify the files causing the bug +- Trace the code path from API entry to the failure point +- Identify related code paths that might have the same issue +- Check if the issue exists in other tools that share the same pattern + +### 0.3 Present Root Cause +**STOP.** Present: +- Brief summary of the root cause +- The specific files and lines that need to change +- Your intended fix approach +- Any risks or side effects of the fix + +Wait for approval before modifying code. + +--- + +## Phase 1: Implementation + +Apply the approved fix. Ensure the code: +- Aligns with existing architecture patterns +- Does not introduce new abstractions unnecessarily +- Handles all edge cases identified in the analysis +- Includes inline comments only if the "why" is non-obvious + +--- + +## Phase 2: Parallel Verification (After Fix Applied) + +Spawn ALL verification agents in a single message. + +### Agent 1: Targeted Fix Verification + +Test the exact scenario described in the issue using committed test fixtures. + +**Test assets by tool category (all from `tests/fixtures/`):** +``` +OCR tools: content/ocr-chat.jpeg, content/ocr-japanese.png +Face tools: content/portrait-color.jpg, content/multi-face.webp, content/portrait-headshot.heic +AI tools: content/portrait-bw.jpeg, content/portrait-isolated.png, content/red-eye.jpg +Format tools: formats/sample.heif, content/svg-logo.svg, formats/sample.avif +Stress: content/stress-large.jpg +General: test-200x150.png, test-100x100.jpg, test-with-exif.jpg +``` + +Do NOT use any external folders. All test images come from `tests/fixtures/` exclusively. + +**Validation steps:** +1. Process a single image matching the issue scenario +2. Process a batch of 5+ images +3. Verify output matches expectations +4. Verify no silent failures (check logs, response codes, output file validity) + +### Agent 2: TypeScript + Lint Check +```bash +pnpm typecheck # Zero errors +pnpm lint # Zero errors +``` + +### Agent 3: Unit + Integration Tests +```bash +pnpm test:unit +pnpm test:integration +``` +All must pass. If any fail, determine if it is a pre-existing failure or caused by the fix. + +### Agent 4: Playwright E2E (If Frontend Touched) +Run the specific E2E specs related to the affected view: +```bash +pnpm test:e2e --grep "{relevant-tool-name}" +``` +Verify DOM stability and UI correctness. + +### Agent 5: Docker Container Validation +```bash +SKIP_MUST_CHANGE_PASSWORD=true docker compose -f docker/docker-compose.yml up -d --build +``` +Re-run the fix scenario against the Docker container to ensure it works in production. + +### Agent 6: Related Tool Regression +Identify other tools that share code paths, utilities, or components with the fix. Test each one to confirm no regression. + +--- + +## Phase 3: Resolution Report + +Output a brief summary confirming: +- The fix applied (files changed, approach taken) +- The specific test images used for validation +- Results of each verification agent (pass/fail with details) +- Any additional bugs found and fixed during the process +- The branch name and PR URL + +--- + +## Usage + +Paste this prompt and set the target: + +``` +[TARGET_ISSUE_URL]: https://github.com/ashim-hq/ashim/issues/{NUMBER} +``` diff --git a/docs/prompts/HARDWARE_BENCHMARK_AND_RECOMMENDATIONS.md b/docs/prompts/HARDWARE_BENCHMARK_AND_RECOMMENDATIONS.md new file mode 100644 index 00000000..e5fb5bcf --- /dev/null +++ b/docs/prompts/HARDWARE_BENCHMARK_AND_RECOMMENDATIONS.md @@ -0,0 +1,661 @@ +# Hardware Benchmark and System Recommendations + +## Role & System Directive + +Initialize as a Principal Performance Engineer and Systems Architect for the Ashim monorepo. Your objective is to run a comprehensive hardware benchmark across all available test systems, measure every feature's resource consumption, identify minimum/recommended/full hardware requirements, and produce a self-hoster's hardware guide. + +**Execution Engine:** Opus 4.7, Max Effort, 1M Token Context for EVERY agent and subagent. No model downgrading. No exceptions. + +--- + +## TOP PRIORITY: MAXIMUM PARALLELIZATION + +Each test system runs its benchmarks independently. Spawn parallel agents for EVERY system simultaneously. Never run sequentially what can run in parallel. + +### Parallel Agent Architecture + +``` +Phase 0: System Inventory (Sequential) + └─> Detect specs on all 4 nodes, deploy containers, verify health + │ +Phase 1: PARALLEL BENCHMARK BLAST ──────────────────────────────── + │ │ + │ Agent 1: macOS Benchmark │ + │ All 35 non-AI tools + batch + pipeline + format matrix │ + │ Docker Desktop for Mac resource monitoring │ + │ │ + │ Agent 2: WSL/GPU Benchmark │ + │ All 47 tools (AI on GPU) + batch + pipeline │ + │ GPU VRAM monitoring, CUDA utilization, GPU vs CPU timing │ + │ │ + │ Agent 3: WSL/GPU - CPU-Only AI Benchmark │ + │ All 12 AI tools with GPU DISABLED (force CPU fallback) │ + │ Measure CPU-only AI inference times to find usable vs │ + │ impractical tools without a GPU │ + │ │ + │ Agent 4: Ubuntu CPU Benchmark │ + │ All 35 non-AI tools + AI CPU fallback + batch + pipeline │ + │ Measure on actual CPU-only hardware (no GPU available) │ + │ │ + │ Agent 5: Windows Docker Desktop Benchmark │ + │ All 35 non-AI tools + batch + pipeline │ + │ Windows-specific Docker Desktop overhead measurement │ + │ │ + │ Agent 6: Resource Limit Sweep │ + │ Run key benchmarks at different Docker --memory and │ + │ --cpus limits to find minimum viable allocations │ + │ │ +Phase 2: Analysis + Report (after all agents done) │ + └─> Compile all data into hardware recommendation document │ +─────────────────────────────────────────────────────────────────── +``` + +--- + +## CRITICAL DIRECTIVES + +- **Production containers only.** All benchmarks run against Docker containers, never dev servers. +- **Fix everything.** If you find bugs, warnings, or performance issues during benchmarking, fix the code on the local Mac codebase, rsync to remotes, rebuild, and re-benchmark. +- **SOURCE OF TRUTH: LOCAL MAC CODEBASE.** All code changes go through the local Mac first, then rsync to remotes. +- **Always use `--repo ashim-hq/ashim`** for any `gh` CLI commands. +- **Never push** `docs/superpowers/` folder. + +--- + +## Test Systems + +| System | Connection | Shell | OS | Role | +|--------|-----------|-------|-----|------| +| **Mac** | Local | zsh | macOS | Development machine, Playwright host | +| **WSL (GPU)** | `ssh -p 2222 siddharth@192.168.0.247` | bash | Linux (WSL2) | GPU benchmarks (RTX 4070 12GB), CPU-only AI comparison | +| **Windows** | `ssh siddh@192.168.0.247` | PowerShell/CMD | Windows | Docker Desktop on Windows, Windows overhead measurement | +| **Ubuntu** | `ssh ubuntuserver@192.168.0.191` | bash | Ubuntu Linux | CPU-only server, no GPU | + +--- + +## Phase 0: System Inventory and Provisioning + +### 0.1 Detect Hardware Specs (parallel across all 4 systems) + +On each system, collect and record: + +**CPU:** +```bash +# Linux/WSL +lscpu | grep -E "Model name|CPU\(s\)|Thread|Core|MHz|cache" +cat /proc/cpuinfo | grep "model name" | head -1 + +# macOS +sysctl -n machdep.cpu.brand_string +sysctl -n hw.ncpu +sysctl -n hw.memsize + +# Windows (PowerShell) +Get-CimInstance Win32_Processor | Select-Object Name, NumberOfCores, NumberOfLogicalProcessors, MaxClockSpeed +``` + +**RAM:** +```bash +# Linux/WSL +free -h + +# macOS +sysctl -n hw.memsize | awk '{print $0/1073741824 " GB"}' + +# Windows (PowerShell) +Get-CimInstance Win32_ComputerSystem | Select-Object TotalPhysicalMemory +``` + +**GPU (WSL only):** +```bash +nvidia-smi --query-gpu=name,memory.total,memory.free,driver_version,compute_cap --format=csv +``` + +**Disk:** +```bash +# Linux/WSL +df -h / | tail -1 +lsblk -d -o NAME,SIZE,ROTA,TYPE | head -5 # SSD vs HDD + +# macOS +diskutil info / | grep "Free Space" + +# Windows (PowerShell) +Get-Volume | Where-Object {$_.DriveLetter -eq 'C'} | Select-Object Size, SizeRemaining +``` + +**Docker:** +```bash +docker info 2>/dev/null | grep -E "Total Memory|CPUs|Storage Driver|Server Version" +``` + +### 0.2 Deploy Containers + +On each system: +```bash +SKIP_MUST_CHANGE_PASSWORD=true docker compose -f docker/docker-compose.yml up -d --build +until curl -sf http://localhost:1349/api/v1/health; do sleep 2; done +``` + +On WSL (GPU variant): +```bash +SKIP_MUST_CHANGE_PASSWORD=true docker compose -f docker/docker-compose-gpu.yml up -d --build +``` + +### 0.3 Obtain Auth Tokens +```bash +TOKEN=$(curl -s -X POST http://localhost:1349/api/auth/login \ + -H 'Content-Type: application/json' \ + -d '{"username":"admin","password":"admin"}' | jq -r '.token') +``` + +### 0.4 Install AI Bundles (WSL + Ubuntu) +```bash +for bundle in background-removal face-detection upscale-enhance object-eraser-colorize ocr photo-restoration; do + curl -X POST "http://localhost:1349/api/v1/admin/features/$bundle/install" \ + -H "Authorization: Bearer $TOKEN" + # Wait for each to complete before next (sequential - models are large) +done +``` + +--- + +## Phase 1: Benchmark Execution (Parallel Across All Systems) + +Spawn agents 1-6 in a SINGLE message. + +### Benchmark Methodology + +For every benchmark, capture these metrics: + +```bash +# Before each test +CONTAINER_ID=$(docker ps -q -f name=ashim) + +# CPU + Memory during test (sample every 1s) +docker stats $CONTAINER_ID --no-stream --format "{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}" + +# Timing +time curl -X POST http://localhost:1349/api/v1/tools/{tool} \ + -H "Authorization: Bearer $TOKEN" \ + -F "file=@{test-file}" \ + -F "settings={json}" \ + -o /dev/null -w "%{time_total}" +``` + +Record for each test: +- **Wall clock time** (seconds) +- **Peak container memory** (MB) +- **Peak CPU usage** (%) +- **Peak GPU VRAM** (MB, GPU node only) +- **Output file size** (bytes) +- **Pass/Fail** + +### Benchmark Test Matrix + +#### Tier 1: Core Tool Benchmarks (all systems) + +Test each tool with a small file (fast) AND the stress file (realistic load): + +| # | Tool | Small File | Large File | Settings | +|---|------|-----------|------------|----------| +| 1 | resize | test-200x150.png | stress-large.jpg | `width=800, fit=cover` | +| 2 | crop | test-200x150.png | stress-large.jpg | `left=10,top=10,width=100,height=100` | +| 3 | rotate | test-200x150.png | stress-large.jpg | `angle=90` | +| 4 | convert (jpg->webp) | test-100x100.jpg | stress-large.jpg | `format=webp, quality=80` | +| 5 | convert (jpg->avif) | test-100x100.jpg | stress-large.jpg | `format=avif, quality=50` | +| 6 | compress | test-200x150.png | stress-large.jpg | `mode=quality, quality=60` | +| 7 | compress (targetSize) | stress-large.jpg | stress-large.jpg | `mode=targetSize, targetSizeKb=500` | +| 8 | strip-metadata | test-with-exif.jpg | stress-large.jpg | `stripAll=true` | +| 9 | edit-metadata | test-with-exif.jpg | stress-large.jpg | `title=Bench, clearGps=true` | +| 10 | adjust-colors | test-200x150.png | stress-large.jpg | `brightness=20, contrast=10, effect=grayscale` | +| 11 | sharpening | test-200x150.png | stress-large.jpg | `method=adaptive, sigma=1.5` | +| 12 | watermark-text | test-200x150.png | stress-large.jpg | `text=BENCHMARK, position=tiled` | +| 13 | compose | test-200x150.png + test-100x100.jpg | stress-large.jpg + portrait-color.jpg | `blendMode=overlay` | +| 14 | collage (4 images) | 4 small fixtures | 4 content images | `templateId=4-grid` | +| 15 | stitch (3 horizontal) | 3 small fixtures | 3 content images | `direction=horizontal` | +| 16 | split (4 tiles) | test-200x150.png | stress-large.jpg | `columns=2, rows=2` | +| 17 | border | test-200x150.png | stress-large.jpg | `borderWidth=20, cornerRadius=10, shadow=true` | +| 18 | svg-to-raster | svg-logo.svg | svg-logo.svg | `width=2000, dpi=300` | +| 19 | vectorize | test-200x150.png | portrait-color.jpg | `colorMode=color` | +| 20 | gif-tools (optimize) | animated-simpsons.gif | animated-simpsons.gif | `mode=optimize, colors=64` | +| 21 | pdf-to-image | test-3page.pdf | test-3page.pdf | `format=png, dpi=300` | +| 22 | optimize-for-web | stress-large.jpg | stress-large.jpg | `format=webp, quality=80, maxWidth=1920` | +| 23 | favicon | test-200x150.png | portrait-color.jpg | (none) | +| 24 | image-to-pdf | 3 small fixtures | 3 content images | `pageSize=A4` | +| 25 | replace-color | test-200x150.png | stress-large.jpg | `sourceColor=#FFFFFF, targetColor=#FF0000` | +| 26 | info | test-200x150.png | stress-large.jpg | (none) | +| 27 | compare | test-200x150.png x2 | stress-large.jpg x2 | (none) | +| 28 | find-duplicates | 5 mixed fixtures | 5 mixed content | `threshold=5` | +| 29 | color-palette | portrait-color.jpg | stress-large.jpg | (none) | +| 30 | qr-generate | (JSON) | (JSON) | `text=https://ashim.app, size=2000` | +| 31 | barcode-read | barcode.avif | barcode.avif | `tryHarder=true` | +| 32 | image-to-base64 | test-200x150.png | stress-large.jpg | `outputFormat=webp` | +| 33 | bulk-rename | 5 small fixtures | 5 content images | `pattern=bench_{{padded}}` | +| 34 | content-aware-resize | test-200x150.png | stress-large.jpg | `width=100` | +| 35 | image-enhancement | test-200x150.png | stress-large.jpg | `mode=auto, intensity=50` | + +#### Tier 2: AI Tool Benchmarks (WSL GPU + WSL CPU-only + Ubuntu CPU) + +For GPU node, run each test twice: once with GPU enabled, once with GPU disabled (set `CUDA_VISIBLE_DEVICES=""` in container env). + +| # | Tool | Test File | Settings | Bundle | +|---|------|-----------|----------|--------| +| 1 | remove-background | portrait-color.jpg | `backgroundType=transparent` | background-removal | +| 2 | remove-background | portrait-isolated.png | `backgroundType=color, backgroundColor=#0000FF` | background-removal | +| 3 | upscale (2x) | test-100x100.jpg | `scale=2` | upscale-enhance | +| 4 | upscale (2x, large) | portrait-color.jpg | `scale=2` | upscale-enhance | +| 5 | upscale (face enhance) | portrait-color.jpg | `scale=2, faceEnhance=true` | upscale-enhance | +| 6 | ocr (fast) | ocr-chat.jpeg | `quality=fast, language=en` | ocr | +| 7 | ocr (best) | ocr-chat.jpeg | `quality=best, language=en` | ocr | +| 8 | ocr (Japanese) | ocr-japanese.png | `quality=balanced, language=ja` | ocr | +| 9 | blur-faces | multi-face.webp | `blurRadius=30, sensitivity=0.5` | face-detection | +| 10 | smart-crop (face) | portrait-color.jpg | `mode=face, width=400, height=400` | face-detection | +| 11 | erase-object | portrait-color.jpg + mask | `format=png` | object-eraser-colorize | +| 12 | colorize | portrait-bw.jpeg | `intensity=1.0` | object-eraser-colorize | +| 13 | enhance-faces (gfpgan) | portrait-color.jpg | `model=gfpgan, strength=0.8` | upscale-enhance | +| 14 | enhance-faces (codeformer) | portrait-color.jpg | `model=codeformer, strength=0.7` | upscale-enhance | +| 15 | noise-removal (quick) | test-200x150.png | `tier=quick` | upscale-enhance | +| 16 | noise-removal (quality) | stress-large.jpg | `tier=quality` | upscale-enhance | +| 17 | red-eye-removal | red-eye.jpg | `sensitivity=50, strength=80` | face-detection | +| 18 | restore-photo (full) | portrait-bw.jpeg | `mode=auto, scratchRemoval=true, faceEnhancement=true, colorize=true` | photo-restoration | +| 19 | passport-photo | portrait-headshot.heic | Analyze + Generate US | background-removal | +| 20 | content-aware-resize (face) | portrait-color.jpg | `width=300, protectFaces=true` | (uses face-detection) | + +#### Tier 3: Batch Processing Benchmarks (all systems) + +| # | Test | Files | Tool | Measure | +|---|------|-------|------|---------| +| 1 | Batch 3 small | 3 fixtures | resize | Time, peak memory | +| 2 | Batch 5 small | 5 fixtures | resize | Time, peak memory | +| 3 | Batch 10 small | 10 fixtures | resize | Time, peak memory | +| 4 | Batch 3 large | 3 content images | resize | Time, peak memory | +| 5 | Batch 5 large | 5 content images | compress | Time, peak memory | +| 6 | Batch 5 mixed formats | jpg+png+webp+heic+avif | convert (webp) | Time, peak memory | +| 7 | Batch 3 AI (GPU) | 3 portraits | remove-background | Time, peak VRAM | +| 8 | Batch 5 AI (GPU) | 5 portraits | blur-faces | Time, peak VRAM | + +#### Tier 4: Pipeline Benchmarks (all systems) + +| # | Pipeline Steps | Files | Measure | +|---|---------------|-------|---------| +| 1 | resize(800) | 1 image | Time | +| 2 | resize(800) -> convert(webp) | 1 image | Time | +| 3 | resize -> grayscale -> sharpening -> compress | 1 image | Time | +| 4 | resize -> grayscale -> sharpening -> compress -> convert | 1 image | Time | +| 5 | 5-step pipeline | 3 images (batch) | Time, peak memory | +| 6 | resize -> remove-bg (AI) | 1 image (GPU) | Time, peak VRAM | +| 7 | 10-step pipeline | 1 image | Time, peak memory | + +#### Tier 5: Format Decode Benchmarks (all systems) + +Resize each format to 200px wide and measure decode+process time: + +| Format | File | Expected Behavior | +|--------|------|-------------------| +| JPEG | sample.jpg | Fast, baseline | +| PNG | sample.png | Fast | +| WebP | sample.webp | Fast | +| AVIF | sample.avif | Moderate (AV1 decode) | +| GIF | sample.gif | Fast (single frame) | +| BMP | sample.bmp | Fast (uncompressed) | +| TIFF | sample.tiff | Fast | +| HEIC | sample.heic | Moderate (heif-dec external) | +| HEIF | sample.heif | Moderate (heif-dec external) | +| SVG | sample.svg | Fast (rasterize) | +| DNG (RAW) | sample.dng | Slow (dcraw external) | +| PSD | sample.psd | Moderate (ImageMagick) | +| TGA | sample.tga | Fast | +| EXR | sample.exr | Moderate (HDR tone map) | +| HDR | sample.hdr | Moderate (HDR tone map) | +| ICO | sample.ico | Fast | + +#### Tier 6: Concurrent Load Benchmarks (all systems) + +| # | Test | Description | Measure | +|---|------|-------------|---------| +| 1 | 1 concurrent request | Baseline single request | Response time | +| 2 | 3 concurrent requests | Light load | Avg/p95/max response time | +| 3 | 5 concurrent requests | Medium load | Avg/p95/max response time, peak memory | +| 4 | 10 concurrent requests | Heavy load | Avg/p95/max response time, peak memory, errors | +| 5 | 20 concurrent requests | Stress | Avg/p95/max response time, peak memory, errors, OOM? | + +Use `resize` with `stress-large.jpg` for all concurrency tests. Run via: +```bash +for i in $(seq 1 N); do + curl -s -X POST http://localhost:1349/api/v1/tools/resize \ + -H "Authorization: Bearer $TOKEN" \ + -F "file=@stress-large.jpg" \ + -F "settings={\"width\":800}" \ + -o /dev/null -w "%{time_total}\n" & +done +wait +``` + +#### Tier 7: Sustained Load + Memory Stability (all systems) + +| # | Test | Description | Measure | +|---|------|-------------|---------| +| 1 | 50 sequential resizes | Process stress-large.jpg 50 times | Memory over time (leak check) | +| 2 | 20 sequential AI tools | Cycle through AI tools 20 times (GPU) | VRAM over time (leak check) | +| 3 | 1-hour idle | Container running with no requests for 60 min | Baseline memory | +| 4 | Container cold start | Time from `docker compose up` to health OK | Startup time | +| 5 | AI bundle install time | Time to install each of the 6 bundles | Download + setup time | + +### Agent 6: Docker Resource Limit Sweep + +Run the core benchmark subset (resize large, compress large, convert large, batch 5, collage 4) at constrained resource limits to find the minimum viable configuration: + +| # | CPU Limit | Memory Limit | Test | Expected Outcome | +|---|-----------|-------------|------|------------------| +| 1 | 1 core | 512MB | resize large | Pass/fail, time | +| 2 | 1 core | 1GB | resize large | Pass/fail, time | +| 3 | 1 core | 2GB | resize large | Pass/fail, time | +| 4 | 2 cores | 1GB | resize large | Pass/fail, time | +| 5 | 2 cores | 2GB | resize large | Pass/fail, time | +| 6 | 2 cores | 4GB | resize large | Pass/fail, time | +| 7 | 4 cores | 2GB | resize large | Pass/fail, time | +| 8 | 4 cores | 4GB | resize large | Pass/fail, time | +| 9 | 1 core | 512MB | batch 5 resize | Pass/fail, time | +| 10 | 1 core | 1GB | batch 5 resize | Pass/fail, time | +| 11 | 2 cores | 2GB | batch 5 resize | Pass/fail, time | +| 12 | 4 cores | 4GB | batch 5 resize | Pass/fail, time | +| 13 | 1 core | 512MB | collage 4 | Pass/fail, time | +| 14 | 2 cores | 2GB | collage 4 | Pass/fail, time | +| 15 | 4 cores | 4GB | collage 4 | Pass/fail, time | +| 16 | 1 core | 2GB | convert avif | Pass/fail, time | +| 17 | 2 cores | 2GB | compress targetSize | Pass/fail, time | +| 18 | 2 cores | 4GB | AI remove-bg (CPU) | Pass/fail, time | +| 19 | 4 cores | 8GB | AI remove-bg (CPU) | Pass/fail, time | +| 20 | 4 cores | 8GB | AI upscale (CPU) | Pass/fail, time | +| 21 | 2 cores | 4GB | AI ocr (CPU) | Pass/fail, time | +| 22 | 4 cores | 8GB | AI restore-photo (CPU) | Pass/fail, time | + +Run with: +```bash +docker run --rm -d --cpus=X --memory=Xm -p 1349:1349 \ + -e AUTH_ENABLED=false -e SKIP_MUST_CHANGE_PASSWORD=true \ + --name ashim-bench ashim:latest +``` + +--- + +## Phase 2: Analysis and Report Generation + +**Agent 15 runs LAST** after all benchmark agents complete. + +Generate `HARDWARE_RECOMMENDATIONS.md` at `/Users/sidd/Desktop/Personal/Projects/ashim/docs/HARDWARE_RECOMMENDATIONS.md`. + +### Report Structure + +```markdown +# Ashim Self-Hosting Hardware Recommendations + +**Generated:** [date] +**Version:** [from package.json] +**Benchmark Systems:** [list all 4 with specs] + +--- + +## Quick Reference + +| Tier | Use Case | CPU | RAM | GPU | Storage | Docker Limits | +|------|----------|-----|-----|-----|---------|---------------| +| Minimum | Core tools only, single user | ? | ? | None | ? | `--cpus=? --memory=?` | +| Recommended | All tools + some AI (CPU), small batches | ? | ? | None | ? | `--cpus=? --memory=?` | +| Full | All tools + all AI (GPU), large batches, concurrent users | ? | ? | NVIDIA ?GB+ | ? | `--cpus=? --memory=?` | + +--- + +## Tier Definitions + +### Minimum Viable (No AI Features) + +**What works:** All 35 non-AI tools with small to medium images (up to ~5MP). +Single-user, sequential processing. Batch up to 3 images. + +**What doesn't work:** AI tools (remove-bg, upscale, OCR, face enhance, etc.), +large batches (10+), concurrent users, images larger than ~20MP. + +**Hardware:** +- CPU: [minimum from benchmarks] +- RAM: [minimum from resource limit sweep] +- Storage: [minimum - app + workspace] +- GPU: Not required + +**Docker Compose limits:** +```yaml +deploy: + resources: + limits: + cpus: 'X' + memory: XG +``` + +**Performance expectations:** +| Operation | Time (small image) | Time (large image) | +|-----------|-------------------|-------------------| +| Resize | Xs | Xs | +| Convert (WebP) | Xs | Xs | +| ... | | | + +--- + +### Recommended (CPU AI, Moderate Load) + +**What works:** All 35 non-AI tools at full speed. AI tools work on CPU +(slower but functional). Batch up to 10 images. 2-3 concurrent users. + +**What doesn't work:** GPU-accelerated AI (uses CPU fallback instead). +Very large batches (20+) may be slow. Heavy concurrent load (10+ users). + +**AI Tool Viability on CPU:** +| AI Tool | CPU Time | Usable? | Notes | +|---------|----------|---------|-------| +| remove-background | Xs | Yes/Marginal/No | | +| upscale (2x) | Xs | Yes/Marginal/No | | +| ocr (fast) | Xs | Yes/Marginal/No | | +| ocr (best) | Xs | Yes/Marginal/No | | +| blur-faces | Xs | Yes/Marginal/No | | +| enhance-faces | Xs | Yes/Marginal/No | | +| colorize | Xs | Yes/Marginal/No | | +| noise-removal | Xs | Yes/Marginal/No | | +| restore-photo | Xs | Yes/Marginal/No | | +| passport-photo | Xs | Yes/Marginal/No | | +| erase-object | Xs | Yes/Marginal/No | | +| red-eye-removal | Xs | Yes/Marginal/No | | + +Viability thresholds: +- **Yes** = under 30 seconds for a typical image +- **Marginal** = 30-120 seconds (usable but user will wait) +- **No** = over 120 seconds or OOM (impractical without GPU) + +**Hardware:** +- CPU: [from benchmarks] +- RAM: [from benchmarks] +- Storage: [app + AI models + workspace] +- GPU: Not required (CPU fallback) + +**Docker Compose limits:** +```yaml +deploy: + resources: + limits: + cpus: 'X' + memory: XG +``` + +--- + +### Full System (GPU AI, Heavy Load) + +**What works:** Everything. All 47 tools at maximum speed with GPU acceleration. +Batch 20+ images. 10+ concurrent users. Pipeline automation. + +**Hardware:** +- CPU: [from benchmarks] +- RAM: [from benchmarks] +- GPU: NVIDIA with [minimum VRAM from benchmarks] +- Storage: [app + all AI models + workspace] + +**GPU VRAM Requirements:** +| AI Bundle | Model Size on Disk | Peak VRAM During Inference | +|-----------|-------------------|---------------------------| +| background-removal | XGB | XGMB | +| upscale-enhance | XGB | XMB | +| face-detection | XMB | XMB | +| object-eraser-colorize | XGB | XMB | +| ocr | XGB | XMB | +| photo-restoration | XGB | XMB | +| **All bundles loaded** | **XGB** | **XMB peak** | + +**GPU vs CPU Speed Comparison:** +| AI Tool | GPU Time | CPU Time | Speedup | +|---------|----------|----------|---------| +| remove-background | Xs | Xs | Xx | +| upscale (2x) | Xs | Xs | Xx | +| ... | | | | + +**Docker Compose limits:** +```yaml +deploy: + resources: + limits: + cpus: 'X' + memory: XG + reservations: + devices: + - driver: nvidia + count: all + capabilities: [gpu] +``` + +--- + +## Detailed Benchmark Results + +### Core Tools Performance (per system) + +| Tool | Mac (small) | Mac (large) | WSL (small) | WSL (large) | Ubuntu (small) | Ubuntu (large) | Windows (small) | Windows (large) | +|------|------------|------------|-------------|-------------|---------------|---------------|----------------|----------------| +| resize | Xs | Xs | Xs | Xs | Xs | Xs | Xs | Xs | +| ... | | | | | | | | | + +### Batch Processing Scaling + +| Batch Size | Mac | WSL | Ubuntu | Windows | Peak Memory | +|-----------|-----|-----|--------|---------|-------------| +| 3 images | Xs | Xs | Xs | Xs | XMB | +| 5 images | Xs | Xs | Xs | Xs | XMB | +| 10 images | Xs | Xs | Xs | Xs | XMB | + +### Pipeline Overhead + +| Steps | Single Image Time | 3-Image Batch Time | Memory | +|-------|-------------------|-------------------|--------| +| 1 | Xs | Xs | XMB | +| 2 | Xs | Xs | XMB | +| 4 | Xs | Xs | XMB | +| 10 | Xs | Xs | XMB | + +### Format Decode Times (per system) + +| Format | Mac | WSL | Ubuntu | Windows | Notes | +|--------|-----|-----|--------|---------|-------| +| JPEG | Xs | Xs | Xs | Xs | Baseline | +| HEIC | Xs | Xs | Xs | Xs | External decoder | +| DNG | Xs | Xs | Xs | Xs | dcraw | +| PSD | Xs | Xs | Xs | Xs | ImageMagick | +| ... | | | | | | + +### Concurrent Load Results + +| Concurrent Requests | Avg Response | p95 Response | Max Response | Errors | Peak Memory | +|---------------------|-------------|-------------|-------------|--------|-------------| +| 1 | Xs | Xs | Xs | 0 | XMB | +| 3 | Xs | Xs | Xs | 0 | XMB | +| 5 | Xs | Xs | Xs | 0 | XMB | +| 10 | Xs | Xs | Xs | ? | XMB | +| 20 | Xs | Xs | Xs | ? | XMB | + +### Docker Resource Limit Results + +| CPU | Memory | resize | batch-5 | collage | convert-avif | AI remove-bg | +|-----|--------|--------|---------|---------|-------------|-------------| +| 1 | 512MB | P/F Xs | P/F Xs | P/F Xs | P/F Xs | N/A | +| 1 | 1GB | P/F Xs | P/F Xs | P/F Xs | P/F Xs | N/A | +| 2 | 2GB | P/F Xs | P/F Xs | P/F Xs | P/F Xs | P/F Xs | +| 4 | 4GB | P/F Xs | P/F Xs | P/F Xs | P/F Xs | P/F Xs | +| 4 | 8GB | P/F Xs | P/F Xs | P/F Xs | P/F Xs | P/F Xs | + +### Memory Stability + +| Test | Start Memory | End Memory | Delta | Leak? | +|------|-------------|------------|-------|-------| +| 50 sequential resizes | XMB | XMB | +XMB | Yes/No | +| 20 AI tool cycles | XMB | XMB | +XMB | Yes/No | +| 1-hour idle | XMB | XMB | +XMB | Yes/No | + +### Storage Requirements + +| Component | Size | +|-----------|------| +| Docker image (no AI) | XGB | +| Docker image (with all AI bundles) | XGB | +| AI model: background-removal | XGB | +| AI model: upscale-enhance | XGB | +| AI model: face-detection | XMB | +| AI model: object-eraser-colorize | XGB | +| AI model: ocr | XGB | +| AI model: photo-restoration | XGB | +| Workspace (temp, per active job) | ~XMB | +| SQLite database (typical) | ~XMB | +| **Total (full system)** | **~XGB** | + +--- + +## Platform-Specific Notes + +### macOS +- Docker Desktop overhead: [measured] +- Apple Silicon performance vs x86 emulation: [if applicable] +- File system performance (virtiofs): [measured] + +### Windows (Docker Desktop) +- Docker Desktop overhead vs native Linux: [measured] +- WSL2 backend performance: [measured] +- Path handling differences: [any issues found] + +### Linux (Native Docker) +- Best raw performance: [confirmed/denied] +- Recommended distro notes: [any] +- cgroup v2 considerations: [any] + +--- + +## Environment Variable Tuning + +| Variable | Default | Minimum Tier | Recommended Tier | Full Tier | Description | +|----------|---------|-------------|-----------------|-----------|-------------| +| MAX_UPLOAD_SIZE_MB | 0 (unlimited) | 10 | 50 | 0 | Max single file size | +| MAX_BATCH_SIZE | 0 (unlimited) | 5 | 10 | 0 | Max files per batch | +| MAX_MEGAPIXELS | 0 (unlimited) | 25 | 100 | 0 | Max image dimensions | +| CONCURRENT_JOBS | 0 (auto) | 1 | 2 | 0 | Parallel processing | +| MAX_WORKER_THREADS | 0 (auto) | 2 | 4 | 0 | Sharp thread pool | +| PROCESSING_TIMEOUT_S | 0 (unlimited) | 60 | 300 | 0 | Per-job timeout | +| MAX_PIPELINE_STEPS | 0 (default 20) | 5 | 10 | 20 | Pipeline step limit | +| SESSION_DURATION_HOURS | 168 | 24 | 168 | 168 | Session TTL | +``` + +--- + +## Execution Rules + +1. **MAXIMUM PARALLELISM.** Spawn agents 1-6 simultaneously. Each system benchmarks independently. +2. **Opus 4.7 Max Effort 1M context** for every agent. No exceptions. +3. **Fix everything.** If benchmarks reveal bugs, crashes, or memory leaks, fix the code immediately. +4. **SOURCE OF TRUTH: LOCAL MAC CODEBASE.** All fixes go through local Mac, rsync to remotes. +5. **Reproducibility.** Run each benchmark 3 times and report the median. Discard obvious outliers. +6. **Cold cache.** Restart the container before each benchmark tier to avoid warm-cache bias. +7. **Use test fixtures only** from `tests/fixtures/`, `tests/fixtures/content/`, and `tests/fixtures/formats/`. +8. **Always use `--repo ashim-hq/ashim`** for any `gh` CLI commands. diff --git a/docs/prompts/INTERNAL_WIKI_GENERATOR.md b/docs/prompts/INTERNAL_WIKI_GENERATOR.md new file mode 100644 index 00000000..cf504c77 --- /dev/null +++ b/docs/prompts/INTERNAL_WIKI_GENERATOR.md @@ -0,0 +1,220 @@ +# Internal Wiki Generator + +## Role & System Directive + +Initialize as the Principal Knowledge Architect for the SnapOtter monorepo. Your objective is to autonomously generate a detailed internal wiki documenting every component, API, data flow, and infrastructure detail in this project. + +**Model Routing:** Follow CLAUDE.md model routing. Haiku for file search and quick lookups, Sonnet for standard writing and documentation, Opus only for complex architecture analysis. Do not over-provision agents. + +--- + +## TOP PRIORITY: MAXIMUM PARALLELIZATION + +After the wiki structure is approved, spawn the maximum number of parallel agent teams to write all documentation sections simultaneously. Each domain is independent and MUST run concurrently. Never run sequentially what can run in parallel. + +### Parallel Agent Architecture + +``` +Phase 0: Scaffolding (Sequential - needs approval) + └─> Create .local-wiki/, scaffold VitePress, generate WIKI_PLAN.md + │ +Phase 1: PARALLEL BLAST (after approval) ────────────────────── + │ │ + │ Agent 1: Frontend Architecture (Sonnet) │ + │ React 19 components, 14 Zustand stores, routing, │ + │ Vite config, Tailwind 4, 9 pages, hooks, tool registry │ + │ │ + │ Agent 2: Backend Architecture (Sonnet) │ + │ Fastify routes (16 + 48 tool routes), plugins, auth, │ + │ Drizzle ORM (10 tables), job system, SSE, 20 lib modules │ + │ │ + │ Agent 3: AI/ML Pipeline (Sonnet) │ + │ Python sidecar (16 scripts), bridge layer (14 modules), │ + │ GPU detection, model architectures, feature bundles │ + │ │ + │ Agent 4: Image Engine (Sonnet) │ + │ 18 Sharp operations, format detection (18 formats), │ + │ metadata handling, pipeline engine │ + │ │ + │ Agent 5: Infrastructure & DevOps (Sonnet) │ + │ Docker (3 Dockerfiles, 3 compose files), entrypoint, │ + │ 4 GitHub Actions workflows, semantic-release │ + │ │ + │ Agent 6: Testing Architecture (Sonnet) │ + │ 42 unit, 57 integration, 33 e2e, 21 e2e-docker tests, │ + │ 3 benchmarks, Vitest + Playwright configs │ + │ │ + │ Agent 7: Tool Reference Guide (Sonnet) │ + │ All 48 tools documented: API, parameters, UI, examples │ + │ │ + │ Agent 8: Landing & Docs Sites (Sonnet) │ + │ Next.js landing (11 components, 6 pages), │ + │ VitePress docs (12 guides, llms.txt, custom theme) │ + │ │ +Phase 2: Assembly (after all agents done) │ + └─> Wire sidebar, dead-link check, boot dev server │ +──────────────────────────────────────────────────────────────── +``` + +--- + +## CRITICAL DIRECTIVES + +1. **Ghost Directory:** All documentation goes in `.local-wiki/`. This directory must NEVER leak into version control. +2. **No Git:** Ensure `.local-wiki/` is in the root `.gitignore`. +3. **Read Source, Don't Guess:** Every agent must read actual `.ts`, `.py`, `.yml`, and config files. Do not guess or hallucinate architecture details. +4. **Fix Everything:** If you discover bugs, broken code, or issues while reading the source, fix them. We want zero known issues. + +--- + +## Phase 0: Scaffolding and Master Index + +### 0.1 Setup +```bash +mkdir -p .local-wiki +echo ".local-wiki/" >> .gitignore # if not already present +``` + +### 0.2 Scaffold VitePress +Initialize a VitePress installation inside `.local-wiki/` with: +- Clean theme configuration +- Sidebar navigation structure +- Search enabled +- Dark/light theme support + +### 0.3 Generate WIKI_PLAN.md + +Scan the entire monorepo and generate `.local-wiki/WIKI_PLAN.md` — a detailed table of contents that assigns every documentation file to a specific agent based on domain expertise. + +**Required sections (minimum):** + +**Frontend (Agent 1):** +- Component architecture — 58 tool components, 17 common, 5 layout, 5 file management, plus features/help/settings +- Zustand state management — all 14 stores (analytics, base64, collage, connection, duplicate, features, file, files-page, pdf-to-image, pipeline, qr, settings, split, theme) +- Routing and navigation — App.tsx, 9 pages, lazy-with-retry loading +- Build system — Vite 6 config, Tailwind CSS 4, PostCSS, asset handling +- Hooks — 8 custom hooks (auth, connection-monitor, gif-info, keyboard-shortcuts, mobile, pipeline-processor, theme, tool-processor) +- Utility libraries — 11 modules (api, analytics, collage-templates, download, icon-map, image-preview, metadata-utils, suggested-tools, tool-registry, utils, lazy-with-retry) +- i18n system (packages/shared/src/i18n/) + +**Backend (Agent 2):** +- Fastify server architecture — plugins (auth, static, upload), hooks, lifecycle +- Route registration — 16 top-level route files + tool-factory.ts pattern +- Tool routes — all 48 tools in `src/routes/tools/` +- Authentication flow — session tokens, API keys, RBAC (auth.ts plugin) +- Database schema — all 10 Drizzle ORM tables with relationships: + - users, teams, sessions, settings, jobs, apiKeys, pipelines, auditLog, roles, userFiles +- Job system — queuing, progress tracking, SSE (progress.ts) +- File handling — upload plugin, user-files.ts (18.5KB), file-storage lib +- Library modules — 20 modules in src/lib/ (analytics, audit, auto-orient, bg-effects, cleanup, env, errors, exiftool, feature-status, file-storage, file-validation, filename, format-decoders, heic-converter, image-worker, output-format, svg-sanitize, timeout, worker-pool, workspace) +- Rate limiting, security middleware, OpenAPI spec +- Pipeline engine (pipeline.ts, 25.6KB) +- Batch processing (batch.ts) +- Branding system (branding.ts) + +**AI/ML (Agent 3):** +- Python sidecar architecture — dispatcher.py, JSON-lines protocol +- TypeScript bridge layer — bridge.ts (13.6KB) + 13 capability modules (background-removal, colorization, face-detection, face-enhancement, face-landmarks, inpainting, noise-removal, ocr, red-eye-removal, restoration, seam-carving, upscaling) +- Python scripts — 16 scripts (colorize, detect_faces, enhance_faces, face_landmarks, inpaint, noise_removal, ocr, ocr_preprocess, red_eye_removal, remove_bg, restore, upscale, dispatcher, gpu, install_feature) +- Model architectures — NAFNet (nafnet_arch.py), SCUNet (scunet_arch.py) +- GPU detection and fallback behavior (gpu.py) +- Feature bundle install/uninstall system (install_feature.py) +- Model management — download_models.py, feature-manifest.json +- Memory management (VRAM, model loading/unloading) + +**Image Engine (Agent 4):** +- Sharp operation library — all 18 operations (auto-enhance, brightness, color-channels, compress, contrast, convert, crop, edit-metadata, flip, grayscale, invert, optimize-for-web, resize, rotate, saturation, sepia, sharpen, strip-metadata) +- Format support — detection system (formats/detect.ts), 18+ input formats (avif, bmp, dng, exr, gif, hdr, heic, heif, ico, jpg, jxl, png, psd, svg, tga, tiff, webp) +- Metadata handling — EXIF, GPS, ICC, XMP via ExifTool (lib/exiftool.ts) +- Engine architecture — engine.ts, types.ts, index.ts exports +- Utility modules — metadata.ts, mime.ts +- External tool integration — heif-dec, dcraw, ImageMagick, potrace, vtracer, caire + +**Infrastructure (Agent 5):** +- Docker build — 3 Dockerfiles (production, test, test.dockerignore) +- Compose configurations — 3 files (standard, GPU, test) +- Entrypoint script — entrypoint.sh logic and environment variables +- CI/CD — 4 GitHub Actions workflows (ci.yml, release.yml, deploy-docs.yml, deploy-landing.yml) +- Semantic-release configuration (.releaserc.json) +- Multi-arch build process +- Volume management (data, workspace) +- Model download pipeline (download_models.py, feature-manifest.json) +- Scripts — sync-version.sh, test-docker-fixes.sh +- Hooks — 5 Claude Code hooks in .claude/hooks/ (auto-tmux-dev, block-no-verify, config-protection, post-edit-format, suggest-compact) + +**Testing (Agent 6):** +- Test architecture overview and file counts: + - 42 unit tests (api: 11, web: 8, ai: 3, image-engine: 5, landing: 6, root: 9) + - 57 integration tests + test-server helper + - 33 e2e Playwright specs + auth setup + helpers + - 21 e2e-docker specs + full-tool-audit script + - 3 benchmark scripts (bench.sh, bench-ai.sh, bench-limits.sh) + - 1 image-engine package test +- Vitest configuration — vitest.config.ts (unit + integration) +- Playwright configuration — 3 configs (main, analytics, docker) +- Test helpers and fixtures — 14 base fixtures, 17 content fixtures, 18 format samples +- Coverage tooling + +**Tool Reference (Agent 7):** +- Every tool: ID, category, endpoint, all parameters with types/defaults/ranges +- Organized by category: + - **AI-powered** (12): blur-faces, colorize, content-aware-resize, enhance-faces, erase-object, noise-removal, ocr, red-eye-removal, remove-background, restore-photo, smart-crop, upscale + - **Image manipulation** (11): border, color-adjustments, compare, compose, compress, convert, crop, image-enhancement, optimize-for-web, replace-color, resize, rotate, sharpening + - **Metadata** (4): color-palette, edit-metadata, info, strip-metadata + - **Conversion/Export** (6): favicon, image-to-base64, image-to-pdf, pdf-to-image, svg-to-raster, vectorize + - **Multi-image** (4): collage, find-duplicates, split, stitch + - **Barcode/QR** (2): barcode-read, qr-generate + - **GIF** (1): gif-tools + - **Watermark** (2): watermark-image, watermark-text + - **Text** (1): text-overlay + - **Rename** (1): bulk-rename + - **Specialty** (1): passport-photo +- Sub-endpoints (inspect, preview, analyze, batch) +- UI component name and settings panel +- Example API calls (curl) +- Pipeline compatibility notes + +**Landing & Docs (Agent 8):** +- Landing site — Next.js static export, 11 components (bento-grid, enterprise, fade-in, footer, hero, how-it-works, navbar, open-source, pricing, typing-cursor, why-choose), 6 pages (home, contact, faq, privacy, terms) +- Docs site — VitePress with custom theme (Layout.vue, GitHubStars.vue), 9 guide pages, 3 API reference pages, llms.txt integration (vitepress-plugin-llms), CNAME configuration +- Shared package — constants.ts (28.3KB, all tool definitions), types.ts, features.ts, permissions.ts, analytics modules (consent, events, types), i18n/en.ts (11.9KB) + +### 0.4 Present Plan +**STOP.** Present `WIKI_PLAN.md` for approval before dispatching agents. + +--- + +## Phase 1: Parallel Deep-Dive (After Approval) + +Spawn ALL 8 agents in a single message. + +### Agent Writing Protocol (All Agents) + +1. **Read the actual source code** for your assigned domain. Open and read every relevant file. +2. **Write detailed Markdown** in `.local-wiki/docs/{domain}/` +3. **Include:** + - Code snippets showing key patterns + - "Why" explanations for architectural decisions + - Mermaid.js diagrams for: + - Sequence diagrams (e.g., Image Upload → Fastify → Sharp/Python → SQLite → Response) + - Database ERD diagrams + - Component hierarchy diagrams + - Data flow diagrams + - Configuration reference tables + - Environment variable documentation +4. **Report completion** when each file is done + +--- + +## Phase 2: Assembly and Wiring + +After all agents complete: + +1. **Update sidebar config** in `.local-wiki/.vitepress/config.mts` — wire every Markdown file into a categorized left-hand navigation +2. **Dead-link check** across all generated Markdown +3. **Cross-reference check** — ensure all internal links between pages resolve +4. **Boot dev server** and provide the exact command: + ```bash + cd .local-wiki && npm run docs:dev + ``` +5. **Provide the localhost URL** for review diff --git a/docs/prompts/QA_PROMPT.md b/docs/prompts/QA_PROMPT.md new file mode 100644 index 00000000..d9857a8a --- /dev/null +++ b/docs/prompts/QA_PROMPT.md @@ -0,0 +1,1131 @@ +# Ashim - Comprehensive QA Automation Prompt + +## Role & System Directive + +Initialize as the Principal QA Automation Architect for the Ashim monorepo. Your objective is a 100% regression and functional test sweep across all environments, covering every API endpoint, every GUI interaction, every input format, every auth flow, and every edge case. + +**Execution Engine:** Opus 4.7, Max Effort, 1M Token Context — for EVERY agent, EVERY subagent, no exceptions. Never downgrade models. + +--- + +## TOP PRIORITY: MAXIMUM PARALLELIZATION + +**Speed is the #1 priority.** You MUST spawn the maximum number of parallel Claude agent teams to execute this test matrix simultaneously. Do NOT run things sequentially when they can run in parallel. The only sequential dependency is Phase 0 (infrastructure) — once containers are healthy on all nodes, EVERYTHING ELSE runs in parallel across 15+ simultaneous agent streams. + +### Parallel Agent Architecture + +After infrastructure is ready, spawn ALL of the following agents in a SINGLE message with multiple Agent tool calls: + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ PHASE 0: INFRASTRUCTURE (Sequential) │ +│ Provision containers on all 3 nodes, verify health, obtain tokens │ +└──────────────────────────────┬──────────────────────────────────────────┘ + │ All containers healthy + ▼ +┌─────────────────── PARALLEL BLAST ──────────────────────────────────────┐ +│ │ +│ ┌─── WSL/GPU NODE (192.168.0.247:2222) ───┐ ┌─── UBUNTU CPU NODE ──┐ │ +│ │ │ │ (192.168.0.191) │ │ +│ │ Agent 1: GPU AI Tools API │ │ │ │ +│ │ remove-bg, upscale, enhance-faces, │ │ Agent 7: CPU Tool │ │ +│ │ colorize, noise-removal, restore, │ │ Parity │ │ +│ │ passport-photo, ocr, blur-faces, │ │ All 35 non-AI │ │ +│ │ smart-crop, erase-object, red-eye │ │ tools via API │ │ +│ │ + anti-fallback GPU verification │ │ │ │ +│ │ │ │ Agent 8: CPU Format │ │ +│ │ Agent 2: GPU Essential+Watermark API │ │ Matrix │ │ +│ │ resize, crop, rotate, convert, │ │ All 18 input │ │ +│ │ compress, strip-metadata, edit-meta, │ │ formats through │ │ +│ │ adjust-colors, sharpening, │ │ resize │ │ +│ │ watermark-text, watermark-image, │ │ │ │ +│ │ text-overlay, compose │ │ Agent 9: CPU AI │ │ +│ │ │ │ Fallback │ │ +│ │ Agent 3: GPU Utility+Layout+Format API │ │ Install bundles, │ │ +│ │ info, compare, find-duplicates, │ │ test CPU fallback │ │ +│ │ color-palette, qr-generate, │ │ for all 12 AI │ │ +│ │ barcode-read, image-to-base64, │ │ tools │ │ +│ │ collage, stitch, split, border, │ │ │ │ +│ │ svg-to-raster, vectorize, gif-tools, │ │ Agent 10: CPU │ │ +│ │ pdf-to-image, optimize-for-web, │ │ Batch+Pipeline │ │ +│ │ bulk-rename, favicon, image-to-pdf, │ │ Batch processing │ │ +│ │ replace-color, content-aware-resize, │ │ + pipeline tests │ │ +│ │ image-enhancement │ │ on CPU node │ │ +│ │ │ │ │ │ +│ │ Agent 4: GPU Batch + Pipeline │ └──────────────────────┘ │ +│ │ Batch processing all tools, │ │ +│ │ pipeline execution (single+batch), │ ┌─── MAC NODE (Local) ──┐│ +│ │ pipeline save/load/delete, │ │ ││ +│ │ SSE progress monitoring, │ │ Agent 11: Playwright ││ +│ │ "first-image-only" bug hunt │ │ Essential+Water- ││ +│ │ │ │ mark+Utility GUI ││ +│ │ Agent 5: GPU Format Matrix │ │ (tools 1-21) ││ +│ │ All 18 input formats through resize │ │ ││ +│ │ on GPU node │ │ Agent 12: Playwright ││ +│ │ │ │ Layout+Format+ ││ +│ └──────────────────────────────────────────┘ │ Optimize+AI GUI ││ +│ │ (tools 22-48) ││ +│ ┌─── ANY NODE (stateless tests) ──────────┐ │ ││ +│ │ │ │ Agent 13: Playwright ││ +│ │ Agent 6: Auth + RBAC + Security │ │ Nav+Auth+Settings ││ +│ │ Auth system (20 tests), │ │ +Files+Pipeline ││ +│ │ API keys (10 tests), │ │ +Batch+Theme GUI ││ +│ │ custom roles/RBAC (10 tests), │ │ ││ +│ │ teams (6 tests), │ └───────────────────────┘│ +│ │ audit log (4 tests), │ │ +│ │ settings (5 tests), │ ┌─── ANY NODE ──────────┐│ +│ │ branding (4 tests), │ │ ││ +│ │ AI features (5 tests), │ │ Agent 14: Security ││ +│ │ analytics/docs (5 tests), │ │ + Stress Testing ││ +│ │ health/upload/download (5 tests), │ │ All 16 security ││ +│ │ file library (10 tests), │ │ tests + 7 perf ││ +│ │ ALL 16 security tests, │ │ tests ││ +│ │ escalation/injection/traversal │ │ ││ +│ │ │ │ Agent 15: DB + ││ +│ └──────────────────────────────────────────┘ │ Cross-Platform ││ +│ │ Parity + Report ││ +│ ┌─── WINDOWS NODE (192.168.0.247) ────────┐ │ (runs last, after ││ +│ │ ssh siddh@192.168.0.247 (PowerShell) │ │ all others done) ││ +│ │ │ └──────────────────────┘│ +│ │ Agent 16: Windows Docker Desktop │ │ +│ │ Docker Desktop on native Windows, │ │ +│ │ PowerShell commands, Windows path │ │ +│ │ handling, run core tool API tests │ │ +│ │ + batch + pipeline to verify │ │ +│ │ Windows compatibility │ │ +│ │ │ │ +│ └──────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +### Agent Spawning Rules + +1. **Spawn agents 1-14 and 16 in a SINGLE message** with 15 parallel Agent tool calls after Phase 0 completes. +2. **Agent 15 (Report)** spawns AFTER agents 1-14 and 16 complete — it collects all results. +3. **Every agent uses Opus 4.7 Max Effort 1M context.** No exceptions. No model downgrading. +4. **Each agent is self-contained** — receives its full test list, connection details, auth token, and file paths. No agent depends on another agent's output (except Agent 15). +5. **Within each agent**, run independent API calls in parallel too (multiple curl commands via `&` or `xargs -P`). +6. **If any agent finds a bug**, it MUST fix it immediately in the source code, then notify the orchestrator to rebuild containers and re-test across all agents. + +--- + +## CRITICAL DIRECTIVE: PRODUCTION CONTAINERS ONLY + +You are strictly forbidden from spinning up local Node.js dev servers or Vite dev servers. ALL tests (integration, Playwright E2E, API contract) MUST execute against fully built Docker containers — the exact images users will run. Never use `pnpm dev`. + +**Container startup command:** +```bash +SKIP_MUST_CHANGE_PASSWORD=true docker compose -f docker/docker-compose.yml up -d --build +# For GPU node: +SKIP_MUST_CHANGE_PASSWORD=true docker compose -f docker/docker-compose-gpu.yml up -d --build +``` + +**Health verification before any testing:** +```bash +until curl -sf http://localhost:1349/api/v1/health; do sleep 2; done +``` + +--- + +## CRITICAL DIRECTIVE: FIX EVERYTHING + +Fix ALL bugs, warnings, deprecations, lint issues, and problems you encounter — even if they are completely unrelated to the test you are currently running. We want this software to be completely bug-free and always just working perfectly. No issue is out of scope. If you see it, fix it. + +- Console warnings in Docker logs → Fix them. +- Deprecation notices → Update the code. +- TypeScript type errors → Fix them. +- Lint violations → Fix them. +- Race conditions → Fix them. +- Memory leaks → Fix them. +- Accessibility issues → Fix them. +- Broken error messages → Fix them. + +After fixing any code, rebuild the Docker container and re-test to verify the fix. + +**SOURCE OF TRUTH: LOCAL MAC CODEBASE.** ALL code changes MUST be made on the local Mac codebase first, then rsync'd to remote test nodes (Ubuntu, WSL). Never fix code directly on a remote system. The local codebase is what gets pushed to GitHub. If you fix a bug on a remote node without updating the local codebase, the fix is lost and future tests will fail again. The workflow is always: fix locally, rsync to remotes, rebuild containers on remotes, re-test. + +--- + +## Multi-Agent Topology + +| Agent | Host | Connection | Shell | Role | +|-------|------|------------|-------|------| +| **Mac (Lead)** | Local macOS | Direct | zsh | Orchestrator. Runs Playwright E2E GUI suite via `playwright.docker.config.ts`. Validates downloads, screenshots, visual regression. | +| **WSL (GPU)** | 192.168.0.247:2222 | `ssh -p 2222 siddharth@192.168.0.247` | bash | Docker + NVIDIA RTX 4070 (12GB VRAM, CUDA 13.2). Owns all GPU-accelerated AI tests, model quality verification, anti-fallback checks. | +| **Windows** | 192.168.0.247 | `ssh siddh@192.168.0.247` | PowerShell/CMD | Native Windows. Tests Docker Desktop on Windows, PowerShell-based workflows, Windows-specific path handling and compatibility. | +| **Ubuntu** | 192.168.0.191 | `ssh ubuntuserver@192.168.0.191` | bash | Pure CPU Linux node. Install Docker if missing, build and run CPU-only container. Tests CPU fallback behavior, headless API-only validation, cross-platform parity. SSH key already configured. | + +**Important:** `ssh siddh@192.168.0.247` is native Windows (PowerShell/CMD). `ssh -p 2222 siddharth@192.168.0.247` is WSL on the same machine. They are different environments on the same hardware. + +**Setup Ubuntu if Docker missing:** +```bash +ssh ubuntuserver@192.168.0.191 'sudo apt-get update && sudo apt-get install -y docker.io docker-compose-v2 && sudo usermod -aG docker $USER' +``` + +--- + +## Test Assets + +**Primary fixtures** (committed to repo): +``` +tests/fixtures/ + test-100x100.jpg, test-100x100.svg, test-1x1.png, test-200x150.heic, + test-200x150.png, test-3page.pdf, test-50x50.webp, test-blank.png, + test-portrait.heic, test-portrait.jpg, test-with-exif.jpg, animated.gif + +tests/fixtures/content/ + animated-simpsons.gif # GIF tool testing + barcode.avif # Barcode reading + cross-format-chat.webp # Cross-format validation + motorcycle.heif # HEIF decode testing + multi-face.webp # Multi-face detection (blur-faces, enhance-faces) + ocr-chat.jpeg # English OCR + ocr-japanese.png # Japanese OCR (language=ja) + portrait-bw.jpeg (2.7MB) # Colorize, restore-photo + portrait-color.jpg # Face enhance, passport-photo, smart-crop + portrait-headshot.heic # HEIC face tools + portrait-isolated.png # Remove-background (already isolated - edge case) + qr-code.avif # Barcode/QR reading + qr-code.svg # SVG QR + red-eye.jpg # Red-eye removal + stress-large.jpg (6.7MB) # Stress/memory testing + svg-logo.svg # SVG-to-raster, vectorize + watermark.jpg # Watermark overlay base + +tests/fixtures/formats/ # 18 FORMAT COVERAGE + sample.avif, sample.bmp, sample.dng (RAW), sample.exr, sample.gif, + sample.hdr, sample.heic, sample.heif, sample.ico, sample.jpg, + sample.jxl, sample.png, sample.psd, sample.svg, sample.tga, + sample.tiff, sample.webp, multipage.tiff +``` + +All test images come exclusively from `tests/fixtures/` and its subdirectories (`content/`, `formats/`). Do NOT use any external folders. + +--- + +## Phase 0: Infrastructure Provisioning (Sequential — Must Complete Before Parallel Blast) + +### 0.1 Code Analysis +- Run `git status` and `git log --oneline -20` on Mac to understand recent changes. +- Run `git diff HEAD~5..HEAD --stat` to see scope of recent modifications. + +### 0.2 Container Deployment (parallel across all 3 nodes) + +Spawn 3 parallel agents to provision all nodes simultaneously: + +- **WSL (GPU):** `ssh -p 2222 siddharth@192.168.0.247` → rsync codebase → `docker compose -f docker/docker-compose-gpu.yml up -d --build` → Verify `nvidia-smi` → Check Docker logs for `GPU detected` → Wait for health endpoint. +- **Ubuntu (CPU):** `ssh ubuntuserver@192.168.0.191` → Install Docker if missing → rsync codebase → `docker compose -f docker/docker-compose.yml up -d --build` → Wait for health endpoint. +- **Mac:** Verify remote containers are accessible: `curl http://192.168.0.247:1349/api/v1/health` and `curl http://192.168.0.191:1349/api/v1/health`. + +### 0.3 Obtain Auth Tokens (on each node) +```bash +TOKEN=$(curl -s -X POST http://localhost:1349/api/auth/login \ + -H 'Content-Type: application/json' \ + -d '{"username":"admin","password":"admin"}' | jq -r '.token') +``` + +### 0.4 Install AI Bundles (on GPU and CPU nodes in parallel) +```bash +for bundle in background-removal face-detection upscale-enhance object-eraser-colorize ocr photo-restoration; do + curl -X POST "http://localhost:1349/api/v1/admin/features/$bundle/install" \ + -H "Authorization: Bearer $TOKEN" & +done +wait +# Poll until all installed: +until curl -s http://localhost:1349/api/v1/features -H "Authorization: Bearer $TOKEN" | jq -e '.[] | select(.installed != true)' | wc -l | grep -q '^0$'; do sleep 10; done +``` + +**Once all 3 nodes are healthy and AI bundles installed → LAUNCH THE PARALLEL BLAST** + +--- + +## Agent 1: GPU AI Tools API Tests (WSL Node) + +**Connection:** `ssh -p 2222 siddharth@192.168.0.247` +**Target:** `http://localhost:1349` +**Test count:** 35 tests + +For every test: send `POST` with valid file and settings, verify HTTP 200, correct output, file size > 0. + +| # | Tool | Endpoint | Test File | Key Settings | Verify | +|---|------|----------|-----------|--------------|--------| +| 1 | **remove-background** (transparent) | `POST /api/v1/tools/remove-background` | portrait-isolated.png | `backgroundType=transparent` | Check CUDA in logs | +| 2 | **remove-background** (color bg) | same | portrait-color.jpg | `backgroundType=color, backgroundColor=#0000FF` | Blue background applied | +| 3 | **remove-background** (blur bg) | same | portrait-color.jpg | `backgroundType=blur, blurRadius=20` | Blurred original as bg | +| 4 | **remove-bg/effects** (phase 2) | `POST /api/v1/tools/remove-background/effects` | Use jobId from #1 | `backgroundType=gradient` | No AI re-run, uses cached mask | +| 5 | **upscale** (2x) | `POST /api/v1/tools/upscale` | test-100x100.jpg | `scale=2, format=png` | Output is 200x200, ESRGAN model used | +| 6 | **upscale** (with face) | same | portrait-color.jpg | `scale=2, faceEnhance=true` | Upscaled with face enhancement | +| 7 | **ocr** (English fast) | `POST /api/v1/tools/ocr` | ocr-chat.jpeg | `quality=fast, language=en` | Correct text extraction | +| 8 | **ocr** (English best) | same | ocr-chat.jpeg | `quality=best, language=en` | Higher accuracy extraction | +| 9 | **ocr** (Japanese) | same | ocr-japanese.png | `quality=balanced, language=ja` | Japanese text extracted | +| 10 | **ocr** (auto language) | same | ocr-chat.jpeg | `quality=balanced, language=auto` | Auto-detected language | +| 11 | **blur-faces** | `POST /api/v1/tools/blur-faces` | multi-face.webp | `blurRadius=30, sensitivity=0.5` | All faces blurred, face count > 1 | +| 12 | **blur-faces** (single) | same | portrait-color.jpg | `blurRadius=50` | Single face blurred | +| 13 | **smart-crop** (face) | `POST /api/v1/tools/smart-crop` | portrait-color.jpg | `mode=face, facePreset=head-shoulders, width=400, height=400` | Face-centered crop | +| 14 | **smart-crop** (subject) | same | portrait-isolated.png | `mode=subject, width=300, height=300, padding=10` | Subject-centered | +| 15 | **smart-crop** (trim) | same | test-blank.png | `mode=trim, threshold=10` | Whitespace trimmed | +| 16 | **erase-object** | `POST /api/v1/tools/erase-object` | portrait-color.jpg + mask.png | `format=png` | Object under mask removed (LaMa) | +| 17 | **colorize** | `POST /api/v1/tools/colorize` | portrait-bw.jpeg | `intensity=1.0, model=auto` | Color version of B&W photo | +| 18 | **colorize** (low intensity) | same | portrait-bw.jpeg | `intensity=0.5` | Partially colorized | +| 19 | **enhance-faces** (gfpgan) | `POST /api/v1/tools/enhance-faces` | portrait-color.jpg | `model=gfpgan, strength=0.8` | Face enhanced | +| 20 | **enhance-faces** (codeformer) | same | portrait-color.jpg | `model=codeformer, strength=0.7` | Face enhanced | +| 21 | **enhance-faces** (multi) | same | multi-face.webp | `model=auto, onlyCenterFace=false` | All faces enhanced | +| 22 | **noise-removal** (quick) | `POST /api/v1/tools/noise-removal` | test-200x150.png | `tier=quick, strength=0.5` | Denoised | +| 23 | **noise-removal** (quality) | same | stress-large.jpg | `tier=quality, strength=0.8, detailPreservation=0.5` | High-quality denoise | +| 24 | **red-eye-removal** | `POST /api/v1/tools/red-eye-removal` | red-eye.jpg | `sensitivity=50, strength=80` | Red eyes corrected | +| 25 | **restore-photo** (auto) | `POST /api/v1/tools/restore-photo` | portrait-bw.jpeg | `mode=auto, scratchRemoval=true, faceEnhancement=true, colorize=true` | Full restoration pipeline | +| 26 | **restore-photo** (light) | same | portrait-color.jpg | `mode=light, faceEnhancement=true, denoise=true` | Light restoration | +| 27 | **passport-photo/analyze** | `POST /api/v1/tools/passport-photo/analyze` | portrait-headshot.heic | (none) | Returns preview + face landmarks | +| 28 | **passport-photo/generate** (US) | `POST /api/v1/tools/passport-photo/generate` | Use jobId from #27 | `countryCode=US, documentType=passport, printLayout=true, dpi=300` | US passport spec (2x2 inch) | +| 29 | **passport-photo/generate** (GB) | same | same | `countryCode=GB` | UK spec dimensions | +| 30 | **passport-photo/generate** (IN) | same | same | `countryCode=IN` | India spec dimensions | +| 31 | **passport-photo/generate** (JP) | same | same | `countryCode=JP` | Japan spec dimensions | +| 32 | **content-aware-resize** | `POST /api/v1/tools/content-aware-resize` | stress-large.jpg | `width=500` | Seam-carved, subjects preserved | +| 33 | **content-aware-resize** (face) | same | portrait-color.jpg | `width=300, protectFaces=true` | Face not distorted | +| 34 | **image-enhancement** (auto) | `POST /api/v1/tools/image-enhancement` | test-200x150.png | `mode=auto, intensity=50` | Auto-enhanced | +| 35 | **image-enhancement/analyze** | `POST /api/v1/tools/image-enhancement/analyze` | test-200x150.png | (none) | JSON corrections analysis | + +**After all AI tests, run Anti-Fallback Check:** +```bash +docker logs ashim 2>&1 | grep -iE "(GPU|CUDA|cpu.fallback|model.loaded|VRAM|device)" +``` +Verify: `GPU detected` / `CUDA available` in logs. ESRGAN, GFPGAN, CodeFormer, DDColor, rembg all using GPU. No `RuntimeError: CUDA out of memory`. No silent CPU fallbacks. + +--- + +## Agent 2: GPU Essential + Watermark API Tests (WSL Node) + +**Connection:** `ssh -p 2222 siddharth@192.168.0.247` +**Target:** `http://localhost:1349` +**Test count:** 35 tests + +| # | Tool | Endpoint | Test File | Key Settings | Verify | +|---|------|----------|-----------|--------------|--------| +| 1 | **resize** | `POST /api/v1/tools/resize` | test-200x150.png | `width=100, height=75, fit=cover` | Output is 100x75 | +| 2 | **resize** (percentage) | same | test-200x150.png | `percentage=50` | Output is 100x75 | +| 3 | **resize** (withoutEnlargement) | same | test-100x100.jpg | `width=200, withoutEnlargement=true` | Output stays 100x100 | +| 4 | **crop** | `POST /api/v1/tools/crop` | test-200x150.png | `left=10, top=10, width=50, height=50, unit=px` | Output is 50x50 | +| 5 | **crop** (percent) | same | test-200x150.png | `left=10, top=10, width=50, height=50, unit=percent` | Proportional crop | +| 6 | **rotate** | `POST /api/v1/tools/rotate` | test-100x100.jpg | `angle=90` | Width/height swapped | +| 7 | **rotate** (flip) | same | test-100x100.jpg | `angle=0, horizontal=true, vertical=true` | No dimension change | +| 8 | **convert** (jpg->png) | `POST /api/v1/tools/convert` | test-100x100.jpg | `format=png` | Output is PNG | +| 9 | **convert** (png->webp) | same | test-200x150.png | `format=webp, quality=80` | Output is WebP | +| 10 | **convert** (png->avif) | same | test-200x150.png | `format=avif, quality=50` | Output is AVIF | +| 11 | **convert** (to tiff) | same | test-100x100.jpg | `format=tiff` | Output is TIFF | +| 12 | **convert** (to gif) | same | test-100x100.jpg | `format=gif` | Output is GIF | +| 13 | **compress** (quality) | `POST /api/v1/tools/compress` | stress-large.jpg | `mode=quality, quality=60` | Output smaller than input | +| 14 | **compress** (targetSize) | same | stress-large.jpg | `mode=targetSize, targetSizeKb=500` | Output ~500KB | +| 15 | **strip-metadata** | `POST /api/v1/tools/strip-metadata` | test-with-exif.jpg | `stripAll=true` | No EXIF in output | +| 16 | **strip-metadata/inspect** | `POST /api/v1/tools/strip-metadata/inspect` | test-with-exif.jpg | (none) | Returns JSON with EXIF data | +| 17 | **edit-metadata** | `POST /api/v1/tools/edit-metadata` | test-with-exif.jpg | `title=Test, author=QA, clearGps=true` | Metadata updated, GPS cleared | +| 18 | **edit-metadata/inspect** | `POST /api/v1/tools/edit-metadata/inspect` | test-with-exif.jpg | (none) | Returns full ExifTool JSON | +| 19 | **adjust-colors** | `POST /api/v1/tools/adjust-colors` | test-200x150.png | `brightness=20, contrast=10, saturation=15` | Valid output | +| 20 | **adjust-colors** (grayscale) | same | test-200x150.png | `effect=grayscale` | Output is grayscale | +| 21 | **adjust-colors** (sepia) | same | test-200x150.png | `effect=sepia` | Output has sepia tone | +| 22 | **adjust-colors** (invert) | same | test-200x150.png | `effect=invert` | Colors inverted | +| 23 | **adjust-colors** (channels) | same | test-200x150.png | `red=1.5, green=0.8, blue=1.2` | Channel-adjusted output | +| 24 | **sharpening** (adaptive) | `POST /api/v1/tools/sharpening` | test-200x150.png | `method=adaptive, sigma=1.5` | Sharpened output | +| 25 | **sharpening** (unsharp) | same | test-200x150.png | `method=unsharp-mask, amount=1.5, radius=2, threshold=5` | Sharpened output | +| 26 | **sharpening** (high-pass) | same | test-200x150.png | `method=high-pass, strength=0.5, kernelSize=3` | Sharpened output | +| 27 | **sharpening** (with denoise) | same | test-200x150.png | `method=adaptive, sigma=1.5, denoise=medium` | Sharpened + denoised | +| 28 | **watermark-text** | `POST /api/v1/tools/watermark-text` | watermark.jpg | `text=ASHIM QA, fontSize=48, color=#FF0000, opacity=0.5, position=center` | Text visible | +| 29 | **watermark-text** (tiled) | same | watermark.jpg | `text=DRAFT, position=tiled, rotation=45, opacity=0.3` | Tiled pattern | +| 30 | **watermark-image** | `POST /api/v1/tools/watermark-image` | watermark.jpg + svg-logo.svg | `position=bottom-right, opacity=0.7, scale=0.2` | Logo overlaid | +| 31 | **text-overlay** | `POST /api/v1/tools/text-overlay` | test-200x150.png | `text=Hello World, fontSize=24, color=#FFFFFF, position=bottom, backgroundBox=true, shadow=true` | Text with bg+shadow | +| 32 | **compose** (overlay) | `POST /api/v1/tools/compose` | test-200x150.png + test-100x100.jpg | `x=10, y=10, opacity=0.8, blendMode=overlay` | Composited output | +| 33 | **compose** (multiply) | same | same | `blendMode=multiply` | Multiply blend | +| 34 | **compose** (screen) | same | same | `blendMode=screen` | Screen blend | +| 35 | **compose** (difference) | same | same | `blendMode=difference` | Difference blend | + +--- + +## Agent 3: GPU Utility + Layout + Format + Optimization API Tests (WSL Node) + +**Connection:** `ssh -p 2222 siddharth@192.168.0.247` +**Target:** `http://localhost:1349` +**Test count:** 44 tests + +| # | Tool | Endpoint | Test File(s) | Key Settings | Verify | +|---|------|----------|-------------|--------------|--------| +| 1 | **info** | `POST /api/v1/tools/info` | test-200x150.png | (none) | JSON: width=200, height=150, format=png, histogram | +| 2 | **info** (HEIC) | same | test-200x150.heic | (none) | Correct dimensions decoded | +| 3 | **compare** (identical) | `POST /api/v1/tools/compare` | test-200x150.png x2 | (none) | similarity=100% | +| 4 | **compare** (different) | same | test-200x150.png + test-100x100.jpg | (none) | similarity < 100%, diff image | +| 5 | **find-duplicates** | `POST /api/v1/tools/find-duplicates` | 3 images (include dupe) | `threshold=5` | Groups identical, space saveable | +| 6 | **color-palette** | `POST /api/v1/tools/color-palette` | portrait-color.jpg | (none) | Array of hex colors (up to 8) | +| 7 | **qr-generate** | `POST /api/v1/tools/qr-generate` | (JSON body) | `text=https://ashim.app, size=500, errorCorrection=H` | Valid QR PNG | +| 8 | **barcode-read** | `POST /api/v1/tools/barcode-read` | barcode.avif | `tryHarder=true` | Barcode text, type, positions | +| 9 | **barcode-read** (QR) | same | qr-code.avif | (none) | QR text content | +| 10 | **image-to-base64** | `POST /api/v1/tools/image-to-base64` | test-200x150.png | `outputFormat=webp, quality=80, maxWidth=100` | Base64 string | +| 11 | **image-to-base64** (multi) | same | 2 images | `outputFormat=jpeg` | Array of base64 strings | +| 12 | **collage** (2 images) | `POST /api/v1/tools/collage` | 2 images | `templateId=2-side-by-side, aspectRatio=16:9, gap=4` | Collage output | +| 13 | **collage** (4 images) | same | 4 images | `templateId=4-grid, aspectRatio=1:1` | 2x2 grid | +| 14 | **stitch** (horizontal) | `POST /api/v1/tools/stitch` | 2 images | `direction=horizontal, resizeMode=fit, gap=4` | Stitched | +| 15 | **stitch** (vertical) | same | 2 images | `direction=vertical, alignment=center` | Stitched | +| 16 | **stitch** (grid) | same | 4 images | `direction=grid, gridColumns=2` | 2x2 grid | +| 17 | **split** | `POST /api/v1/tools/split` | test-200x150.png | `columns=2, rows=2, outputFormat=png` | ZIP with 4 tiles | +| 18 | **split** (custom tile) | same | stress-large.jpg | `tileWidth=200, tileHeight=200` | ZIP with correct tile count | +| 19 | **border** | `POST /api/v1/tools/border` | test-200x150.png | `borderWidth=10, borderColor=#FF0000, cornerRadius=20, shadow=true` | Bordered with shadow | +| 20 | **svg-to-raster** | `POST /api/v1/tools/svg-to-raster` | svg-logo.svg | `width=500, outputFormat=png, backgroundColor=#FFFFFF` | 500px PNG | +| 21 | **svg-to-raster** (high DPI) | same | svg-logo.svg | `dpi=300, outputFormat=jpg, quality=90` | High-res JPEG | +| 22 | **svg-to-raster/batch** | `POST /api/v1/tools/svg-to-raster/batch` | 2 SVGs | (none) | ZIP with 2 files | +| 23 | **vectorize** (bw) | `POST /api/v1/tools/vectorize` | test-200x150.png | `colorMode=bw, threshold=128` | SVG output | +| 24 | **vectorize** (color) | same | portrait-color.jpg | `colorMode=color, colorPrecision=6` | Color SVG | +| 25 | **gif-tools** (resize) | `POST /api/v1/tools/gif-tools` | animated.gif | `mode=resize, percentage=50` | Smaller animated GIF | +| 26 | **gif-tools** (optimize) | same | animated-simpsons.gif | `mode=optimize, colors=128` | Smaller file | +| 27 | **gif-tools** (speed) | same | animated.gif | `mode=speed, speedFactor=2` | Faster playback | +| 28 | **gif-tools** (reverse) | same | animated.gif | `mode=reverse` | Reversed frames | +| 29 | **gif-tools** (extract all) | same | animated.gif | `mode=extract, extractMode=all` | ZIP with frames | +| 30 | **gif-tools** (extract single) | same | animated.gif | `mode=extract, extractMode=single, frameNumber=1` | Single frame | +| 31 | **gif-tools** (rotate) | same | animated.gif | `mode=rotate, angle=90` | Rotated GIF | +| 32 | **gif-tools/info** | `POST /api/v1/tools/gif-tools/info` | animated.gif | (none) | Frame count, delays, duration | +| 33 | **pdf-to-image** (all pages) | `POST /api/v1/tools/pdf-to-image` | test-3page.pdf | `format=png, dpi=150, pages=1-3` | ZIP with 3 PNGs | +| 34 | **pdf-to-image** (single) | same | test-3page.pdf | `format=jpg, dpi=72, pages=1` | Single JPEG | +| 35 | **pdf-to-image** (grayscale) | same | test-3page.pdf | `colorMode=grayscale, dpi=150` | Grayscale output | +| 36 | **pdf-to-image/info** | `POST /api/v1/tools/pdf-to-image/info` | test-3page.pdf | (none) | `{pageCount: 3}` | +| 37 | **pdf-to-image/preview** | `POST /api/v1/tools/pdf-to-image/preview` | test-3page.pdf | (none) | Thumbnail previews | +| 38 | **optimize-for-web** | `POST /api/v1/tools/optimize-for-web` | stress-large.jpg | `format=webp, quality=80, maxWidth=1920, stripMetadata=true` | WebP < original | +| 39 | **optimize-for-web/preview** | `POST /api/v1/tools/optimize-for-web/preview` | same | same | Binary with size headers | +| 40 | **bulk-rename** | `POST /api/v1/tools/bulk-rename` | 2 images | `pattern=ashim_{{padded}}, startIndex=1` | ZIP with renamed files | +| 41 | **favicon** | `POST /api/v1/tools/favicon` | test-200x150.png | (none) | ZIP: 16/32/48/180/192/512px, ICO, manifest | +| 42 | **image-to-pdf** | `POST /api/v1/tools/image-to-pdf` | 2 images | `pageSize=A4, orientation=portrait, margin=20` | Multi-page PDF | +| 43 | **replace-color** | `POST /api/v1/tools/replace-color` | test-200x150.png | `sourceColor=#FFFFFF, targetColor=#FF0000, tolerance=30` | White→red | +| 44 | **replace-color** (transparent) | same | test-200x150.png | `sourceColor=#FFFFFF, makeTransparent=true, tolerance=30` | White→transparent | + +--- + +## Agent 4: GPU Batch + Pipeline Tests (WSL Node) + +**Connection:** `ssh -p 2222 siddharth@192.168.0.247` +**Target:** `http://localhost:1349` +**Test count:** 20 tests + +### Batch Processing (8 tests) + +| # | Test | Description | +|---|------|-------------| +| 1 | **Batch resize** | `POST /api/v1/tools/resize/batch` with 5 images → ZIP with all 5 resized | +| 2 | **Batch convert** | 5 JPGs → WebP batch → ZIP with 5 WebPs | +| 3 | **Batch compress** | 3 large images → All compressed in ZIP | +| 4 | **Batch watermark-text** | 3 images with same watermark → All watermarked | +| 5 | **"First-Image-Only" Bug Hunt** | Send 5 images to any batch endpoint → Verify ZIP contains EXACTLY 5 processed files, not just 1 | +| 6 | **Batch with mixed formats** | JPG + PNG + WebP + HEIC → All processed correctly | +| 7 | **Large batch** | 10+ images through resize → All complete, none dropped | +| 8 | **Batch SSE progress** | Monitor `GET /api/v1/jobs/:jobId/progress` SSE stream during batch → Verify totalFiles, completedFiles increment correctly | + +### Pipeline/Automate (12 tests) + +| # | Test | Description | +|---|------|-------------| +| 9 | **Simple pipeline** | Execute: [resize(width=100)] → Output is 100px wide | +| 10 | **2-step pipeline** | [resize(width=200), convert(format=webp)] → 200px WebP | +| 11 | **3-step pipeline** | [crop(50,50,100,100), rotate(90), compress(quality=70)] → All applied | +| 12 | **5-step pipeline** | [resize, adjust-colors(grayscale), sharpening, compress, convert(png)] → All 5 steps | +| 13 | **Pipeline with AI tool** | [remove-background, resize(200)] → BG removed then resized | +| 14 | **Pipeline batch** | `POST /api/v1/pipeline/batch` 3 images through [resize, convert] → ZIP with 3 | +| 15 | **Save pipeline** | `POST /api/v1/pipeline/save` → Stored in DB | +| 16 | **List pipelines** | `GET /api/v1/pipeline/list` → Saved pipeline appears | +| 17 | **Delete pipeline** | `DELETE /api/v1/pipeline/:id` → Removed | +| 18 | **Available tools** | `GET /api/v1/pipeline/tools` → Valid tool IDs | +| 19 | **Max steps limit** | Pipeline with 21+ steps → 400 error (max 20) | +| 20 | **Invalid tool in pipeline** | Nonexistent toolId → Clear error | + +--- + +## Agent 5: GPU Format Matrix (WSL Node) + +**Connection:** `ssh -p 2222 siddharth@192.168.0.247` +**Target:** `http://localhost:1349` +**Test count:** 18 tests + +Test EVERY supported input format through the `resize` tool (baseline format compatibility): + +| # | Format | Test File | Special Handling | Verify | +|---|--------|-----------|------------------|--------| +| 1 | JPEG | sample.jpg | Standard | Valid resized JPEG | +| 2 | PNG | sample.png | Alpha channel | Alpha preserved | +| 3 | WebP | sample.webp | WebP decode | Valid output | +| 4 | GIF | sample.gif | Static frame | Frame extracted | +| 5 | BMP | sample.bmp | BMP decode | Valid output | +| 6 | TIFF | sample.tiff | TIFF decode | Valid output | +| 7 | Multi-page TIFF | multipage.tiff | First page | Handled correctly | +| 8 | AVIF | sample.avif | AV1 decode | Valid output | +| 9 | SVG | sample.svg | Sanitization + rasterize | Valid output | +| 10 | HEIC | sample.heic | heif-dec decode | Valid output | +| 11 | HEIF | sample.heif | heif-dec decode | Valid output | +| 12 | DNG (RAW) | sample.dng | dcraw decode | Valid output | +| 13 | PSD | sample.psd | ImageMagick decode | Valid output | +| 14 | TGA | sample.tga | TGA decode | Valid output | +| 15 | EXR | sample.exr | HDR tone mapping | Valid output | +| 16 | HDR | sample.hdr | HDR tone mapping | Valid output | +| 17 | ICO | sample.ico | Icon decode | Valid output | +| 18 | PDF | test-3page.pdf | pdf-to-image tool | Valid output | + +--- + +## Agent 6: Auth + RBAC + Admin API Tests (WSL or Ubuntu Node) + +**Target:** `http://localhost:1349` (either node) +**Test count:** 84 tests + +### Auth System (20 tests) + +| # | Test | Method | Endpoint | Verify | +|---|------|--------|----------|--------| +| 1 | Login success | POST | `/api/auth/login` | `{token, user: {id, username, role}}` | +| 2 | Login wrong password | POST | `/api/auth/login` | 401 | +| 3 | Login nonexistent user | POST | `/api/auth/login` | 401 | +| 4 | Login empty body | POST | `/api/auth/login` | 400 validation | +| 5 | Session validation | GET | `/api/auth/session` | User info with valid token | +| 6 | Session invalid token | GET | `/api/auth/session` | 401 | +| 7 | Logout | POST | `/api/auth/logout` | 200, session invalidated | +| 8 | Post-logout session check | GET | `/api/auth/session` | 401 (old token rejected) | +| 9 | Change password | POST | `/api/auth/change-password` | 200, old sessions revoked | +| 10 | Change password weak | POST | `/api/auth/change-password` | 400 (8+ chars, upper+lower+number) | +| 11 | Change password wrong current | POST | `/api/auth/change-password` | 401 | +| 12 | List users (admin) | GET | `/api/auth/users` | Array of users with roles | +| 13 | Register new user | POST | `/api/auth/register` | 201 | +| 14 | Register duplicate username | POST | `/api/auth/register` | 409 conflict | +| 15 | Update user role | PUT | `/api/auth/users/:id` | Role changed | +| 16 | Admin escalation prevention | POST | `/api/auth/register` | Cannot create admin as non-admin | +| 17 | Delete user (not self) | DELETE | `/api/auth/users/:id` | Deleted, sessions cascaded | +| 18 | Delete self prevention | DELETE | `/api/auth/users/:id` (own) | 400 | +| 19 | Last admin protection | PUT | `/api/auth/users/:id` | Cannot demote last admin | +| 20 | Reset user password (admin) | POST | `/api/auth/users/:id/reset-password` | Reset, sessions+keys revoked | + +### API Keys (10 tests) + +| # | Test | Verify | +|---|------|--------| +| 21 | Create API key | Returns `si_` prefix key | +| 22 | List API keys | Array without raw keys | +| 23 | Use API key for auth | Tool works with `si_...` | +| 24 | Scoped permissions | `permissions: ["tools:use"]` — tools work, user management blocked | +| 25 | Scoped key rejected | 403 with tools-only key on admin endpoint | +| 26 | Delete API key | Key invalidated | +| 27 | Deleted key rejected | 401 | +| 28 | Key with expiration | Past expiry → immediately invalid | +| 29 | Key lastUsedAt updated | After use, timestamp updated | +| 30 | Admin sees all keys | `apikeys:all` permission | + +### Custom Roles & RBAC (10 tests) + +| # | Test | Verify | +|---|------|--------| +| 31 | List roles | Built-in (admin, editor, user) + custom | +| 32 | Create custom role | `permissions: ["tools:use", "files:own"]` | +| 33 | Assign custom role | User gets custom permissions | +| 34 | Custom role can use tools | Tool endpoint works | +| 35 | Custom role cannot manage users | 403 on `/api/auth/users` | +| 36 | Update custom role | Permissions changed | +| 37 | Delete custom role | Users reassigned to "user" | +| 38 | Cannot modify built-in roles | 400 on admin role | +| 39 | Escalation prevention | Editor creating admin-level role → Blocked | +| 40 | Permission matrix sweep | All 15 permissions verified per role | + +### Teams (6 tests) + +| # | Test | Verify | +|---|------|--------| +| 41 | List teams | Teams with member counts | +| 42 | Create team | New team created | +| 43 | Rename team | Name updated | +| 44 | Delete empty team | Removed | +| 45 | Delete team with members | 400 | +| 46 | Delete Default team | 400 | + +### Audit Log (4 tests) + +| # | Test | Verify | +|---|------|--------| +| 47 | Read audit log | Paginated entries | +| 48 | Filter by action | `?action=user.login` → Only login events | +| 49 | Filter by date range | Time-bounded results | +| 50 | Events recorded | login/register/delete events appear | + +### Settings (5 tests) + +| # | Test | Verify | +|---|------|--------| +| 51 | Get all settings | Key-value object | +| 52 | Get specific setting | Single value | +| 53 | Update settings (admin) | Persisted | +| 54 | Update settings (non-admin) | 403 | +| 55 | HTML injection prevention | `