@bhooai/nexus-core 2.0.13 → 2.0.16

package/src/app/Storage.ts

@@ -5,14 +5,30 @@
  *
  *   await storage.disk('uploads').put('avatars', file);
  *   const url = await storage.disk('private').signedUrl('invoices/1.pdf', { ttl: 300 });
+ *
+ * Image variants: when `StorageConfig.imageTransform.enabled` and the file is
+ * an image (jpeg/png/webp/avif), `put()` auto-calls the Python image service
+ * (Pillow + optional Real-ESRGAN) at `NEXUS_IMAGES_URL` to generate variants
+ * per `imageTransform.sizes` (e.g. thumb:150, small:480) in `imageTransform.formats`.
+ * No native Node dependency (sharp removed).
  */
 import { createHash, createHmac, randomUUID } from 'node:crypto';
-import { mkdir, readFile, stat as fsStat, unlink, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, stat as fsStat, unlink, writeFile, symlink, link, lstat } from 'node:fs/promises';
 import { createReadStream } from 'node:fs';
-import { dirname, extname, join, resolve } from 'node:path';
+import { dirname, extname, join, resolve, relative } from 'node:path';
 import { existsSync } from 'node:fs';
 import type { Readable } from 'node:stream';
 
+export interface ImageVariant {
+  path: string;
+  url: string;
+  width: number;
+  height: number;
+  format: string;
+  size: number;
+  sha256: string;
+}
+
 export interface StoredFile {
   id: string;
   path: string;
@@ -22,6 +38,7 @@ export interface StoredFile {
   mime: string;
   originalName: string;
   sha256: string;
+  variants?: Record<string, ImageVariant>;
 }
 
 export interface SignedUrlOptions {
@@ -66,9 +83,283 @@ export interface StorageConfig {
     formats: string[];
     sizes: Record<string, number>;
     stripMetadata?: boolean;
+    quality?: number;
+    fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+    upscale?: {
+      enabled?: boolean;
+      algorithm?: 'realesrgan' | 'lanczos';
+    };
+    /** Override Python image service URL; defaults to NEXUS_IMAGES_URL env or http://localhost:8000 */
+    imagesUrl?: string;
   };
 }
 
+// ---------------------------------------------------------------------------
+// Image helpers — call Python image service to generate variants
+// ---------------------------------------------------------------------------
+
+const IMAGE_MIMES = new Set([
+  'image/jpeg',
+  'image/jpg',
+  'image/png',
+  'image/webp',
+  'image/avif',
+  'image/gif',
+  'image/bmp',
+]);
+
+function isImageMime(mime: string | undefined): boolean {
+  if (!mime) return false;
+  if (IMAGE_MIMES.has(mime.toLowerCase())) return true;
+  return mime.toLowerCase().startsWith('image/');
+}
+
+function imagesBaseUrl(cfg: StorageConfig | null): string | null {
+  const fromCfg = cfg?.imageTransform?.imagesUrl;
+  if (fromCfg) return fromCfg.replace(/\/+$/, '');
+  const pyPortUrl = process.env.PY_PORT ? `http://127.0.0.1:${process.env.PY_PORT}` : '';
+  const fromEnv = process.env.NEXUS_IMAGES_URL || pyPortUrl || process.env.AI_SERVER_URL || '';
+  if (fromEnv) return fromEnv.replace(/\/+$/, '');
+  // Try pyserver (8001) first, then ai-server (8000) — image service is at pyserver (bhooai_nexus)
+  try {
+    const ports = (globalThis as any).__nexus_ports ?? null;
+    if (ports?.pyserver) return `http://127.0.0.1:${ports.pyserver}`;
+  } catch {}
+  return 'http://127.0.0.1:8001';
+}
+
+async function generateImageVariants(
+  buffer: Buffer,
+  cfg: StorageConfig | null,
+): Promise<Record<string, ImageVariant> | undefined> {
+  const tf = cfg?.imageTransform;
+  if (!tf?.enabled || !tf.sizes || Object.keys(tf.sizes).length === 0) return undefined;
+  const baseUrl = imagesBaseUrl(cfg);
+  if (!baseUrl) return undefined;
+  const formats = tf.formats?.length ? tf.formats : ['webp'];
+  const quality = tf.quality ?? 80;
+  const fit = tf.fit ?? 'inside';
+  const algorithm = tf.upscale?.algorithm ?? 'realesrgan';
+  const stripMetadata = tf.stripMetadata ?? true;
+
+  const b64 = buffer.toString('base64');
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 15_000);
+  try {
+    const doFetch = (url: string) =>
+      fetch(`${url}/images/variants/json`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          b64,
+          sizes: tf.sizes,
+          formats,
+          quality,
+          fit,
+          algorithm,
+          strip_metadata: stripMetadata,
+        }),
+        signal: controller.signal,
+      } as any);
+    let res = await doFetch(baseUrl);
+    // Fallback to alternate port (pyserver 8001 vs ai-server 8000)
+    if (res.status === 404) {
+      const alt = baseUrl.includes(':8001') ? baseUrl.replace(':8001', ':8000') : baseUrl.replace(':8000', ':8001');
+      if (alt !== baseUrl) {
+        const altRes = await doFetch(alt);
+        if (altRes.ok || altRes.status !== 404) res = altRes;
+      }
+    }
+    if (!res.ok) {
+      const txt = await res.text().catch(() => '');
+      console.warn(`[storage] image variants failed: ${res.status} ${txt.slice(0, 300)}`);
+      return undefined;
+    }
+    const json = (await res.json()) as { variants: Record<string, { b64: string; width: number; height: number; format: string; size: number; sha256: string }> };
+    // Return b64 variants for caller to persist; caller maps to paths/urls
+    // We keep b64 here — LocalDisk/S3Disk will write files and strip b64.
+    // To avoid double-encoding, return as-is with b64 included.
+    const out: Record<string, ImageVariant & { b64: string }> = {} as any;
+    for (const [k, v] of Object.entries(json.variants ?? {})) {
+      (out as any)[k] = v;
+    }
+    return out as any;
+  } catch (e: any) {
+    if (e?.name === 'AbortError') console.warn('[storage] image variants timed out (15s) — skipping');
+    else console.warn(`[storage] image variants error — skipping: ${e?.message ?? e}`);
+    return undefined;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function persistVariants(
+  variants: Record<string, { b64: string; width: number; height: number; format: string; size: number; sha256: string }>,
+  dir: string,
+  id: string,
+  shard: string,
+  cfg: DiskConfig,
+  resolveRoot: () => string,
+  baseUrlForPath: (rel: string) => string,
+): Promise<Record<string, ImageVariant>> {
+  const out: Record<string, ImageVariant> = {};
+  for (const [name, v] of Object.entries(variants)) {
+    const ext = v.format === 'jpeg' ? 'jpg' : v.format;
+    const rel = join(dir, shard, 'variants', name, `${id}.${ext}`).replace(/\\/g, '/');
+    const abs = join(resolveRoot(), rel);
+    await mkdir(dirname(abs), { recursive: true });
+    const buf = Buffer.from(v.b64, 'base64');
+    await writeFile(abs, buf);
+    out[name] = {
+      path: rel,
+      url: baseUrlForPath(rel),
+      width: v.width,
+      height: v.height,
+      format: v.format,
+      size: buf.length,
+      sha256: v.sha256,
+    };
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// DB dedup helpers — single entry per sha256, multiple placements, symlink reuse
+// ---------------------------------------------------------------------------
+
+function getUploadModelSafe(): any {
+  try {
+    // Lazy to avoid circular at import time; Upload.ts imports from nexus-data which is already a dep
+    // Use dynamic require via eval to keep ESM happy
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const mod = (globalThis as any).__nexus_upload_model;
+    if (mod) return mod;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+async function findUploadBySha256(sha256: string): Promise<any | null> {
+  try {
+    const { getUploadModel } = await import('./Upload.js');
+    const M = getUploadModel();
+    if (!M) return null;
+    const doc = await M.findOne({ sha256 }).exec();
+    return doc ?? null;
+  } catch {
+    return null;
+  }
+}
+
+async function upsertUploadPlacement(doc: any | null, sha256: string, placement: any, canonical: any, variants: Record<string, ImageVariant> | undefined, meta: { originalName: string; mime: string; size: number; width?: number; height?: number }): Promise<any> {
+  try {
+    const { getUploadModel } = await import('./Upload.js');
+    const M = getUploadModel();
+    if (!M) return null;
+    if (doc) {
+      // Existing sha256 — push new placement if not already present (by path)
+      const exists = (doc.placements ?? []).some((p: any) => p.path === placement.path);
+      if (!exists) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const updated = await M.findOneAndUpdate(
+          { sha256 },
+          { $push: { placements: placement }, $set: { updatedAt: new Date(), ...(variants ? { variants } : {}) } } as any,
+          { returnDocument: 'after' } as any,
+        ).exec();
+        return updated ?? doc;
+      }
+      return doc;
+    }
+    const toCreate: any = {
+      sha256,
+      originalName: meta.originalName,
+      mime: meta.mime,
+      size: meta.size,
+      ...(meta.width ? { width: meta.width } : {}),
+      ...(meta.height ? { height: meta.height } : {}),
+      canonical,
+      placements: [placement],
+      ...(variants ? { variants } : {}),
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+    const created = await M.create(toCreate);
+    return created[0] ?? toCreate;
+  } catch (e) {
+    // Duplicate key race — fetch existing
+    try {
+      const { getUploadModel } = await import('./Upload.js');
+      const M = getUploadModel();
+      if (!M) return null;
+      return await M.findOne({ sha256 }).exec();
+    } catch {
+      return doc;
+    }
+  }
+}
+
+async function ensureSymlink(targetAbs: string, linkAbs: string): Promise<boolean> {
+  try {
+    await mkdir(dirname(linkAbs), { recursive: true });
+    // Remove existing file/link if any
+    try {
+      await unlink(linkAbs);
+    } catch {}
+    const relTarget = relative(dirname(linkAbs), targetAbs);
+    // Windows needs type 'file' and often admin; try symlink then hardlink then copy
+    try {
+      await symlink(relTarget, linkAbs, 'file');
+      return true;
+    } catch (e: any) {
+      // Fallback to hardlink
+      try {
+        await link(targetAbs, linkAbs);
+        return true;
+      } catch {
+        // Last fallback: copy
+        const buf = await readFile(targetAbs);
+        await writeFile(linkAbs, buf);
+        return false;
+      }
+    }
+  } catch {
+    return false;
+  }
+}
+
+async function removePlacementByPath(path: string): Promise<boolean> {
+  try {
+    const { getUploadModel } = await import('./Upload.js');
+    const M = getUploadModel();
+    if (!M) return false;
+    const doc = await M.findOne({ $or: [{ 'canonical.path': path }, { 'placements.path': path }] }).exec();
+    if (!doc) return false;
+    const placements: any[] = (doc as any).placements ?? [];
+    const remaining = placements.filter((p: any) => p.path !== path);
+    if (remaining.length === 0) {
+      // Last placement — delete canonical file + variants physically, then doc
+      await M.deleteOne({ sha256: (doc as any).sha256 }).exec();
+      return true; // caller should delete physical canonical
+    }
+    await M.updateOne({ sha256: (doc as any).sha256 }, { $set: { placements: remaining, updatedAt: new Date() } } as any).exec();
+    return false; // not last — keep canonical
+  } catch {
+    return false;
+  }
+}
+
+async function findPlacementDocByPath(path: string): Promise<any | null> {
+  try {
+    const { getUploadModel } = await import('./Upload.js');
+    const M = getUploadModel();
+    if (!M) return null;
+    return await M.findOne({ $or: [{ 'canonical.path': path }, { 'placements.path': path }] }).exec();
+  } catch {
+    return null;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Local driver
 // ---------------------------------------------------------------------------
@@ -93,6 +384,89 @@ class LocalDisk implements Disk {
     const meta = sourceAsMeta(source);
     const originalName = meta.originalName ?? 'file';
     const ext = extname(originalName) || '';
+    const sha256 = createHash('sha256').update(buffer).digest('hex');
+    const mime = meta.mime ?? 'application/octet-stream';
+
+    // Try DB dedup — single entry per sha256
+    let existing: any = null;
+    try {
+      existing = await findUploadBySha256(sha256);
+    } catch {}
+    const isDedupHit = !!existing && existing.canonical?.disk === this.name;
+
+    if (isDedupHit) {
+      // Existing content — create symlink for new placement (separate directory, same content)
+      const date = new Date();
+      const shard = `${date.getUTCFullYear()}/${String(date.getUTCMonth() + 1).padStart(2, '0')}`;
+      const newId = randomUUID();
+      const newRel = join(dir, shard, `${newId}${ext}`).replace(/\\/g, '/');
+      const newAbs = this.abs(newRel);
+      const canonicalAbs = join(this.resolveRoot(), existing.canonical.path);
+      // If canonical file missing (e.g. storage cleared), fallback to normal write
+      let canLink = false;
+      try {
+        await fsStat(canonicalAbs);
+        canLink = true;
+      } catch {
+        canLink = false;
+      }
+      if (canLink) {
+        await ensureSymlink(canonicalAbs, newAbs);
+        // Symlink variants if any
+        let newVariants: Record<string, ImageVariant> | undefined;
+        if (existing.variants && Object.keys(existing.variants).length > 0) {
+          newVariants = {};
+          for (const [name, v] of Object.entries(existing.variants as Record<string, any>)) {
+            const vExt = (v as any).format === 'jpeg' ? 'jpg' : (v as any).format;
+            const vRel = join(dir, shard, 'variants', name, `${newId}.${vExt}`).replace(/\\/g, '/');
+            const vAbs = this.abs(vRel);
+            const canonicalVRel = (v as any).path as string;
+            const canonicalVAbs = join(this.resolveRoot(), canonicalVRel);
+            try {
+              await fsStat(canonicalVAbs);
+              await ensureSymlink(canonicalVAbs, vAbs);
+              newVariants[name] = {
+                path: vRel,
+                url: this.url(vRel),
+                width: (v as any).width,
+                height: (v as any).height,
+                format: (v as any).format,
+                size: (v as any).size,
+                sha256: (v as any).sha256,
+              };
+            } catch {
+              // ignore variant link failure
+            }
+          }
+        }
+        // Record new placement in DB
+        const placement = {
+          id: newId,
+          disk: this.name,
+          path: newRel,
+          url: this.url(newRel),
+          dir,
+          createdAt: new Date(),
+        };
+        try {
+          await upsertUploadPlacement(existing, sha256, placement, existing.canonical, undefined, { originalName, mime, size: buffer.length });
+        } catch {}
+        return {
+          id: sha256, // single entry id is sha256
+          path: newRel,
+          url: this.url(newRel),
+          disk: this.name,
+          size: buffer.length,
+          mime,
+          originalName,
+          sha256,
+          ...(newVariants && Object.keys(newVariants).length ? { variants: newVariants } : existing.variants ? { variants: existing.variants } : {}),
+        };
+      }
+      // Fall through to normal write if canonical missing
+    }
+
+    // Miss or canLink false — normal write
     const id = randomUUID();
     const date = new Date();
     const shard = `${date.getUTCFullYear()}/${String(date.getUTCMonth() + 1).padStart(2, '0')}`;
@@ -102,16 +476,60 @@ class LocalDisk implements Disk {
     await mkdir(dirname(abs), { recursive: true });
     await writeFile(abs, buffer);
 
-    const sha256 = createHash('sha256').update(buffer).digest('hex');
-    return {
+    let variants: Record<string, ImageVariant> | undefined;
+    // Auto-generate image variants via Python (Pillow+Real-ESRGAN) — best-effort, never fails upload
+    if (isImageMime(mime) && (globalThis as any).__nexus_storage_cfg?.imageTransform?.enabled) {
+      const raw = await generateImageVariants(buffer, (globalThis as any).__nexus_storage_cfg as StorageConfig);
+      if (raw) {
+        try {
+          variants = await persistVariants(
+            raw as any,
+            dir,
+            id,
+            shard,
+            this.cfg,
+            () => this.resolveRoot(),
+            (p) => this.url(p),
+          );
+        } catch (e) {
+          console.warn(`[storage] persist variants failed: ${(e as Error).message}`);
+        }
+      }
+    }
+
+    // Create/Update DB entry (single doc per sha256)
+    let width: number | undefined;
+    let height: number | undefined;
+    if (isImageMime(mime) && variants) {
+      const first = Object.values(variants)[0] as any;
+      if (first) {
+        width = first.width;
+        height = first.height;
+      }
+    }
+    const canonical = { disk: this.name, path: rel, url: this.url(rel) };
+    const placement = {
       id,
+      disk: this.name,
+      path: rel,
+      url: this.url(rel),
+      dir,
+      createdAt: new Date(),
+    };
+    try {
+      await upsertUploadPlacement(existing, sha256, placement, canonical, variants, { originalName, mime, size: buffer.length, width, height });
+    } catch {}
+
+    return {
+      id: sha256,
       path: rel,
       url: this.url(rel),
       disk: this.name,
       size: buffer.length,
-      mime: meta.mime ?? 'application/octet-stream',
+      mime,
       originalName,
       sha256,
+      ...(variants ? { variants } : {}),
     };
   }
 
@@ -124,11 +542,58 @@ class LocalDisk implements Disk {
   }
 
   async delete(path: string): Promise<void> {
+    // DB-aware delete: remove placement, keep canonical if other placements remain
+    try {
+      const doc: any = await findPlacementDocByPath(path);
+      if (doc) {
+        const isCanonical = doc.canonical?.path === path;
+        const placements: any[] = doc.placements ?? [];
+        const remaining = placements.filter((p: any) => p.path !== path);
+        if (isCanonical && remaining.length > 0) {
+          // Don't delete canonical physical file while other placements reference it; just drop placement entry
+          try {
+            const { getUploadModel } = await import('./Upload.js');
+            const M = getUploadModel();
+            if (M) await M.updateOne({ sha256: doc.sha256 }, { $pull: { placements: { path } } as any, $set: { updatedAt: new Date() } }).exec();
+          } catch {}
+          return;
+        }
+        // For non-canonical or last placement, unlink the requested path
+        try {
+          await unlink(this.abs(path));
+        } catch {}
+        // Also unlink its variant symlinks if any (per-placement variants)
+        if (doc.variants) {
+          for (const v of Object.values(doc.variants as Record<string, any>)) {
+            // Variants are stored per placement? For dedup, variants are canonical-level, not per-placement separate
+            // We keep canonical variants until last placement deleted, so don't delete per-placement variant here
+          }
+        }
+        const shouldDeleteCanonical = await removePlacementByPath(path);
+        if (shouldDeleteCanonical) {
+          // Last placement — also delete canonical file + variants physically
+          try {
+            await unlink(this.abs(doc.canonical.path));
+          } catch {}
+          if (doc.variants) {
+            for (const v of Object.values(doc.variants as Record<string, any>)) {
+              try {
+                await unlink(this.abs((v as any).path));
+              } catch {}
+            }
+          }
+        }
+        return;
+      }
+    } catch {}
     try {
       await unlink(this.abs(path));
     } catch {
       /* swallow — deletes are idempotent */
     }
+    try {
+      await removePlacementByPath(path);
+    } catch {}
   }
 
   async exists(path: string): Promise<boolean> {
@@ -190,6 +655,38 @@ class S3Disk implements Disk {
     const meta = sourceAsMeta(source);
     const originalName = meta.originalName ?? 'file';
     const ext = extname(originalName) || '';
+    const sha256 = createHash('sha256').update(buffer).digest('hex');
+    const mime = meta.mime ?? 'application/octet-stream';
+
+    // DB dedup for S3 — single entry per sha256, no duplicate upload
+    let existing: any = null;
+    try {
+      existing = await findUploadBySha256(sha256);
+    } catch {}
+    if (existing && existing.canonical?.disk === this.name) {
+      const date = new Date();
+      const shard = `${date.getUTCFullYear()}/${String(date.getUTCMonth() + 1).padStart(2, '0')}`;
+      const newId = randomUUID();
+      const newRel = `${dir}/${shard}/${newId}${ext}`;
+      // For S3 dedup, don't duplicate object — just add placement pointing to canonical
+      const placement = { id: newId, disk: this.name, path: newRel, url: this.url(newRel), dir, createdAt: new Date() };
+      // Note: we keep logical newRel but reuse canonical variants
+      try {
+        await upsertUploadPlacement(existing, sha256, placement, existing.canonical, existing.variants as any, { originalName, mime, size: buffer.length });
+      } catch {}
+      return {
+        id: sha256,
+        path: newRel,
+        url: this.url(newRel),
+        disk: this.name,
+        size: buffer.length,
+        mime,
+        originalName,
+        sha256,
+        ...(existing.variants ? { variants: existing.variants } : {}),
+      };
+    }
+
     const id = randomUUID();
     const date = new Date();
     const shard = `${date.getUTCFullYear()}/${String(date.getUTCMonth() + 1).padStart(2, '0')}`;
@@ -200,16 +697,58 @@ class S3Disk implements Disk {
       Body: buffer,
       ContentType: meta.mime ?? 'application/octet-stream',
     }));
-    const sha256 = createHash('sha256').update(buffer).digest('hex');
+    let variants: Record<string, ImageVariant> | undefined;
+    if (isImageMime(mime) && (globalThis as any).__nexus_storage_cfg?.imageTransform?.enabled) {
+      const raw = await generateImageVariants(buffer, (globalThis as any).__nexus_storage_cfg as StorageConfig);
+      if (raw) {
+        try {
+          // Persist variants to S3 as well
+          const out: Record<string, ImageVariant> = {};
+          for (const [name, v] of Object.entries(raw as any)) {
+            const vv = v as { b64: string; width: number; height: number; format: string; size: number; sha256: string };
+            const vext = vv.format === 'jpeg' ? 'jpg' : vv.format;
+            const vrel = `${dir}/${shard}/variants/${name}/${id}.${vext}`;
+            const vbuf = Buffer.from(vv.b64, 'base64');
+            await this.client.send(new PutObjectCommand({
+              Bucket: this.cfg.bucket,
+              Key: vrel,
+              Body: vbuf,
+              ContentType: `image/${vext === 'jpg' ? 'jpeg' : vext}`,
+            }));
+            out[name] = {
+              path: vrel,
+              url: this.url(vrel),
+              width: vv.width,
+              height: vv.height,
+              format: vv.format,
+              size: vbuf.length,
+              sha256: vv.sha256,
+            };
+          }
+          variants = out;
+        } catch (e) {
+          console.warn(`[storage] S3 persist variants failed: ${(e as Error).message}`);
+        }
+      }
+    }
+    // Upsert DB
+    {
+      const canonical = { disk: this.name, path: rel, url: this.url(rel) };
+      const placement = { id, disk: this.name, path: rel, url: this.url(rel), dir, createdAt: new Date() };
+      try {
+        await upsertUploadPlacement(existing, sha256, placement, canonical, variants, { originalName, mime, size: buffer.length });
+      } catch {}
+    }
     return {
-      id,
+      id: sha256,
       path: rel,
       url: this.url(rel),
       disk: this.name,
       size: buffer.length,
-      mime: meta.mime ?? 'application/octet-stream',
+      mime,
       originalName,
       sha256,
+      ...(variants ? { variants } : {}),
     };
   }
 
@@ -229,7 +768,45 @@ class S3Disk implements Disk {
   async delete(path: string): Promise<void> {
     await this.ensure();
     const { DeleteObjectCommand } = (await import('@aws-sdk/client-s3' as string)) as any;
-    await this.client.send(new DeleteObjectCommand({ Bucket: this.cfg.bucket, Key: path }));
+    // DB-aware: only delete physical object if last placement
+    try {
+      const doc: any = await findPlacementDocByPath(path);
+      if (doc) {
+        const isCanonical = doc.canonical?.path === path;
+        const placements: any[] = doc.placements ?? [];
+        const remaining = placements.filter((p: any) => p.path !== path);
+        if (isCanonical && remaining.length > 0) {
+          try {
+            const { getUploadModel } = await import('./Upload.js');
+            const M = getUploadModel();
+            if (M) await M.updateOne({ sha256: doc.sha256 }, { $pull: { placements: { path } } as any, $set: { updatedAt: new Date() } }).exec();
+          } catch {}
+          return;
+        }
+        // Not canonical or last — proceed to delete S3 object, then update DB
+        await this.client.send(new DeleteObjectCommand({ Bucket: this.cfg.bucket, Key: path }));
+        const shouldDeleteCanonical = await removePlacementByPath(path);
+        if (shouldDeleteCanonical) {
+          try {
+            await this.client.send(new DeleteObjectCommand({ Bucket: this.cfg.bucket, Key: doc.canonical.path }));
+          } catch {}
+          if (doc.variants) {
+            for (const v of Object.values(doc.variants as Record<string, any>)) {
+              try {
+                await this.client.send(new DeleteObjectCommand({ Bucket: this.cfg.bucket, Key: (v as any).path }));
+              } catch {}
+            }
+          }
+        }
+        return;
+      }
+    } catch {}
+    try {
+      await this.client.send(new DeleteObjectCommand({ Bucket: this.cfg.bucket, Key: path }));
+    } catch {}
+    try {
+      await removePlacementByPath(path);
+    } catch {}
   }
 
   async exists(path: string): Promise<boolean> {
@@ -299,6 +876,8 @@ class StorageFacade {
   configure(cfg: StorageConfig, signingSecret: string): void {
     this.cfg = cfg;
     this.signingSecret = signingSecret || cfg.signingSecret || 'nexus-insecure';
+    // Expose for variant generation in drivers (LocalDisk/S3Disk)
+    (globalThis as any).__nexus_storage_cfg = cfg;
     for (const [name, diskCfg] of Object.entries(cfg.disks ?? {})) {
       if (diskCfg.driver === 'local') {
         this.disks.set(name, new LocalDisk(name, diskCfg, this.signingSecret));
@@ -308,6 +887,8 @@ class StorageFacade {
     }
   }
 
+  getConfig(): StorageConfig | null { return this.cfg; }
+
   disk(name?: string): Disk {
     const key = name ?? this.cfg?.default ?? Object.keys(this.cfg?.disks ?? {})[0];
     if (!key) throw new Error('Storage has no disks configured');
@@ -326,6 +907,19 @@ export const storage = new StorageFacade();
 
 /** Auto-configure from env — used by createNexusApp() boot. */
 export function configureStorageFromEnv(root: string, signingSecret: string): void {
+  // Allow disabling or tuning image variants via env
+  const imageTransformEnabled = (process.env.NEXUS_IMAGE_TRANSFORM_ENABLED ?? 'true') !== 'false';
+  const imageSizesEnv = process.env.NEXUS_IMAGE_SIZES; // e.g. "thumb:150,small:480,medium:1280,large:2048"
+  const imagesUrlEnv = process.env.NEXUS_IMAGES_URL || process.env.AI_SERVER_URL || undefined;
+  const imageQualEnv = process.env.NEXUS_IMAGE_QUALITY ? parseInt(process.env.NEXUS_IMAGE_QUALITY, 10) : 80;
+  let parsedSizes: Record<string, number> | undefined;
+  if (imageSizesEnv) {
+    parsedSizes = {};
+    for (const part of imageSizesEnv.split(',')) {
+      const [k, v] = part.split(':').map(s => s.trim());
+      if (k && v) parsedSizes[k] = parseInt(v, 10);
+    }
+  }
   const cfg: StorageConfig = {
     default: 'uploads',
     disks: {
@@ -351,6 +945,19 @@ export function configureStorageFromEnv(root: string, signingSecret: string): vo
         : {}),
     },
     signingSecret,
+    imageTransform: {
+      enabled: imageTransformEnabled,
+      formats: (process.env.NEXUS_IMAGE_FORMATS ?? 'webp').split(',').map(s => s.trim().toLowerCase()).filter(Boolean),
+      sizes: parsedSizes ?? { thumb: 150, small: 480, medium: 1280, large: 2048 },
+      stripMetadata: (process.env.NEXUS_IMAGE_STRIP_METADATA ?? 'true') !== 'false',
+      quality: imageQualEnv,
+      fit: (process.env.NEXUS_IMAGE_FIT as any) || 'inside',
+      upscale: {
+        enabled: (process.env.NEXUS_IMAGE_UPSCALE_ENABLED ?? 'true') !== 'false',
+        algorithm: (process.env.NEXUS_IMAGE_UPSCALE_ALGO as any) || 'realesrgan',
+      },
+      ...(imagesUrlEnv ? { imagesUrl: imagesUrlEnv } : {}),
+    },
   };
   storage.configure(cfg, signingSecret);