@warlock.js/core 4.0.174 → 4.1.3

package/skills/upload-file/SKILL.md

@@ -0,0 +1,297 @@
+---
+name: upload-file
+description: 'Handle multipart file uploads — read via `request.file()` or `request.validated()`, validate with `v.file()`, save via `UploadedFile.save()` or the storage layer, transform images inline. Triggers: `UploadedFile`, `request.file`, `v.file`, `.save`, `.saveAs`, `.resize`, `.format`, `.quality`, `.image`, `.mimeType`, `.maxSize`; "accept a file upload", "validate file size and mime", "save to S3 or local disk", "resize an uploaded image on save"; typical import `import type { UploadedFile, RequestHandler } from "@warlock.js/core"`. Skip: storage drivers + presigned URLs — `@warlock.js/core/store-file/SKILL.md`; image-only transforms — `@warlock.js/core/process-image/SKILL.md`; schema rules — `@warlock.js/core/validate-input/SKILL.md`; competing libs `multer`, `formidable`, `busboy`.'
+---
+
+# Warlock — upload a file
+
+Multipart uploads come in as `UploadedFile` instances. The class wraps Fastify's multipart data and adds a fluent API for validation, image transforms, and storage. Save with `.save(directory)` for auto-naming or `.saveAs(path)` for an explicit path; both return a `StorageFile` with the final path/URL.
+
+## The shape
+
+```ts title="src/app/uploads/schema/index.ts"
+import { v } from "@warlock.js/seal";
+
+export const uploadAvatarSchema = v.object({
+  avatar: v
+    .file()
+    .image()
+    .maxSize({ unit: "MB", size: 5 })
+    .mimeType(["image/jpeg", "image/png", "image/webp"]),
+});
+```
+
+```ts title="src/app/uploads/controllers/upload-avatar.controller.ts"
+import { type GuardedRequestHandler } from "app/auth/types/guarded-request.type";
+import { type UploadAvatarSchema, uploadAvatarSchema } from "../schema/upload-avatar.schema";
+
+export const uploadAvatarController: GuardedRequestHandler<UploadAvatarSchema> = async (
+  request,
+  response,
+) => {
+  const { avatar } = request.validated();
+
+  const file = await avatar
+    .resize(400, 400)
+    .format("webp")
+    .quality(85)
+    .save(`avatars/${request.user.id}`);
+
+  return response.successCreate({ path: file.path, url: file.url });
+};
+
+uploadAvatarController.validation = {
+  schema: uploadAvatarSchema,
+};
+```
+
+That's the full flow: schema declares the validation (value + type from one file in `schema/`), controller uses `GuardedRequestHandler<UploadAvatarSchema>` (or `RequestHandler<Request<UploadAvatarSchema>>` for public routes), pull from `request.validated()`, chain transforms, save to disk. The result is a `StorageFile` with `path`, `url`, `mimeType`, and the rest.
+
+## Reading the file
+
+Inside a controller:
+
+```ts
+import type { RequestHandler, UploadedFile } from "@warlock.js/core";
+
+export const uploadController: RequestHandler = async (request, response) => {
+  // option A — direct from request, no validation
+  const file: UploadedFile | undefined = request.file("avatar");
+
+  if (!file) {
+    return response.badRequest({ error: "missing file" });
+  }
+
+  // option B — typed via the schema (preferred when you've defined one)
+  const { avatar } = request.validated<{ avatar: UploadedFile }>();
+};
+```
+
+`request.file(key)` returns `UploadedFile | undefined`. With a schema attached, `request.validated()` is typed via `Infer<typeof schema>` so the file field comes out as `UploadedFile` directly.
+
+For multi-file uploads, use an array schema (`v.array(v.file())`) — the validated value is `UploadedFile[]`.
+
+## The `UploadedFile` API
+
+From `@warlock.js/core/src/http/uploaded-file.ts`:
+
+| Member                              | Returns                | Notes                                                  |
+| ----------------------------------- | ---------------------- | ------------------------------------------------------ |
+| `file.name`                         | `string`               | sanitized original filename                            |
+| `file.mimeType`                     | `string`               | e.g. `"image/jpeg"`                                    |
+| `file.extension`                    | `string`               | lowercased, no dot — e.g. `"jpg"`                      |
+| `file.isImage` / `isVideo` / `isAudio` | `boolean`           | MIME-type prefix checks                                |
+| `await file.size()`                 | `number` (bytes)       | buffers the file on first call                         |
+| `await file.buffer()`               | `Buffer`               | cached after first call                                |
+| `await file.dimensions()`           | `{ width?, height? }`  | empty object if not an image                           |
+| `await file.metadata()`             | `{ name, mimeType, extension, size, width?, height? }` | one-shot metadata |
+| `await file.toImage()`              | `Image`                | for advanced transforms outside the fluent API         |
+| `await file.toJSON()`               | metadata + base64      | for serialization / debugging                          |
+
+Image transforms (chainable, no-op for non-images):
+
+| Method                          | Notes                                  |
+| ------------------------------- | -------------------------------------- |
+| `.resize(width, height?)`       | proportional if `height` omitted       |
+| `.format(format)`               | `"jpeg" | "png" | "webp" | "avif" | ...` — extension is auto-updated |
+| `.quality(1–100)`               | JPEG/WebP/AVIF only                    |
+| `.rotate(deg)`                  | positive = clockwise                   |
+| `.blur(sigma?)`                 | default `3`, min `0.3`                 |
+| `.grayscale()`                  | —                                      |
+| `.transform(opts | callback)`   | full sharp/`ImageTransformOptions` control |
+
+Save:
+
+```ts
+await file.save(directory, options?);   // auto-named, returns StorageFile
+await file.saveAs(fullPath, options?);  // explicit path, returns StorageFile
+```
+
+Driver selection:
+
+```ts
+await file.use("s3").save("avatars");        // single upload
+await file.use("r2").saveAs("cdn/x.webp");
+```
+
+## Save options
+
+```ts
+type SaveOptions = {
+  name?: "random" | "original" | string; // default "random"
+  prefix?:
+    | true                                  // default datetime prefix
+    | string                                // static prefix
+    | {
+        format?: string;                    // dayjs-style format
+        randomLength?: number;
+        as?: "file" | "directory";          // default "file"
+      };
+  driver?: StorageDriverName;
+  validate?: FileValidationOptions;         // throws on mismatch
+};
+```
+
+```ts
+// Random name (default): avatars/x7k9m2p4.jpg
+await file.save("avatars");
+
+// Keep original: avatars/photo.jpg
+await file.save("avatars", { name: "original" });
+
+// Date directory + random name: avatars/2026/05/23/x7k9m2p4.jpg
+await file.save("avatars", {
+  prefix: { format: "YYYY/MM/DD", as: "directory" },
+});
+
+// Validate-then-save in one call
+await file.save("avatars", {
+  validate: {
+    allowedMimeTypes: ["image/jpeg", "image/png"],
+    maxSize: 5 * 1024 * 1024,
+  },
+});
+```
+
+For an explicit path, `saveAs` skips naming/prefix logic:
+
+```ts
+await file.saveAs("avatars/profile-123.png");
+```
+
+## What `save()` returns: `StorageFile`
+
+```ts
+const stored = await file.save("avatars");
+
+stored.path;          // "avatars/x7k9m2p4.webp" (after format transform)
+stored.url;           // public URL (driver-dependent)
+await stored.size();
+await stored.mimeType();
+stored.extension;
+await stored.data();  // full info object incl. hash
+```
+
+`StorageFile` is the standard handle returned by every `Storage.put()` / `UploadedFile.save()` call. Use it from then on — the `UploadedFile` is best discarded after save.
+
+## Saving directly via the storage layer
+
+`UploadedFile.save()` is the shortcut. For full control, drop to the storage API and pass the buffer:
+
+```ts
+import { storage } from "@warlock.js/core";
+
+const buffer = await file.buffer();
+
+const stored = await storage.use("s3").put(buffer, "uploads/manual/file.bin", {
+  mimeType: file.mimeType,
+});
+```
+
+`storage.put(content, location, options)` accepts `Buffer | string | UploadedFile | Readable`. Also: `putStream`, `putFromUrl`, `putFromBase64`. Use the storage layer directly for non-file payloads (already-processed buffers, programmatically generated content) and `UploadedFile.save()` for raw multipart uploads.
+
+## Validation rules
+
+Inside a seal schema, file rules chain on `v.file()`:
+
+```ts
+v.file()                                          // must be UploadedFile
+  .image()                                        // must be image MIME
+  .accept(["jpg", "png", "webp"])                 // extension allowlist
+  .mimeType(["image/jpeg", "image/png"])          // MIME allowlist
+  .pdf() / .excel() / .word()                     // shortcuts
+  .minSize({ unit: "KB", size: 10 })
+  .maxSize({ unit: "MB", size: 5 })
+  .minWidth(200).maxWidth(4000)
+  .minHeight(200).maxHeight(4000);
+```
+
+Size accepts either bytes (`.maxSize(5_242_880)`) or `{ unit, size }` (`{ unit: "MB", size: 5 }`). See [`validate-input`](../validate-input/SKILL.md) for the full validation pattern.
+
+For ad-hoc validation outside a schema:
+
+```ts
+await file.validate({
+  allowedMimeTypes: ["image/jpeg", "image/png"],
+  allowedExtensions: ["jpg", "jpeg", "png"],
+  maxSize: 5 * 1024 * 1024,
+});
+// throws on mismatch
+```
+
+## Common patterns
+
+### Multi-file upload
+
+```ts title="src/app/uploads/schema/index.ts"
+import { v } from "@warlock.js/seal";
+
+export const uploadFilesSchema = v.object({
+  files: v
+    .array(v.file().maxSize({ unit: "MB", size: 50 }).mimeType(ALLOWED_MIME_TYPES))
+    .maxLength(5),
+});
+```
+
+```ts title="src/app/uploads/controllers/create-upload.controller.ts"
+import type { RequestHandler } from "@warlock.js/core";
+
+export const createUploadController: RequestHandler = async (request, response) => {
+  const { files } = request.validated();
+
+  const saved = await Promise.all(
+    files.map((file) =>
+      file.save(`uploads/${request.user.organizationId}`, {
+        prefix: { as: "directory", format: "DD-MM-YYYY" },
+      }),
+    ),
+  );
+
+  return response.successCreate({ uploads: saved.map((f) => ({ path: f.path })) });
+};
+```
+
+### Image processing pipeline
+
+```ts
+const thumb = await avatar.resize(200, 200).format("webp").quality(80).save("avatars/thumb");
+
+const full = await avatar.resize(1200).format("webp").quality(90).save("avatars/full");
+```
+
+Each chain produces a fresh transform — but `UploadedFile` is stateful, so do this once and keep references to the saved `StorageFile`s.
+
+### Saving to S3 with a content type override
+
+```ts
+const file = await uploadedFile
+  .use("s3")
+  .save("documents", { name: "original" });
+
+// or, full storage layer:
+await storage.use("s3").put(await uploadedFile.buffer(), "documents/report.pdf", {
+  mimeType: "application/pdf",
+  cacheControl: "max-age=31536000",
+});
+```
+
+### Stream a download from a stored file
+
+The reverse direction — sending a stored file back via `response.sendFile(...)` is the cleanest path. For dynamic content, use `response.stream(...)`. See [`send-response`](../send-response/SKILL.md).
+
+## Gotchas
+
+- **`file.buffer()` reads the entire file into memory.** For large uploads, prefer `Storage.putStream(...)` (drop straight from `request.file().fileData.file` if you have access — but in most cases `save()` is fine).
+- **Image transforms only apply to images.** `file.resize(...).save(...)` on a PDF is a no-op for the resize and a successful save for the file.
+- **`save()` rewrites the extension on format change.** `file.format("webp").save("avatars")` produces `avatars/<name>.webp` regardless of the upload's original extension.
+- **`.use(driver)` mutates the instance.** It returns `this`; subsequent saves on the same instance keep the driver. Re-instantiate or call `.use("local")` to reset.
+- **Multipart parsing needs `fileUploadLimit` headroom.** Default is `10MB` (configurable via `http.fileUploadLimit` in `src/config/http.ts`). Schema `maxSize` is checked after parsing, so set the multipart limit at least as high.
+- **`request.file("key")` returns `undefined` for missing files** — no throw. Always check before chaining.
+- **The hash is empty until save.** `file.hash` is populated by the SHA-256 from `StorageFile.data()` after `save()` resolves.
+
+## See also
+
+- [`validate-input/SKILL.md`](../validate-input/SKILL.md) — `v.file()` rules and the validation pipeline.
+- [`create-controller/SKILL.md`](../create-controller/SKILL.md) — pulling files from `request.validated()` vs `request.file()`.
+- [`send-response/SKILL.md`](../send-response/SKILL.md) — `response.sendFile(...)` for serving the stored file back.
+- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — storage configuration and driver selection.

package/skills/use-app-context/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: use-app-context
+description: 'Read app-wide context — the `Application` static class (env, version, uptime, runtime strategy) plus the `app` runtime accessor (live Fastify, socket.io, router, database via the DI container). Triggers: `Application.isProduction`, `Application.environment`, `Application.runtimeStrategy`, `Application.uptime`, `Application.version`, `app.http`, `app.socket`, `app.database`, `app.router`; "branch on environment", "reach the live Fastify instance", "framework version in health endpoint", "dev vs production runtime check"; typical import `import { Application, app } from "@warlock.js/core"`. Skip: path helpers — `@warlock.js/core/resolve-path/SKILL.md`; connector start order — `@warlock.js/core/add-connector/SKILL.md`; competing patterns: bare `process.env.NODE_ENV`, ad-hoc Fastify imports.'
+---
+
+# Warlock — use the application context
+
+`Application` is the static class that exposes "where am I running, and where is everything?" without each call site re-parsing `process.env`, `process.cwd()`, or a package.json. Import it from `@warlock.js/core` and read off the static members directly — no instantiation.
+
+## The shape
+
+```ts
+import { Application } from "@warlock.js/core";
+
+if (Application.isProduction) {
+  // …production-only behavior
+}
+
+const uploadsDir = Application.uploadsPath;
+const uptimeMs   = Application.uptime;
+const version    = Application.version;
+```
+
+Every member is a getter — values are computed on access, not snapshotted at boot. That's deliberate: tests flip the environment, the dev server flips the runtime strategy, and the framework caches its own version. You always read the current value.
+
+## Environment
+
+```ts
+Application.environment      // "development" | "production" | "test"
+Application.isProduction     // === "production"
+Application.isDevelopment    // === "development"
+Application.isTest           // === "test"
+```
+
+Backed by `process.env.NODE_ENV`. `setEnvironment` mutates it:
+
+```ts
+Application.setEnvironment("test");
+```
+
+Used internally by the CLI (`preload.environemnt: "production"` calls `setEnvironment` before the action runs) and by Vitest setups. Don't call it from request handlers — it's process-global.
+
+The most common consumer is `src/config/http.ts`, picking the cookie security flag:
+
+```ts title="src/config/http.ts"
+import { Application, env, type HttpConfigurations } from "@warlock.js/core";
+
+const httpConfigurations: HttpConfigurations = {
+  cookies: {
+    secret: env("COOKIE_SECRET", "super-secret-key-change-me"),
+    options: {
+      httpOnly: true,
+      secure: Application.isProduction,   // true on prod (HTTPS only), false in dev
+      path: "/",
+    },
+  },
+};
+
+export default httpConfigurations;
+```
+
+## Runtime strategy
+
+`runtimeStrategy` is a separate axis from `environment`. It marks how the *framework itself* is running:
+
+- `"development"` — dev server (file watcher, HMR, transpile cache on disk).
+- `"production"` — built bundle running from `dist/`.
+
+```ts
+Application.runtimeStrategy           // "production" | "development"
+Application.setRuntimeStrategy("production");
+```
+
+The dev-server CLI command sets it to `"development"`. The `build` command and `start.production` set `"production"`. Use it inside connectors that need to behave differently in the bundled output — the built-in `HttpConnector` uses `router.scanDevServer()` in dev and `router.scan()` in production.
+
+Most app code shouldn't care about `runtimeStrategy` — branch on `environment` instead, which is the orthogonal "what world is this code talking to?" axis.
+
+## Paths
+
+For path helpers (`appPath`, `configPath`, `uploadsPath`, …) anchored at `process.cwd()`, the `paths.*` aggregate, and the `uploads.root` config override, see [`resolve-path/SKILL.md`](../resolve-path/SKILL.md).
+
+The most-used helpers are also surfaced as no-argument getters on `Application`:
+
+```ts
+Application.rootPath        // <cwd>
+Application.srcPath         // <cwd>/src
+Application.appPath         // <cwd>/src/app
+Application.publicPath      // <cwd>/public
+Application.storagePath     // <cwd>/storage
+Application.uploadsPath     // <cwd>/storage/uploads (or override)
+```
+
+Reach for those when you want the directory itself; reach for the helpers (e.g. `appPath("orders/routes.ts")`) when you need a file inside.
+
+## Version and uptime
+
+```ts
+Application.version        // "1.0.0" (semver, cached after first read)
+Application.uptime         // ms since process start
+Application.startedAt      // Date object — wall time when the process booted
+```
+
+`version` is the `@warlock.js/core` package version, lazily loaded once. `uptime` is `process.uptime() * 1000` — the Node-process uptime, not "the framework's uptime." If you spawn workers, each worker has its own.
+
+`startedAt` is computed once at module load: `new Date(Date.now() - process.uptime() * 1000)`. Stable across the run.
+
+The project's home page surfaces the version in a footer:
+
+```tsx
+<span>v{Application.version}</span>
+```
+
+## The `app` runtime accessor
+
+`Application` exposes **static metadata** (env, paths, version). For **runtime infrastructure** — the live Fastify instance, socket.io server, router, database connection — use the separate `app` object exported from `@warlock.js/core`:
+
+```ts
+import { app } from "@warlock.js/core";
+
+app.http        // Fastify instance (after http connector starts)
+app.socket      // socket.io Server (after socket connector starts)
+app.router      // the Router singleton
+app.database    // Cascade's DataSource
+```
+
+Each property is a getter backed by the framework's DI container (`container.get("http.server")` etc.). The container is populated by connectors during their `boot()`/`start()` phase — read these accessors only after the relevant connector has run. Every getter is a thin `container.get(...)`, so before the connector boots it returns `undefined` (it does **not** throw); chaining off an `undefined` accessor is what blows up. `http` and `socket` are *late*-phase connectors — they boot **after** app code is imported, so these accessors are not populated at the top level of a module's `main.ts`. From inside controllers, services, use-cases, or any code that runs while a request is in flight, every accessor is safe.
+
+Typical uses (note: from runtime code, after bootstrap — not at module-import time):
+
+```ts title="src/app/chat/setup-chat-socket.ts — attach a socket.io namespace"
+import { getSocketServer } from "@warlock.js/core";
+
+export function setupChatSocket() {
+  const io = getSocketServer();
+  if (!io) return; // socket connector not booted yet
+
+  io.of("/chat").on("connection", (socket) => {
+    // …
+  });
+}
+```
+
+```ts title="raw DataSource for an out-of-Cascade query"
+import { app } from "@warlock.js/core";
+
+const result = await app.database.client.query("SELECT NOW()");
+```
+
+Reach for `app.*` as the escape hatch. If a typed framework primitive wraps the same thing (`router.get(...)` over `app.http.route(...)`, repository methods over raw `app.database` queries), prefer that — the typed surface keeps you on the rails the rest of the framework is designed around.
+
+## Common patterns
+
+### Environment-aware logging level
+
+```ts title="src/config/log.ts"
+import { Application, type LogConfigurations } from "@warlock.js/core";
+
+const logConfig: LogConfigurations = {
+  level: Application.isProduction ? "info" : "debug",
+};
+
+export default logConfig;
+```
+
+### Resolve a file relative to the app root
+
+```ts
+import { appPath } from "@warlock.js/core";
+import { readFile } from "node:fs/promises";
+
+const template = await readFile(appPath("mailers/templates/welcome.html"), "utf-8");
+```
+
+### Health endpoint
+
+```ts title="src/app/system/controllers/health.controller.ts"
+import { Application, type RequestHandler, type Response } from "@warlock.js/core";
+
+export const healthController: RequestHandler = async (_request, response: Response) => {
+  return response.success({
+    status: "ok",
+    environment: Application.environment,
+    version: Application.version,
+    uptimeMs: Application.uptime,
+    startedAt: Application.startedAt,
+  });
+};
+```
+
+### Don't ship debug routes to production
+
+```ts title="src/app/dev/routes.ts"
+import { Application, router } from "@warlock.js/core";
+import { dumpStateController } from "./controllers/dump-state.controller";
+
+if (!Application.isProduction) {
+  router.get("/__dev/state", dumpStateController);
+}
+```
+
+(The framework's HMR diffs route registrations — wrapping `router.get()` in an `if` means the route exists or doesn't depending on env, which is fine for boot-time branches like this one.)
+
+### CORS — relax in dev, lock down in prod
+
+```ts title="src/config/http.ts"
+cors: {
+  origin: Application.isProduction
+    ? ["https://app.example.com"]
+    : "*",
+}
+```
+
+## Gotchas
+
+- **Don't cache `Application.isProduction` at module top-level.** Tests routinely flip `NODE_ENV` before importing modules; a cached snapshot survives the flip and produces stale behavior. Read the getter at use site.
+
+  ```ts
+  // ❌ cached at import time — wrong after env flips
+  const isProd = Application.isProduction;
+
+  export function logLevel() {
+    return isProd ? "info" : "debug";
+  }
+
+  // ✅ read at use site
+  export function logLevel() {
+    return Application.isProduction ? "info" : "debug";
+  }
+  ```
+
+- **`version` is `null` until the first `await`.** The version loader is async (it reads `package.json`). On a cold start before any framework code has run `getWarlockVersion()`, `Application.version` returns `null`. The framework does load it during bootstrap, so anywhere downstream of bootstrap is fine — controllers, services, connectors after `start()`. CLI commands without `preload.bootstrap` may see `null`.
+- **`Application` is static, not a DI registration.** Don't try to inject it. There's nothing to inject — it's a class with only static members.
+- **`app.*` accessors return `undefined` before their connector boots — they don't throw.** `app.socket` / `app.database` / `app.http` are populated by their respective connectors during boot; until then each getter returns `undefined` (a bare `container.get(...)`). Reading them earlier (eager module-load code, the top level of a `main.ts` for the late-phase `http`/`socket`, certain CLI commands without the right `preload.connectors`) hands you `undefined`, and chaining off it throws. Safe everywhere downstream of bootstrap.
+
+## See also
+
+- [`resolve-path/SKILL.md`](../resolve-path/SKILL.md) — path helpers (`appPath`, `configPath`, `uploadsPath`, …) and the `paths.*` aggregate.
+- [`configure-app/SKILL.md`](../configure-app/SKILL.md) — `src/config/*.ts` and `warlock.config.ts`.
+- [`add-connector/SKILL.md`](../add-connector/SKILL.md) — using `Application.runtimeStrategy` inside a connector's `start()`.
+- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — module layout, where paths point to.