Initial Commit

openspec/changes/enterprise-api-plugin-file-upload/tasks.md

@@ -0,0 +1,62 @@
+# Tasks: enterprise-api-plugin-file-upload
+
+**Change ID**: enterprise-api-plugin-file-upload
+**Package**: `@suaveplan/api-plugin-file-upload`
+**Target path**: `api/data/api-plugin-file-upload`
+**Prerequisite packages on Verdaccio**: `@suaveplan/api`, `@suaveplan/api-shared`, `@suaveplan/api-plugin-auth`, `@suaveplan/api-plugin-database`, `@suaveplan/mime`, `@suaveplan/exif`, `@suaveplan/audio-metadata`, `@suaveplan/compress-image`, `@suaveplan/events`, `@suaveplan/rate-limiter`, `@suaveplan/error`
+
+---
+
+## 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 + types + errors + events
+
+- [ ] Create directory; `package.json` v0.0.0; standard tooling.
+- [ ] Types: `FileRecord`, `ChunkedUpload`, `FileStorageAdapter`, `FileUploadPluginConfig` (Zod). Allowed MIME types config.
+- [ ] Errors: 6-code union + registration. Test + doc.
+- [ ] Events: `FileUploadEventMap` (file:uploaded, file:quarantined, file:approved, file:deleted).
+
+---
+
+## 2. SurrealQL
+
+- [ ] `file_record.surql` (key, mimeType, size, status [pending|approved|quarantined|deleted], uploadedBy, tenantId, metadata jsonb), `chunked_upload.surql`.
+
+---
+
+## 3. Adapter port
+
+- [ ] `src/adapters/storage.port.ts` — `FileStorageAdapter` interface. Local-disk default implementation for dev. Test + doc.
+
+---
+
+## 4. Services
+
+- [ ] **UploadService**: `uploadSingle(stream, meta)` — MIME validation, size check, store via adapter, extract metadata. `initiateChunked`, `uploadPart`, `completeChunked`. Rate-limited. Test + doc.
+- [ ] **MetadataService**: dispatch to `@suaveplan/exif` for images, `@suaveplan/audio-metadata` for audio, no-op otherwise. Test + doc.
+- [ ] **LifecycleService**: `approveFile`, `quarantineFile`, `deleteFile`, `getFile`, `listFiles`, `getSignedDownloadUrl` (TTL). Test + doc.
+
+---
+
+## 5. Routes
+
+- [ ] `POST /files` — `requireAuth` + rate-limit; single upload.
+- [ ] `GET /files/:id` — `requireAuth`.
+- [ ] `GET /files/:id/download` — signed URL check or direct stream.
+- [ ] `DELETE /files/:id` — `requireAuth` + audit.
+- [ ] Chunked: initiate, upload part, complete — `requireAuth` + rate-limit.
+- [ ] Route `.test.ts` + `.md`.
+
+---
+
+## 6. Plugin factory + integration tests + publish
+
+- [ ] `createFileUploadPlugin(storageAdapter, config?)`: `definePlugin`, `dependencies: ["database", "auth"]`, `migrationsPath: "./surql"`.
+- [ ] Integration: upload file → extract metadata → download → delete (real SurrealDB + local storage adapter).
+- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/api-plugin-file-upload` — green; 100% coverage.
+- [ ] `bun scripts/publish.ts --package @suaveplan/api-plugin-file-upload`.
+- [ ] Archive → `openspec/archive/2026-04-24-enterprise-api-plugin-file-upload/`.