85 lines
4.0 KiB
Markdown
85 lines
4.0 KiB
Markdown
# Tasks: enterprise-image
|
||
|
||
**Change ID**: enterprise-image
|
||
**Package**: `@suaveplan/image`
|
||
**Target path**: `universal/media/image`
|
||
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/mime`, `@suaveplan/crypto-utils`
|
||
|
||
---
|
||
|
||
## 0. Pre-flight (non-negotiable)
|
||
|
||
- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
||
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
||
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
||
|
||
## 1. Scaffold
|
||
|
||
- [ ] Create directory `universal/media/image/` with `src/`, `tests/`, `src/__benchmarks__/`, and all feature subdirectories per the layout in `proposal.md`.
|
||
- [ ] Write `package.json` at version `0.1.0` with `"type": "module"`, `"sideEffects": false`, full `exports` map, deps: `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `@suaveplan/mime workspace:^`, `@suaveplan/crypto-utils workspace:^`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`.
|
||
- [ ] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`.
|
||
- [ ] Write `vitest.config.ts` using `createTestConfig()` from `@suaveplan/testing/config`.
|
||
- [ ] Add `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check` scripts.
|
||
|
||
---
|
||
|
||
## 2. Types + errors
|
||
|
||
- [ ] Write `src/types/common.ts` — `ImageFormat`, `ColorSpace`, `ImageMetadata`, `ResizeOptions`, `CropOptions`, `ConvertOptions`, `ImageAdapter`, `ImageProcessorOptions` interfaces.
|
||
- [ ] Write `src/types/common.md`.
|
||
- [ ] Write `src/error-codes.ts` — `ImageErrorCode` union, `IMAGE_ERROR_METADATA`, `registerImageErrorCodes()`.
|
||
- [ ] Write Zod schemas: `ResizeOptionsSchema`, `CropOptionsSchema`, `ConvertOptionsSchema`, `ImageMetadataSchema`, `ImageProcessorOptionsSchema`.
|
||
|
||
---
|
||
|
||
## 3. MemoryImageAdapter
|
||
|
||
- [ ] Implement pure-JS pixel operations on raw RGBA `Uint8Array`: `readMetadata` (parse JPEG/PNG headers for width/height), `resize` (nearest-neighbour), `crop`, `rotate` (90/180/270), `flip`, `convert` (PNG↔JPEG re-encode via raw header swapping — or format passthrough with explicit limitation in docs).
|
||
- [ ] Write `memory-adapter.test.ts` (≤500 lines): each operation, round-trip, edge cases (1×1, wide, tall).
|
||
- [ ] Write `memory-adapter.md`.
|
||
|
||
---
|
||
|
||
## 4. ImageProcessor
|
||
|
||
- [ ] Implement `ImageProcessor` class delegating all operations to `adapter`; wire `AbortSignal` propagation.
|
||
- [ ] Implement OTel: span `image.process`, counter `image.operation_total`, histogram `image.duration_ms`.
|
||
- [ ] Write `image-processor.test.ts` (≤500 lines): each operation via MemoryImageAdapter, abort, invalid options throw.
|
||
- [ ] Write `image-processor.md`.
|
||
|
||
---
|
||
|
||
## 5. Utils
|
||
|
||
- [ ] Implement `src/utils/format-detect.ts` — delegates to `@suaveplan/mime`; maps MIME type to `ImageFormat`.
|
||
- [ ] Write `format-detect.test.ts` and `format-detect.md`.
|
||
|
||
---
|
||
|
||
## 6. Benchmarks
|
||
|
||
- [ ] Write `src/__benchmarks__/image.bench.ts` — `metadata` read, `resize` 1920×1080→640×360, `convert` PNG→WebP (null adapter for format-convert path).
|
||
|
||
---
|
||
|
||
## 7. Tests
|
||
|
||
- [ ] Write `tests/integration.test.ts` — full pipeline with MemoryImageAdapter.
|
||
- [ ] Write `tests/property.test.ts` (fast-check) — crop idempotency, resize monotonicity, flip involution.
|
||
|
||
---
|
||
|
||
## 8. Docs
|
||
|
||
- [ ] All co-located `.md` files (≥200 words each).
|
||
- [ ] Write `README.md` at package root.
|
||
|
||
---
|
||
|
||
## 9. Verify and publish
|
||
|
||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/image` — green.
|
||
- [ ] `bunx turbo test:coverage --filter=@suaveplan/image` — 100%.
|
||
- [ ] `bun scripts/publish.ts --package @suaveplan/image`.
|
||
- [ ] Archive to `openspec/archive/2026-04-24-enterprise-image/`.
|