Initial Commit
This commit is contained in:
194
openspec/changes/enterprise-image/proposal.md
Normal file
194
openspec/changes/enterprise-image/proposal.md
Normal file
@@ -0,0 +1,194 @@
|
||||
# OpenSpec Change: enterprise-image
|
||||
|
||||
- **Change ID**: enterprise-image
|
||||
- **Package**: `@suaveplan/image`
|
||||
- **Category**: universal
|
||||
- **Target path**: `universal/media/image`
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/image.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/image` on the genesis branch from scratch at enterprise quality. The package provides image metadata extraction, format detection, and transformation operations: resize, crop, rotate, flip, format conversion, quality adjustment, and channel extraction. Pure TypeScript with no Node.js or browser hard deps — pixel manipulation operates on raw `Uint8Array` buffers. Pluggable codec adapters (e.g. sharp, native WebCodecs) via the `ImageAdapter` interface.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
The package does not exist on genesis yet — this is a fresh build. No prior source, no test results, no coverage data.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | Base class for `ImageError`; `defineCodes` for `IMAGE.*` codes |
|
||||
| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `Clock` |
|
||||
| `@suaveplan/mime` (`workspace:^`) | MIME/format detection for input buffers |
|
||||
| `@suaveplan/crypto-utils` (`workspace:^`) | Content-hash cache keys |
|
||||
| `zod` (`catalog:forms`) | Zod schemas for all public option types |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | Spans + counters on every operation |
|
||||
|
||||
Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata` (all `catalog:testing`).
|
||||
|
||||
---
|
||||
|
||||
## Public API
|
||||
|
||||
### Core types
|
||||
|
||||
```ts
|
||||
class ImageError extends SuaveplanError
|
||||
|
||||
type ImageFormat = 'jpeg' | 'png' | 'webp' | 'avif' | 'gif' | 'bmp' | 'tiff' | 'svg' | 'unknown'
|
||||
type ColorSpace = 'srgb' | 'p3' | 'cmyk' | 'grayscale'
|
||||
|
||||
interface ImageMetadata {
|
||||
width: number
|
||||
height: number
|
||||
format: ImageFormat
|
||||
colorSpace: ColorSpace
|
||||
hasAlpha: boolean
|
||||
byteSize: number
|
||||
mimeType: string
|
||||
}
|
||||
|
||||
interface ResizeOptions {
|
||||
width?: number
|
||||
height?: number
|
||||
fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside'
|
||||
position?: 'center' | 'top' | 'bottom' | 'left' | 'right'
|
||||
withoutEnlargement?: boolean
|
||||
}
|
||||
|
||||
interface CropOptions {
|
||||
left: number
|
||||
top: number
|
||||
width: number
|
||||
height: number
|
||||
}
|
||||
|
||||
interface ConvertOptions {
|
||||
format: ImageFormat
|
||||
quality?: number // 1–100
|
||||
lossless?: boolean
|
||||
}
|
||||
|
||||
interface ImageAdapter {
|
||||
readonly supportedFormats: readonly ImageFormat[]
|
||||
readMetadata(data: Uint8Array): Promise<ImageMetadata>
|
||||
resize(data: Uint8Array, options: ResizeOptions): Promise<Uint8Array>
|
||||
crop(data: Uint8Array, options: CropOptions): Promise<Uint8Array>
|
||||
rotate(data: Uint8Array, degrees: number): Promise<Uint8Array>
|
||||
flip(data: Uint8Array, axis: 'horizontal' | 'vertical'): Promise<Uint8Array>
|
||||
convert(data: Uint8Array, options: ConvertOptions): Promise<Uint8Array>
|
||||
}
|
||||
|
||||
interface ImageProcessorOptions {
|
||||
adapter: ImageAdapter
|
||||
logger?: LoggerLike
|
||||
clock?: Clock
|
||||
}
|
||||
|
||||
class ImageProcessor {
|
||||
constructor(options: ImageProcessorOptions)
|
||||
metadata(data: Uint8Array, signal?: AbortSignal): Promise<ImageMetadata>
|
||||
resize(data: Uint8Array, options: ResizeOptions, signal?: AbortSignal): Promise<Uint8Array>
|
||||
crop(data: Uint8Array, options: CropOptions, signal?: AbortSignal): Promise<Uint8Array>
|
||||
rotate(data: Uint8Array, degrees: number, signal?: AbortSignal): Promise<Uint8Array>
|
||||
flip(data: Uint8Array, axis: 'horizontal' | 'vertical', signal?: AbortSignal): Promise<Uint8Array>
|
||||
convert(data: Uint8Array, options: ConvertOptions, signal?: AbortSignal): Promise<Uint8Array>
|
||||
}
|
||||
|
||||
function createImageProcessor(options: ImageProcessorOptions): ImageProcessor
|
||||
```
|
||||
|
||||
### Error codes
|
||||
|
||||
```ts
|
||||
type ImageErrorCode =
|
||||
| 'IMAGE_UNSUPPORTED_FORMAT'
|
||||
| 'IMAGE_INVALID_DIMENSIONS'
|
||||
| 'IMAGE_DECODE_FAILED'
|
||||
| 'IMAGE_ENCODE_FAILED'
|
||||
| 'IMAGE_OPERATION_FAILED'
|
||||
| 'IMAGE_INVALID_OPTIONS'
|
||||
|
||||
const IMAGE_ERROR_METADATA: Readonly<Record<ImageErrorCode, CodeMetadata>>
|
||||
function registerImageErrorCodes(): void
|
||||
```
|
||||
|
||||
### Zod schemas
|
||||
|
||||
```ts
|
||||
ResizeOptionsSchema
|
||||
CropOptionsSchema
|
||||
ConvertOptionsSchema
|
||||
ImageMetadataSchema
|
||||
ImageProcessorOptionsSchema
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## New additions for genesis
|
||||
|
||||
1. **`ImageAdapter` interface** — all codec-specific work delegated; `ImageProcessor` is codec-agnostic.
|
||||
2. **`MemoryImageAdapter`** — pure-JS pixel operations (resize nearest-neighbour, crop, flip, rotate 90/180/270) operating on raw RGBA `Uint8Array`. No external deps. Used in tests and as a fallback.
|
||||
3. **Format detection** — delegates to `@suaveplan/mime` for initial MIME sniff; headers re-verified inside `readMetadata`.
|
||||
4. **`AbortSignal` propagation** — every async method passes signal through; aborted operations throw `ImageError(IMAGE_OPERATION_FAILED)`.
|
||||
5. **OTel instrumentation** — span `image.process`, counter `image.operation_total` (attr `image.operation`), histogram `image.duration_ms`, attributes `image.format`, `image.width`, `image.height`.
|
||||
6. **Property-based tests** — crop idempotency (crop same region twice = same result), resize monotonicity (larger target → larger output), flip involution (flip twice = original).
|
||||
7. **Benchmark suite** — `metadata` read, `resize` 1920×1080→640×360, `convert` PNG→WebP.
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
universal/media/image/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
error-codes.ts
|
||||
constants/
|
||||
index.ts
|
||||
types/
|
||||
common.ts
|
||||
common.md
|
||||
core/
|
||||
image-processor/
|
||||
image-processor.ts
|
||||
image-processor.md
|
||||
image-processor.types.ts
|
||||
image-processor.test.ts
|
||||
index.ts
|
||||
adapters/
|
||||
memory-adapter/
|
||||
memory-adapter.ts
|
||||
memory-adapter.md
|
||||
memory-adapter.test.ts
|
||||
index.ts
|
||||
utils/
|
||||
format-detect.ts
|
||||
format-detect.md
|
||||
format-detect.test.ts
|
||||
__benchmarks__/
|
||||
image.bench.ts
|
||||
tests/
|
||||
integration.test.ts
|
||||
property.test.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
**Downstream**: `@suaveplan/media` facade, `@suaveplan/compress-image`, `@suaveplan/image-quantisation`.
|
||||
**Breaking changes**: none — fresh build.
|
||||
**Prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/mime`, `@suaveplan/crypto-utils` published to Verdaccio.
|
||||
84
openspec/changes/enterprise-image/tasks.md
Normal file
84
openspec/changes/enterprise-image/tasks.md
Normal file
@@ -0,0 +1,84 @@
|
||||
# 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/`.
|
||||
Reference in New Issue
Block a user