mirror of
https://github.com/snapotter-hq/SnapOtter.git
synced 2026-08-03 07:46:42 +02:00
chore: track reusable prompt templates in docs/prompts/
Un-ignore docs/prompts/ and update the internal wiki generator prompt to reflect current codebase state (48 tools, 8 agents, accurate component/test/store counts, landing app coverage).
This commit is contained in:
SnapOtter
@@ -40,6 +40,7 @@ CLAUDE.md
|
||||
.superpowers/
|
||||
docs/*
|
||||
!docs/COMMUNITY_GUIDE.md
|
||||
!docs/prompts/
|
||||
PRD.md
|
||||
|
||||
# Ad-hoc test screenshots and reports
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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}
|
||||
```
|
||||
@@ -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.
|
||||
@@ -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
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,236 @@
|
||||
# Test Coverage Expansion
|
||||
|
||||
## Role & System Directive
|
||||
|
||||
Initialize as a Principal Software Development Engineer in Test (SDET) for the Ashim monorepo. Your objective is to dramatically increase code coverage across all layers (unit, integration, E2E, E2E-Docker) for all tools, AI features, and core utilities.
|
||||
|
||||
**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 write and run tests simultaneously. Each test track is independent and MUST run concurrently. Never run sequentially what can run in parallel.
|
||||
|
||||
### Parallel Agent Architecture
|
||||
|
||||
```
|
||||
Phase 0: Coverage Audit (Sequential - must complete first)
|
||||
└─> Run coverage tools, identify all gaps, present report for approval
|
||||
│
|
||||
Phase 1: PARALLEL BLAST (after approval) ─────────────────────────
|
||||
│ │
|
||||
│ Agent 1: Integration Tests - Batch A (8 complex tools) │
|
||||
│ collage, stitch, split, svg-to-raster, compose, │
|
||||
│ barcode-read, find-duplicates, compare │
|
||||
│ │
|
||||
│ Agent 2: Integration Tests - Batch B (9 medium tools) │
|
||||
│ border, watermark-image, watermark-text, text-overlay, │
|
||||
│ image-to-pdf, image-to-base64, favicon, │
|
||||
│ color-adjustments, color-palette, replace-color, sharpening │
|
||||
│ │
|
||||
│ Agent 3: Integration Tests - Batch C (6 simpler tools) │
|
||||
│ optimize-for-web, image-enhancement, info, │
|
||||
│ bulk-rename, qr-generate, vectorize │
|
||||
│ │
|
||||
│ Agent 4: AI Bridge Unit Tests (packages/ai/) │
|
||||
│ bridge.ts lifecycle, each tool bridge module, │
|
||||
│ dispatcher protocol, error propagation │
|
||||
│ │
|
||||
│ Agent 5: E2E-Docker Expansion │
|
||||
│ All 47+ tools against real Docker container, │
|
||||
│ batch workflows, pipeline chains │
|
||||
│ │
|
||||
│ Agent 6: Unit Test Gaps │
|
||||
│ image-engine format detection, metadata utils, │
|
||||
│ MIME mapping, engine pipeline, web stores │
|
||||
│ │
|
||||
│ Agent 7: Cross-Format Matrix Tests │
|
||||
│ Every tool x every format parameterized suite │
|
||||
│ │
|
||||
│ Agent 8: Edge Case and Adversarial Tests │
|
||||
│ Concurrent requests, memory pressure, corrupted files, │
|
||||
│ zero-byte files, unicode filenames, 1x1 images │
|
||||
│ │
|
||||
Phase 2: Verification (after all agents done) │
|
||||
└─> Full test suite run, lint, typecheck, coverage report │
|
||||
───────────────────────────────────────────────────────────────────
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CRITICAL DIRECTIVE: FIX EVERYTHING
|
||||
|
||||
When any test reveals a bug, warning, deprecation, or issue:
|
||||
1. Document it clearly in the test expectation
|
||||
2. Fix the underlying code immediately
|
||||
3. Ensure the test passes with the fix
|
||||
4. Run surrounding tests to verify no regressions
|
||||
|
||||
Do NOT skip or mark tests as `.todo`/`.skip` for real bugs. Fix them. Zero tolerance for known issues, even if completely unrelated to your current test scope.
|
||||
|
||||
**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.
|
||||
|
||||
---
|
||||
|
||||
## Test Assets
|
||||
|
||||
### Root Fixtures (`tests/fixtures/`) -- Small/fast unit tests
|
||||
|
||||
test-100x100.jpg, test-1x1.png, test-200x150.png, test-200x150.heic, test-with-exif.jpg, test-portrait.jpg, test-portrait.heic, test-blank.png, test-50x50.webp, test-100x100.svg, animated.gif, test-3page.pdf
|
||||
|
||||
### Content Fixtures (`tests/fixtures/content/`) -- Realistic test images
|
||||
|
||||
| File | Content | Test Value |
|
||||
|------|---------|------------|
|
||||
| portrait-bw.jpeg (2.7MB) | B&W portrait | Colorize, restore, grayscale detection |
|
||||
| portrait-color.jpg | Color portrait | Face enhance, passport, smart crop |
|
||||
| portrait-headshot.heic | HEIC headshot | HEIC face tools |
|
||||
| portrait-isolated.png | Isolated subject | Remove-bg, already-isolated edge case |
|
||||
| multi-face.webp | Multiple faces | Multi-face detection stress test |
|
||||
| ocr-chat.jpeg | English text | OCR extraction |
|
||||
| ocr-japanese.png | Japanese text | Non-Latin OCR |
|
||||
| red-eye.jpg | Red-eye portrait | Red-eye removal |
|
||||
| stress-large.jpg (6.7MB) | Large file | Memory/performance stress |
|
||||
| barcode.avif | Barcode image | Barcode reading |
|
||||
| qr-code.avif | QR code | QR reading |
|
||||
| svg-logo.svg | SVG with effects | SVG operations |
|
||||
| animated-simpsons.gif | Animated GIF | GIF tools |
|
||||
| motorcycle.heif | HEIF no people | HEIF format, non-portrait |
|
||||
| watermark.jpg | Base image | Watermark testing |
|
||||
| cross-format-chat.webp | Same content as JPEG | Cross-format comparison |
|
||||
|
||||
### Format Fixtures (`tests/fixtures/formats/`) -- 18 format coverage
|
||||
|
||||
sample.jpg, sample.png, sample.webp, sample.avif, sample.bmp, sample.dng, sample.exr, sample.gif, sample.hdr, sample.heic, sample.heif, sample.ico, sample.jxl, sample.psd, sample.svg, sample.tga, sample.tiff, multipage.tiff
|
||||
|
||||
All test images come exclusively from `tests/fixtures/` and its subdirectories. Do NOT use any external folders.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0: Coverage Audit and Gap Analysis
|
||||
|
||||
### 0.1 Run Coverage Tools
|
||||
```bash
|
||||
pnpm test:unit --coverage
|
||||
pnpm test:integration --coverage
|
||||
```
|
||||
|
||||
### 0.2 Parse Coverage Reports
|
||||
Generate a prioritized list of files/modules with less than 80% branch or line coverage, focusing on:
|
||||
- AI routes (`apps/api/src/routes/tools/` - all AI tool files)
|
||||
- Tool routes with zero dedicated tests
|
||||
- React Zustand stores (`apps/web/src/stores/`)
|
||||
- Python sidecar dispatcher and scripts (`packages/ai/`)
|
||||
- Image engine utilities (`packages/image-engine/src/`)
|
||||
|
||||
### 0.3 Present Gap Report
|
||||
**STOP.** Present the coverage gap analysis as a structured table. Do not write any test code until explicitly told "Approved, proceed."
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Parallel Test Writing (After Approval)
|
||||
|
||||
Spawn ALL agents in a single message.
|
||||
|
||||
### Agent 1-3: Integration Tests for Untested Tool Routes
|
||||
|
||||
Use the existing test infrastructure (`buildTestApp`, `loginAsAdmin`, `createMultipartPayload` from test-server.ts).
|
||||
|
||||
**Each test file must cover:**
|
||||
- Valid input with default settings -> 200 success
|
||||
- Valid input with every parameter variation -> correct output
|
||||
- Missing file -> 400
|
||||
- Invalid parameters -> 400
|
||||
- Format-specific edge cases using fixture files
|
||||
- Output format verification (check dimensions, format, file size > 0)
|
||||
- Batch processing if the tool supports it (5+ images, verify ZIP contains all)
|
||||
- HEIC/HEIF input handling
|
||||
- Large file handling (stress-large.jpg)
|
||||
- Tiny file handling (test-1x1.png)
|
||||
|
||||
### Agent 4: AI Bridge Unit Tests (`packages/ai/`)
|
||||
|
||||
The entire `packages/ai/` package has zero test coverage. Write unit tests for:
|
||||
|
||||
- **bridge.ts:** Sidecar lifecycle (spawn, health check, timeout, restart, graceful shutdown)
|
||||
- **Each tool bridge module** (background-removal.ts, upscaling.ts, ocr.ts, etc.): request serialization, response parsing, error propagation, timeout handling
|
||||
- **Dispatcher protocol:** JSON-lines communication, request/response matching
|
||||
- **GPU detection:** `isGpuAvailable()` logic
|
||||
- Mock the Python sidecar. Do NOT require actual ML models for unit tests.
|
||||
|
||||
### Agent 5: E2E-Docker Expansion
|
||||
|
||||
Expand `tests/e2e-docker/` from 5 files to cover all 47+ tools against the real Docker container.
|
||||
|
||||
**Structure as tool-group spec files:**
|
||||
- `essential-tools.spec.ts` - resize, crop, rotate, convert, compress, metadata, colors, sharpening
|
||||
- `watermark-overlay-tools.spec.ts` - watermark-text, watermark-image, text-overlay, compose
|
||||
- `utility-tools.spec.ts` - info, compare, find-duplicates, color-palette, qr, barcode, base64
|
||||
- `layout-tools.spec.ts` - collage, stitch, split, border
|
||||
- `format-conversion-tools.spec.ts` - svg-to-raster, vectorize, gif-tools, pdf-to-image
|
||||
- `optimization-tools.spec.ts` - optimize-for-web, bulk-rename, favicon, image-to-pdf, replace-color
|
||||
- `ai-tools.spec.ts` - all 12 AI tools
|
||||
- `pipeline-tools.spec.ts` - single and batch pipeline execution
|
||||
- `batch-processing.spec.ts` - multi-file batch for every tool category
|
||||
|
||||
**Each test must:**
|
||||
- Use real fixture images for realistic inputs
|
||||
- Verify actual output (not just HTTP 200 -- check dimensions, format, file size > 0)
|
||||
- Test multi-file/batch workflows
|
||||
- Test pipeline automation with multi-step chains
|
||||
|
||||
### Agent 6: Unit Test Gaps
|
||||
|
||||
- `packages/image-engine/`: format detection (`formats/detect.ts`), metadata utilities (`utils/metadata.ts`), MIME mapping (`utils/mime.ts`), engine pipeline (`engine.ts`)
|
||||
- `apps/web/src/stores/`: any untested Zustand stores
|
||||
- `apps/api/src/routes/`: unit tests for complex helper functions
|
||||
|
||||
### Agent 7: Cross-Format Matrix Tests
|
||||
|
||||
Create a parameterized test suite that runs every applicable tool against every supported input format:
|
||||
|
||||
```
|
||||
formats = [JPEG, PNG, WebP, AVIF, HEIC, HEIF, GIF, BMP, TIFF, SVG, PSD, DNG, TGA, EXR, HDR, ICO]
|
||||
tools = [resize, crop, rotate, convert, compress, adjust-colors, sharpening, ...]
|
||||
for each tool x format: upload, process, verify output
|
||||
```
|
||||
|
||||
This catches format-specific bugs (like AVIF sidecar crashes). Use the `tests/fixtures/formats/` files.
|
||||
|
||||
### Agent 8: Edge Case and Adversarial Tests
|
||||
|
||||
Expand adversarial coverage:
|
||||
- **Concurrent:** Parallel uploads to same tool (10 simultaneous)
|
||||
- **Memory:** Upload 6.7MB stress-large.jpg repeatedly (50 times sequentially)
|
||||
- **Zero-byte files:** Empty file upload -> proper 400 error
|
||||
- **Corrupted headers:** Wrong magic bytes for declared format -> rejected by validation
|
||||
- **Wrong extension:** `.jpg` file containing PNG data -> handled gracefully
|
||||
- **Unicode filenames:** Emoji, CJK characters, RTL text, spaces, special chars
|
||||
- **Extreme dimensions:** Maximum size images, 1x1 pixel through every tool
|
||||
- **Pipeline edge cases:** Circular steps, conflicting operations, 21+ steps (over limit)
|
||||
- **Batch limits:** 50+ images in one batch -> handled or clear limit error
|
||||
- **Simultaneous:** Batch + single requests at the same time -> no corruption
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Verification
|
||||
|
||||
After all agents complete:
|
||||
|
||||
1. Run `pnpm test` -- all unit + integration tests must pass
|
||||
2. Run `pnpm lint` -- zero lint errors
|
||||
3. Run `pnpm typecheck` -- zero type errors
|
||||
4. Generate final coverage report and compare against Phase 0 baseline
|
||||
5. Document Docker commands needed for e2e-docker tests
|
||||
|
||||
---
|
||||
|
||||
## Bug Fix Protocol
|
||||
|
||||
When any test reveals a bug or warning:
|
||||
1. Document it clearly in the test expectation
|
||||
2. Fix the underlying code immediately
|
||||
3. Ensure the test passes with the fix
|
||||
4. Run surrounding tests to verify no regressions
|
||||
5. Do NOT skip or mark tests as `.todo`/`.skip` for real bugs
|
||||
Reference in New Issue
Block a user