directus-extension-generate-image-previews/AGENTS.md

Agent notes — directus-extension-generate-image-previews

Common confusion points for agents working here. Read before touching the warmer.

What this is

A Directus bundle extension that pre-generates image transform ("preview") cache files so the admin UI never pays the first-request sharp cost. Target server: Directus 11.17.4 on land-nest (self-hosted, PM2 cluster, STORAGE_LOCAL_ROOT=./uploads).

Bundle entries: an api hook (files.upload), an api endpoint (/image-previews/*), and an app module (image-previews admin page: progress, disk usage, config).

Directus transform invariants (source-verified, tag v11.17.4) — DO NOT REGRESS

1. Cached transform filename = <basename(filename_disk)>__<object-hash(resolved transforms)>.<ext>, written beside the original in the storage root (./uploads, no .cache subdir).

2. Hash = object-hash@3 defaults: sha1/hex, unorderedArrays:false (array order matters), unorderedObjects:true. Hashes the RESOLVED transform array from resolvePreset, NOT the raw query/preset object.

3. resolvePreset order is fixed: copy transformationParams.transforms[] → push toFormat (if format/quality) → push resize (+extract on focal cover). Raw params ?width=&height=&fit=&format= resolve to [toFormat, resize]; a preset resolves to [resize, toFormat] → different hash for a visually identical result.

4. { key } alone is a NO-OP. resolvePreset never reads key. Always pass the full preset object.

5. format:'auto' is the killer trap. All six system-* presets are format:'auto'. getFormat with no acceptFormat → JPEG→jpg, PNG→png; a browser Accept: image/avif → avif. Different toFormat arg → different hash → guaranteed miss.

6. The write IS awaited. Not draining the returned stream leaks an FD but never truncates. Still: destroy/unpipe the returned stream to avoid FD leaks.

7. AssetsService.getAsset runs fine as sudo (new AssetsService({ schema })) with no HTTP request context — this is the basis of our in-process strategy.

Preset registry semantics (controller parity)

The controller builds, inline in api/src/controllers/assets.ts:

res.locals['shortcuts'] = [...SYSTEM_ASSET_ALLOW_LIST, ...(directus_settings.storage_asset_presets ?? [])]

and resolves ?key= with .find(t => t.key === key) → first match wins (a system key shadows a custom preset of the same key). There is no reusable helper, and GET /settings exposes only custom presets. Our registry (src/lib/presets.ts) must mirror this order exactly.

What the admin actually requests (verbatim from app source)

Surface	URL
Files grid	?key=system-medium-cover&v=<modified_on> (cards, crop)
Image field	?key=system-large-cover / system-large-contain
Image display	?key=system-small-cover

No explicit width/height/format. format:auto is implicit. v= is ignored for hashing.

Chosen strategy — IN-PROCESS (no token, no HTTP, no rate limiter)

const assets = new services.AssetsService({ schema });          // sudo
const { stream } = await assets.getAsset(fileId, {
  transformationParams: presetObject,                          // FULL object, not { key }
  acceptFormat: 'avif',                                        // or 'webp'
});
(stream as Readable).destroy?.();

acceptFormat reproduces what a browser's Accept header does → byte-identical cache filename with no HTTP/token. Warm both avif and webp for format:'auto' presets.

HTTP-replay (GET /assets/{id}?key=…) is the documented fallback only (needs a token + rate-limit pacing).

Config + state

• Persisted settings + progress state are small JSON files under <STORAGE_LOCAL_ROOT>/.image-previews (default /directus/uploads/.image-previews; override IMAGE_PREVIEWS_STATE_DIR). Do NOT default to /directus/extensions/... — that path is a root-owned volume and the API runs as node → EACCES.
• state.jsonl = append-only completed {file_id,preset_key,format} → resume.
• All state is file-backed (PM2 cluster, 8 workers — never in-memory).

Gotchas learned the hard way

• Directus coerces env values: "true" arrives as boolean true, "1" as number. Env parsing must accept unknown and stringify (see asString in settings.ts). A string-only .toLowerCase() call silently killed the upload hook.
• Docker bind mounts: never rm -rf the bind-mounted extension directory — it breaks the mount and Directus removes the extension without re-adding it. Sync contents in place; restart the dev container.
• The dev stack (dev/compose.dev.yml) is the only place to test; never load this into prod while iterating (prod has EXTENSIONS_AUTO_RELOAD=true).

Server facts (land-nest)

• Directus image directus/directus:11.17.4; PUBLIC_URL=https://data.landshaft.life; PM2_INSTANCES=8; STORAGE_LOCAL_ROOT=./uploads; logs at ~/apps/directus/logs.
• ASSETS_TRANSFORM_MAX_CONCURRENT=45 per worker → over it errors; catch per file/preset.
• ASSETS_TRANSFORM_IMAGE_MAX_DIMENSION default 6000 is a pixel dimension guard, not a file-size limit. The extension imposes no limit; raise the Directus env var to process larger images.
• Local storage writes are non-atomic — warm only after an upload is committed.
• RATE_LIMITER_* applies to HTTP only → irrelevant to in-process generation (this is why the admin knob is concurrency, not a rate limit).
• Observed bottleneck (2026-10-23 log triage): storage:local:responseTime 1206ms, pg:responseTime 150–738ms; no 503s, no sharp errors. Pre-generation removes the cold-transform cost; uploads-volume I/O latency is a separate ops concern.

Safety (do not crash prod)

• Every entrypoint body is wrapped so thrown errors are logged and swallowed — never propagate into Directus core. ALL behaviour is gated by enabled (default false): a loaded-but-disabled bundle does nothing.
• Test only on the staging stack (dev/compose.dev.yml), never the prod instance.
• Rollout = backup previous dist/ → deploy → healthcheck → enable; rollback = restore dist/ + disable.
• Automation (autonomous loops) gets staging only: a scoped token limited to /image-previews/* (+ directus_files metadata read), never a prod admin token; never the prod Docker socket; restricted non-sudo SSH or opencode-on-host. Promotion to prod is a human action.

Conventions

• Build via @directus/extensions-sdk (npm run build / dev / link); bundle emits dist/app.js + dist/api.js.
• Deploy with npm run publish (scp dist + package.json to land-nest extensions dir).
• Tests: node:test via tsx (npm test). Typecheck: npm run typecheck.
• Do not add comments unless asked. Follow the sibling extensions' style.
• Never commit without explicit request.