SuavePlan/suaveplan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
suaveplan/openspec/changes/enterprise-api-plugin-file-upload/tasks.md
admin fbc70f96e6 Initial Commit
2026-05-27 23:29:53 +01:00

3.3 KiB
Raw Permalink Blame History

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/.
Reference in New Issue View Git Blame Copy Permalink