@njinlabs/njin 0.10.3 → 0.11.0

package/README.md

@@ -334,6 +334,50 @@ DELETE /api/auth/logout        # Bearer <token>
 
 All `/api/*` endpoints require `Authorization: Bearer <token>`.
 
+## MCP — manage the site with AI agents
+
+njin exposes a remote [MCP](https://modelcontextprotocol.io) server at `POST /mcp` (Streamable HTTP), so an agent such as Claude Cowork or Claude Desktop can read and edit content, change settings and upload files.
+
+**Other AI clients.** Any MCP client that speaks Streamable HTTP and OAuth with dynamic client registration can connect. These OAuth callbacks are accepted out of the box: Claude, ChatGPT, Cursor, VS Code, and any loopback address (`localhost` / `127.0.0.1` — what Gemini CLI, Claude Code, Codex CLI, MCP Inspector and similar desktop clients use). For a client with its own hosted callback, allow it in `config.ts` — and only for clients you trust, since it is where the sign-in code is sent:
+
+```ts
+export default defineConfig({
+  mcp: {
+    redirectUris: [
+      "https://app.example.com/oauth/callback",   // exact
+      "https://client.example.com/connectors/*",  // path prefix
+    ],
+  },
+});
+```
+
+A client that can't do OAuth but can send a header can use a token from `POST /api/mcp-token` instead.
+
+**Connecting Claude:** add a custom connector and enter only the URL, `https://your-site.com/mcp`. Claude opens an njin sign-in page, you log in with your normal njin account and click **Allow** — no token to copy. The site must be reachable from the internet over HTTPS; set `publicUrl` in `config.ts` if it sits behind a proxy that rewrites the host.
+
+| Tool | |
+| --- | --- |
+| `list_models` | Every model and `vars` group with its JSON schema — agents call this first |
+| `read_records`, `get_record` | Search, filter, sort, paginate, populate |
+| `create_record`, `update_record`, `delete_record` | Validated through the model's own schema, so hooks and transforms run exactly as over REST |
+| `get_vars`, `update_vars` | Settings groups |
+| `create_upload_url`, `check_upload` | Add files (below) |
+| `list_files`, `get_file`, `delete_file` | Manage uploaded files |
+
+**Links.** A relation or file field takes the related record's id as a plain string, and that is what `list_models` tells the agent. If an agent sends an object instead (`{ "id": "..." }`, or a whole record read earlier) it is reduced to the id before saving — otherwise njin would store a dead embedded copy rather than a link. Created and updated records come back with their relations expanded, with a `_warnings` entry if a link points at nothing, and reads flag records that already hold an embedded `{ id }` copy so they can be repaired.
+
+**Files.** File bytes can't go through a tool call, so `create_upload_url` returns a short-lived link (10 minutes, up to 10 files of 10 MB). The agent uploads with `curl -F file=@photo.jpg <url>`, or — if it has no shell or network — shows the link so you can open it and drop the file. `check_upload` then returns the file ids to put in a model's file field. Only safe types are accepted (images except SVG, PDF, Office documents, audio, video, zip, fonts); HTML, SVG and scripts are rejected because `/uploads` is served from the site's own origin.
+
+**Managing connections.** Every connected agent is a token you can revoke:
+
+```bash
+GET    /api/mcp-token       # connected agents (OAuth) and manually created tokens
+DELETE /api/mcp-token/:id   # revoke — takes effect immediately
+POST   /api/mcp-token       # { name } → a long-lived token, shown once, for clients that can send an Authorization header
+```
+
+These need an admin session token, never an MCP token. There is no per-agent permission scoping yet: an agent can do anything an admin can in the content API (it cannot touch users or sessions).
+
 ## Admin panel
 
 njin doesn't bundle an admin panel — `_admin/` at your project root is just a static folder the server looks for at startup (`GET /_admin`). Drop a built admin SPA's `index.html`/assets into it (your own, or one shared by the community) and it's served automatically; if it's missing, the startup banner just notes it wasn't found.
@@ -349,6 +393,7 @@ import bunFilesystemAdapter from "@njinlabs/njin/adapters/bun_filesystem";
 
 export default defineConfig({
   port: Number(process.env.PORT ?? 3000),
+  publicUrl: "https://your-site.com", // optional — only needed behind a proxy; used by the MCP/OAuth discovery documents
   db: {
     path: process.env.DB_PATH ?? "rocksdb://data",
     namespace: process.env.DB_NAMESPACE ?? "general",
@@ -404,8 +449,11 @@ bunx njin dev       # Start dev server (Elysia + Vite HMR)
 bunx njin build     # Build for production -> ./out (public/, _admin/, views/, compiled server)
 bunx njin start     # Run from source in production mode (no compile)
 bunx njin update    # Update @njinlabs/njin to the latest version and refresh _admin/
+bunx njin update --beta  # Follow the beta channel instead (or --tag <name>)
 ```
 
+**Trying a beta.** Prereleases never become `latest`, so a normal install or update never picks one up. New project: `bunx @njinlabs/njin@beta create my-web`. Existing project: `bunx njin update --beta` (the dependency is pinned to that exact version). To go back to stable, set `@njinlabs/njin` to a stable version in `package.json` and run `bunx njin update`.
+
 Wire these as `package.json` scripts (`"dev": "njin dev"`, etc.) if you'd rather run `bun run dev`.
 
 ## License

package/package.json

@@ -1,9 +1,16 @@
 {
   "name": "@njinlabs/njin",
-  "version": "0.10.3",
+  "version": "0.11.0",
   "description": "A modern framework for building company profiles, landing pages, and content-driven websites.",
   "type": "module",
-  "keywords": ["bun", "elysia", "surrealdb", "edgejs", "cms", "framework"],
+  "keywords": [
+    "bun",
+    "elysia",
+    "surrealdb",
+    "edgejs",
+    "cms",
+    "framework"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -16,10 +23,16 @@
   "engines": {
     "bun": ">=1.3.0"
   },
-  "files": ["src", "LICENSE"],
+  "files": [
+    "src",
+    "LICENSE"
+  ],
   "scripts": {
     "test": "bun test --isolate",
-    "test:coverage": "bun test --isolate --coverage"
+    "test:coverage": "bun test --isolate --coverage",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write ."
   },
   "bin": {
     "njin": "./src/cli/index.ts"
@@ -33,6 +46,7 @@
     "./adapters/*": "./src/core/adapters/*.ts"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.5.13",
     "@tailwindcss/vite": "^4.3.0",
     "@types/alpinejs": "^3.13.11",
     "@types/bun": "latest",
@@ -51,6 +65,7 @@
   "dependencies": {
     "@elysia/bearer": "^1.4.4",
     "@elysia/cors": "^1.4.2",
+    "@modelcontextprotocol/sdk": "^1.32.0",
     "@paralleldrive/cuid2": "^3.3.0",
     "@surrealdb/node": "^3.0.3",
     "edge.js": "^6.5.1",

package/src/cli/build-assets.ts

@@ -5,7 +5,10 @@ import { join } from "node:path";
 // Shared staging steps between `njin build` (compiled binary) and `njin build:worker`
 // (bundled JS entry) — both produce the same `out/public`, `out/src/views`, `out/_admin`
 // layout; only the server artifact itself differs.
-export const stageBuildAssets = async (root: string, outDir: string): Promise<void> => {
+export const stageBuildAssets = async (
+  root: string,
+  outDir: string,
+): Promise<void> => {
   await rm(outDir, { recursive: true, force: true });
   await mkdir(outDir, { recursive: true });
 

package/src/cli/build.ts

@@ -1,7 +1,7 @@
-import type { BunPlugin } from "bun";
 import { cp, mkdir, rm } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import type { BunPlugin } from "bun";
 import { stageBuildAssets } from "./build-assets";
 
 const root = process.cwd();
@@ -53,15 +53,21 @@ const NATIVE_FILE: Record<string, string> = {
 
 let surrealNativePlugin: BunPlugin | undefined;
 if (isRemoteBuild) {
-  console.log("• Remote db.path detected — skipping @surrealdb/node native binding");
+  console.log(
+    "• Remote db.path detected — skipping @surrealdb/node native binding",
+  );
 } else {
   const nativeFile = NATIVE_FILE[`${process.platform}-${process.arch}`];
   if (!nativeFile) {
-    console.error(`\n✗ Unsupported platform for @surrealdb/node: ${process.platform}-${process.arch}`);
+    console.error(
+      `\n✗ Unsupported platform for @surrealdb/node: ${process.platform}-${process.arch}`,
+    );
     process.exit(1);
   }
 
-  const surrealNodeDistDir = dirname(fileURLToPath(import.meta.resolve("@surrealdb/node")));
+  const surrealNodeDistDir = dirname(
+    fileURLToPath(import.meta.resolve("@surrealdb/node")),
+  );
   const bindingsDir = join(outDir, "bindings");
   await mkdir(bindingsDir, { recursive: true });
   await cp(join(surrealNodeDistDir, nativeFile), join(bindingsDir, nativeFile));
@@ -74,7 +80,9 @@ if (isRemoteBuild) {
         const original = await Bun.file(args.path).text();
         const marker = "const require = createRequire(import.meta.url);";
         if (!original.includes(marker)) {
-          throw new Error("@surrealdb/node's loader shape changed — expected createRequire marker not found");
+          throw new Error(
+            "@surrealdb/node's loader shape changed — expected createRequire marker not found",
+          );
         }
         // Wrap `require` so the host platform's own .node lookup is redirected to the copy in
         // out/bindings/; every other platform's file and the optional sibling npm packages fall
@@ -119,28 +127,42 @@ const geoipLibDir = dirname(fileURLToPath(import.meta.resolve("geoip-lite")));
 const geoipDataDir = join(geoipLibDir, "..", "data");
 const outGeoipDataDir = join(outDir, "geoip-data");
 await mkdir(outGeoipDataDir, { recursive: true });
-await cp(join(geoipDataDir, "geoip-country.dat"), join(outGeoipDataDir, "geoip-country.dat"));
-await cp(join(geoipDataDir, "geoip-country6.dat"), join(outGeoipDataDir, "geoip-country6.dat"));
+await cp(
+  join(geoipDataDir, "geoip-country.dat"),
+  join(outGeoipDataDir, "geoip-country.dat"),
+);
+await cp(
+  join(geoipDataDir, "geoip-country6.dat"),
+  join(outGeoipDataDir, "geoip-country6.dat"),
+);
 console.log("✓ Copied geoip-lite country data -> out/geoip-data");
 
 const geoipDataPlugin: BunPlugin = {
   name: "geoip-lite-data-dir",
   setup(build) {
-    build.onLoad({ filter: /geoip-lite[\\/]lib[\\/]geoip\.js$/ }, async (args) => {
-      const original = await Bun.file(args.path).text();
-      const marker = "global.geodatadir || process.env.GEODATADIR || '../data/'";
-      if (!original.includes(marker)) {
-        throw new Error("geoip-lite's data dir resolution changed — expected marker not found");
-      }
-      const patched = original.replace(
-        "var geodatadir = path.resolve(\n\t__dirname,\n\t" + marker + "\n);",
-        "var geodatadir = require('path').join(require('path').dirname(process.execPath), 'geoip-data');",
-      );
-      if (patched === original) {
-        throw new Error("geoip-lite's geodatadir block didn't match expected shape — patch did not apply");
-      }
-      return { contents: patched, loader: "js" };
-    });
+    build.onLoad(
+      { filter: /geoip-lite[\\/]lib[\\/]geoip\.js$/ },
+      async (args) => {
+        const original = await Bun.file(args.path).text();
+        const marker =
+          "global.geodatadir || process.env.GEODATADIR || '../data/'";
+        if (!original.includes(marker)) {
+          throw new Error(
+            "geoip-lite's data dir resolution changed — expected marker not found",
+          );
+        }
+        const patched = original.replace(
+          "var geodatadir = path.resolve(\n\t__dirname,\n\t" + marker + "\n);",
+          "var geodatadir = require('path').join(require('path').dirname(process.execPath), 'geoip-data');",
+        );
+        if (patched === original) {
+          throw new Error(
+            "geoip-lite's geodatadir block didn't match expected shape — patch did not apply",
+          );
+        }
+        return { contents: patched, loader: "js" };
+      },
+    );
   },
 };
 
@@ -173,7 +195,9 @@ printBanner({ mode: "production" });
     // reasoning for @surrealdb/node on a remote build — surreal.ts's dynamic import of it is
     // unreachable when db.path is remote, so it's safe to leave unresolved.
     external: isRemoteBuild ? ["vite", "@surrealdb/node"] : ["vite"],
-    plugins: [surrealNativePlugin, geoipDataPlugin].filter((p): p is BunPlugin => p !== undefined),
+    plugins: [surrealNativePlugin, geoipDataPlugin].filter(
+      (p): p is BunPlugin => p !== undefined,
+    ),
     // The CLI's `bun build --compile` implicitly inlines process.env.NODE_ENV as "production";
     // the Bun.build() JS API doesn't, so view.ts's top-level `isDev` check would otherwise read
     // undefined and take the dev branch (importing the externalized, not-on-disk `vite`).

package/src/cli/create.ts

@@ -1,11 +1,20 @@
 import { existsSync, mkdirSync, readdirSync } from "node:fs";
 import { join, resolve } from "node:path";
 
-const c = { reset: "\x1b[0m", bold: "\x1b[1m", dim: "\x1b[2m", cyan: "\x1b[36m", green: "\x1b[32m" };
+const c = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+};
 
 const targetArg = process.argv[3] ?? ".";
 const targetDir = resolve(process.cwd(), targetArg);
-const projectName = targetArg === "." ? "njin-app" : targetArg.split(/[\\/]/).filter(Boolean).pop()!;
+const projectName =
+  targetArg === "."
+    ? "njin-app"
+    : targetArg.split(/[\\/]/).filter(Boolean).pop()!;
 
 if (existsSync(targetDir) && readdirSync(targetDir).length > 0) {
   console.error(`✖ Directory "${targetArg}" already exists and is not empty.`);
@@ -35,11 +44,23 @@ mkdirSync(targetDir, { recursive: true });
 
 // `--strip-components=2` drops the `njin-<version>/template/` prefix baked into
 // GitHub's tag-tarball layout, so template/ contents land directly in targetDir.
-const tar = Bun.spawn(["tar", "-xz", "-f", "-", "--strip-components=2", "-C", targetDir, `njin-${pkg.version}/template`], {
-  stdin: res.body,
-  stdout: "inherit",
-  stderr: "inherit",
-});
+const tar = Bun.spawn(
+  [
+    "tar",
+    "-xz",
+    "-f",
+    "-",
+    "--strip-components=2",
+    "-C",
+    targetDir,
+    `njin-${pkg.version}/template`,
+  ],
+  {
+    stdin: res.body,
+    stdout: "inherit",
+    stderr: "inherit",
+  },
+);
 
 const tarExitCode = await tar.exited;
 
@@ -54,7 +75,10 @@ if (tarExitCode !== 0) {
 const pkgPath = join(targetDir, "package.json");
 const scaffoldedPkg = await Bun.file(pkgPath).json();
 scaffoldedPkg.name = projectName;
-scaffoldedPkg.dependencies = { "@njinlabs/njin": `^${pkg.version}`, ...scaffoldedPkg.dependencies };
+scaffoldedPkg.dependencies = {
+  "@njinlabs/njin": `^${pkg.version}`,
+  ...scaffoldedPkg.dependencies,
+};
 await Bun.write(pkgPath, JSON.stringify(scaffoldedPkg, null, 2) + "\n");
 
 console.log("Installing dependencies...\n");
@@ -69,7 +93,9 @@ const installExitCode = await install.exited;
 
 if (installExitCode !== 0) {
   console.error(`\n✖ "bun install" failed (exit code ${installExitCode}).`);
-  console.error(`  The project was scaffolded at ${targetDir}, but dependencies are not installed.`);
+  console.error(
+    `  The project was scaffolded at ${targetDir}, but dependencies are not installed.`,
+  );
   console.error(`  Run "cd ${targetArg} && bun install" manually to retry.\n`);
   process.exit(installExitCode);
 }

package/src/cli/index.ts

@@ -28,6 +28,7 @@ switch (command) {
   build         Build for production -> ./out (public/, _admin/, views/, server)
   build:worker  Build a headless worker for production -> ./out (public/, _admin/, views/, worker.js)
   start         Run from source in production mode (no compile)
-  update        Update @njinlabs/njin to the latest version and refresh _admin/`);
+  update        Update @njinlabs/njin to the latest version and refresh _admin/
+                (--beta, or --tag <name>, follows a prerelease channel instead)`);
     process.exit(command ? 1 : 0);
 }

package/src/cli/update.ts

@@ -3,13 +3,21 @@ import { existsSync } from "node:fs";
 import { mkdir, rm } from "node:fs/promises";
 import { join } from "node:path";
 
-const c = { reset: "\x1b[0m", bold: "\x1b[1m", dim: "\x1b[2m", cyan: "\x1b[36m", green: "\x1b[32m" };
+const c = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+};
 
 const root = process.cwd();
 const pkgPath = join(root, "package.json");
 
 if (!existsSync(pkgPath)) {
-  console.error(`✖ No package.json found in ${root} — run this from an njin project root.`);
+  console.error(
+    `✖ No package.json found in ${root} — run this from an njin project root.`,
+  );
   process.exit(1);
 }
 
@@ -21,41 +29,98 @@ const depKey = pkg.dependencies?.["@njinlabs/njin"]
     : undefined;
 
 if (!depKey) {
-  console.error(`✖ "@njinlabs/njin" is not listed in this project's package.json — run this from an njin project root.`);
+  console.error(
+    `✖ "@njinlabs/njin" is not listed in this project's package.json — run this from an njin project root.`,
+  );
+  process.exit(1);
+}
+
+const currentPinned = String(pkg[depKey]["@njinlabs/njin"]).replace(
+  /^[\^~]/,
+  "",
+);
+
+// `--beta` is shorthand for `--tag beta`. Without either, only the stable channel (`latest`)
+// is followed — a prerelease is published under its own dist-tag and never becomes `latest`.
+const args = process.argv.slice(3);
+const tagIndex = args.indexOf("--tag");
+const requestedTag = args.includes("--beta")
+  ? "beta"
+  : tagIndex !== -1
+    ? args[tagIndex + 1]
+    : undefined;
+
+if (tagIndex !== -1 && (!requestedTag || requestedTag.startsWith("-"))) {
+  console.error(`✖ --tag needs a dist-tag name, e.g. "--tag beta".`);
   process.exit(1);
 }
 
-const currentPinned = String(pkg[depKey]["@njinlabs/njin"]).replace(/^[\^~]/, "");
+const distTag = requestedTag ?? "latest";
 
-console.log("Checking latest njin version...\n");
+console.log(
+  `Checking ${distTag === "latest" ? "latest" : `"${distTag}"`} njin version...\n`,
+);
 
-const registryRes = await fetch("https://registry.npmjs.org/@njinlabs/njin/latest");
+const registryRes = await fetch(
+  `https://registry.npmjs.org/@njinlabs/njin/${encodeURIComponent(distTag)}`,
+);
 if (!registryRes.ok) {
-  console.error(`✖ Could not reach the npm registry (HTTP ${registryRes.status}).`);
+  console.error(
+    registryRes.status === 404
+      ? `✖ There is no "${distTag}" release of njin on npm.`
+      : `✖ Could not reach the npm registry (HTTP ${registryRes.status}).`,
+  );
   process.exit(1);
 }
 
 const { version: latest } = (await registryRes.json()) as { version: string };
 const adminDir = join(root, "_admin");
 
+// A project already on a prerelease would otherwise be moved *back* to the older stable
+// version by a plain `njin update` — only an explicit --beta/--tag may change channel.
+const isBehindCurrent = (() => {
+  try {
+    return Bun.semver.order(latest, currentPinned) === -1;
+  } catch {
+    return false;
+  }
+})();
+
+if (!requestedTag && isBehindCurrent) {
+  console.log(
+    `${c.green}✓${c.reset} This project is on ${currentPinned}, ahead of the latest stable (${latest}) — nothing to update. Use "--beta" to follow the beta channel.`,
+  );
+  process.exit(0);
+}
+
 if (currentPinned === latest && existsSync(adminDir)) {
-  console.log(`${c.green}✓${c.reset} Already on the latest version (${latest}) — nothing to update.`);
+  console.log(
+    `${c.green}✓${c.reset} Already on the latest version (${latest}) — nothing to update.`,
+  );
   process.exit(0);
 }
 
 console.log(`Updating njin ${currentPinned} -> ${latest}...\n`);
 
-pkg[depKey]["@njinlabs/njin"] = `^${latest}`;
+// A prerelease is pinned exactly: "^0.11.0-beta.1" would also accept later stable 0.x releases
+// on the next install, silently leaving the beta channel the user chose.
+pkg[depKey]["@njinlabs/njin"] = distTag === "latest" ? `^${latest}` : latest;
 await Bun.write(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
 
 console.log("Installing dependencies...\n");
 
-const install = Bun.spawn(["bun", "install"], { cwd: root, stdout: "inherit", stderr: "inherit" });
+const install = Bun.spawn(["bun", "install"], {
+  cwd: root,
+  stdout: "inherit",
+  stderr: "inherit",
+});
 const installExitCode = await install.exited;
 
 if (installExitCode !== 0) {
   console.error(`\n✖ "bun install" failed (exit code ${installExitCode}).`);
-  console.error(`  package.json now points at njin ${latest}; run "bun install" manually to retry.`);
+  console.error(
+    `  package.json now points at njin ${latest}; run "bun install" manually to retry.`,
+  );
   process.exit(installExitCode);
 }
 
@@ -82,11 +147,23 @@ await mkdir(adminDir, { recursive: true });
 
 // --strip-components=3 drops the `njin-<version>/template/_admin/` prefix baked into GitHub's
 // tag-tarball layout, so _admin/'s own contents land directly in adminDir.
-const tar = Bun.spawn(["tar", "-xz", "-f", "-", "--strip-components=3", "-C", adminDir, `njin-${latest}/template/_admin`], {
-  stdin: res.body,
-  stdout: "inherit",
-  stderr: "inherit",
-});
+const tar = Bun.spawn(
+  [
+    "tar",
+    "-xz",
+    "-f",
+    "-",
+    "--strip-components=3",
+    "-C",
+    adminDir,
+    `njin-${latest}/template/_admin`,
+  ],
+  {
+    stdin: res.body,
+    stdout: "inherit",
+    stderr: "inherit",
+  },
+);
 
 const tarExitCode = await tar.exited;
 

package/src/config/module.ts

@@ -7,6 +7,10 @@ import elysia from "../modules/elysia";
 import file from "../modules/file";
 import img from "../modules/img";
 import logger from "../modules/logger";
+import mcp from "../modules/mcp";
+import mcpToken from "../modules/mcp_token";
+import mcpUpload from "../modules/mcp_upload";
+import oauth from "../modules/oauth";
 import plugin from "../modules/plugin";
 import setup from "../modules/setup";
 import surreal from "../modules/surreal";
@@ -31,9 +35,14 @@ const modules = [
   await plugin.init(),
   await file.init(),
   await auth.init(),
+  await mcpToken.init(),
   await setup.init(),
   await api.init(),
   await vars.init(),
+  // After api/vars so models' hooks and events are already registered (api.init drains them).
+  await mcp.init(),
+  await mcpUpload.init(),
+  await oauth.init(),
   await img.init(),
   await analytics.init(),
   await users.init(),

package/src/core/adapters/bun_filesystem.ts

@@ -1,7 +1,7 @@
-import type { FileAdapter } from "../../modules/file";
-import { init } from "@paralleldrive/cuid2";
 import { join, resolve } from "node:path";
+import { init } from "@paralleldrive/cuid2";
 import z from "zod";
+import type { FileAdapter } from "../../modules/file";
 import { getConfig } from "../config";
 import { sanitizeFileName } from "../path_guard";
 
@@ -13,7 +13,11 @@ const createId = init({
 
 const meta = z.null();
 
-const bunFilesystemAdapter = ({ dir = "./uploads" }: { dir?: string } = {}): FileAdapter<typeof meta> => {
+const bunFilesystemAdapter = ({
+  dir = "./uploads",
+}: {
+  dir?: string;
+} = {}): FileAdapter<typeof meta> => {
   return {
     meta,
     dir,
@@ -25,7 +29,10 @@ const bunFilesystemAdapter = ({ dir = "./uploads" }: { dir?: string } = {}): Fil
       // resolve(), not join() — dir is normally project-relative ("./uploads"), but an
       // already-absolute dir (as tests pass directly) must win outright rather than get
       // nested under rootDir.
-      await Bun.write(join(resolve(getConfig().rootDir, dir), name), await file.arrayBuffer());
+      await Bun.write(
+        join(resolve(getConfig().rootDir, dir), name),
+        await file.arrayBuffer(),
+      );
 
       return {
         meta: null,
@@ -35,7 +42,8 @@ const bunFilesystemAdapter = ({ dir = "./uploads" }: { dir?: string } = {}): Fil
         url: `/uploads/${name}`,
       };
     },
-    unlink: (file) => Bun.file(join(resolve(getConfig().rootDir, dir), file.name)).delete(),
+    unlink: (file) =>
+      Bun.file(join(resolve(getConfig().rootDir, dir), file.name)).delete(),
   };
 };
 

package/src/core/adapters/s3.ts

@@ -1,7 +1,7 @@
-import type { FileAdapter } from "../../modules/file";
 import { init } from "@paralleldrive/cuid2";
 import type { S3Options } from "bun";
 import z from "zod";
+import type { FileAdapter } from "../../modules/file";
 import { sanitizeFileName } from "../path_guard";
 
 const createId = init({
@@ -22,10 +22,15 @@ type ResolveUrlOptions = {
 // Path-style works for AWS S3 and S3-compatible services alike (R2, Spaces, MinIO).
 // No process.env fallback here on purpose — the consuming project's config.ts is the
 // single place that decides whether a value comes from an env var or is hardcoded.
-export const resolveUrl = (key: string, options: ResolveUrlOptions = {}): string => {
-  if (options.publicUrl) return `${options.publicUrl.replace(/\/$/, "")}/${key}`;
+export const resolveUrl = (
+  key: string,
+  options: ResolveUrlOptions = {},
+): string => {
+  if (options.publicUrl)
+    return `${options.publicUrl.replace(/\/$/, "")}/${key}`;
 
-  if (options.endpoint) return `${options.endpoint.replace(/\/$/, "")}/${options.bucket}/${key}`;
+  if (options.endpoint)
+    return `${options.endpoint.replace(/\/$/, "")}/${options.bucket}/${key}`;
 
   const region = options.region ?? "us-east-1";
   return `https://${options.bucket}.s3.${region}.amazonaws.com/${key}`;
@@ -34,7 +39,9 @@ export const resolveUrl = (key: string, options: ResolveUrlOptions = {}): string
 // `bucket` is required (unlike Bun.S3Client itself, which would otherwise fall back to
 // S3_BUCKET/AWS_BUCKET env vars) — resolveUrl() needs to know it regardless, and reading
 // it here directly would bypass the project's own config.ts as the single source of truth.
-const s3Adapter = (options: S3Options & { bucket: string; publicUrl?: string }): FileAdapter<typeof meta> => {
+const s3Adapter = (
+  options: S3Options & { bucket: string; publicUrl?: string },
+): FileAdapter<typeof meta> => {
   const { publicUrl, ...s3Options } = options;
   const bucket = new Bun.S3Client(s3Options);
 
@@ -51,7 +58,12 @@ const s3Adapter = (options: S3Options & { bucket: string; publicUrl?: string }):
         name: key,
         size: file.size,
         type: file.type,
-        url: resolveUrl(key, { publicUrl, endpoint: s3Options.endpoint, bucket: s3Options.bucket, region: s3Options.region }),
+        url: resolveUrl(key, {
+          publicUrl,
+          endpoint: s3Options.endpoint,
+          bucket: s3Options.bucket,
+          region: s3Options.region,
+        }),
       };
     },
     unlink: (file) => bucket.delete(file.name),