@everysk/apps-devkit 0.1.0 → 0.3.0-beta-20261016180126

package/dist/vite/plugins/serveDevFiles.js

@@ -0,0 +1,153 @@
+import { createApiTokenSource } from "../apiToken.js";
+/** Every path under the platform's file route, claimed whole so none falls through to `index.html`. */
+const FILE_ROUTE = /^\/file\//;
+/**
+ * A file's url as the platform serves it: the hex of a version-4 UUID, as everysk/client's
+ * `FileRequestHandler` matches it (`RE_FILE_URL`).
+ */
+const FILE_URL = /^\/file\/([0-9a-f]{12}4[0-9a-f]{3}[89ab][0-9a-f]{15})\/?(?:\?.*)?$/;
+/** Why a file could not be served, with the status to answer it with. */
+class FileRouteError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/** The error and, when Node gives one, its cause, which is where fetch keeps ECONNREFUSED or DNS. */
+const describeError = (error) => {
+    if (!(error instanceof Error))
+        return String(error);
+    return error.cause instanceof Error
+        ? `${error.message}: ${error.cause.message}`
+        : error.message;
+};
+/** The API's own `message` from a refusal, or the start of whatever came back instead. */
+const refusalOf = async (response) => {
+    const text = await response.text();
+    try {
+        return JSON.parse(text).message ?? text.slice(0, 200);
+    }
+    catch {
+        return text.slice(0, 200);
+    }
+};
+/**
+ * The file whose stored url is `/<hash>`, read with its content. A file stores its url as
+ * `/<hash>` and the API adds `/file` only when it returns it, and the file list accepts a `url`
+ * filter without a workspace (everysk-lib 1.13.4 `sdk/entities/file`, everysk/client
+ * `File.validate_query`).
+ */
+const findFile = async (fetchApi, apiUrl, accessToken, hash) => {
+    const query = JSON.stringify({ filters: [["url", `/${hash}`]], page_size: 1 });
+    let response;
+    try {
+        response = await fetchApi(`${apiUrl}/files?query=${encodeURIComponent(query)}`, {
+            headers: { Authorization: `Bearer ${accessToken}` },
+        });
+    }
+    catch (error) {
+        throw new FileRouteError(502, `The API could not be reached: ${describeError(error)}`);
+    }
+    if (!response.ok) {
+        const refusal = await refusalOf(response);
+        throw new FileRouteError(502, `The API refused the file: ${response.status} ${response.statusText}: ${refusal}`);
+    }
+    let body;
+    try {
+        body = (await response.json());
+    }
+    catch {
+        throw new FileRouteError(502, `The API answered with ${response.headers.get("content-type")}, not JSON.`);
+    }
+    if (!Array.isArray(body.files)) {
+        throw new FileRouteError(502, `The file list came back without files: ${JSON.stringify(body).slice(0, 200)}`);
+    }
+    return body.files[0];
+};
+/** The content of a found file, refusing what would be served as an empty or corrupt file. */
+const contentOf = (file, hash) => {
+    if (typeof file.data !== "string") {
+        throw new FileRouteError(502, `The API returned ${file.name} (/file/${hash}) without its content.`);
+    }
+    if (file.data.startsWith("data:")) {
+        throw new FileRouteError(422, `${file.name} was stored as a data URL, so its bytes are not the file: upload it again, read with fileToBase64.`);
+    }
+    return Buffer.from(file.data, "base64");
+};
+/**
+ * createDevFileRoute
+ *
+ * The dev server's stand-in for the platform's `/file/<hash>` route. On the platform a file's
+ * `url` is that route, served with the user's session and shown inline; the dev server has no
+ * session, so the file is found through the API with the dev proxy's OAuth2 token instead, by
+ * its stored `url`, and its base64 content is decoded here and sent with its own type. So an app
+ * shows a file through its `url` wherever it runs.
+ *
+ * Read with the OAuth2 client's permissions, not a user's, as everything through the dev proxy is.
+ * Every path under `/file/` is answered here, never handed on: Vite would answer it with the
+ * app's `index.html` and a 200. A file that cannot be served gets a status that says why, and a
+ * line in the terminal, since an `<img>` or `<iframe>` never shows the body. Nothing escapes the
+ * middleware: Connect ignores its promise, and a rejection would end the dev server.
+ *
+ * @param params - The API, its token and last failure, and a `fetch` and a log to replace in tests.
+ * @returns A Connect middleware that answers `/file/` and passes everything else on.
+ */
+export const createDevFileRoute = ({ apiUrl, token, lastError, fetch: fetchApi = fetch, log = console.warn, }) => async (req, res, next) => {
+    const url = req.url ?? "";
+    if (!FILE_ROUTE.test(url))
+        return next();
+    const fail = (status, message) => {
+        log(`[dev server] ${url}: ${message}`);
+        res.statusCode = status;
+        res.setHeader("Content-Type", "text/plain; charset=utf-8");
+        res.end(message);
+    };
+    if (req.method !== "GET" && req.method !== "HEAD")
+        return fail(405, "A file is only read here.");
+    const hash = FILE_URL.exec(url)?.[1];
+    if (!hash)
+        return fail(400, "Not a file url: /file/ and the 32-character hex hash of a file.");
+    const accessToken = token();
+    if (!accessToken) {
+        return fail(503, `No OAuth2 token for EVERYSK_API_URL: ${lastError()?.message ?? "not there yet"}`);
+    }
+    try {
+        const file = await findFile(fetchApi, apiUrl, accessToken, hash);
+        if (!file) {
+            return fail(404, `No file has the url /file/${hash}, as the OAuth2 client EVERYSK_API_CLIENT_ID sees.`);
+        }
+        const content = contentOf(file, hash);
+        const disposition = `inline; filename*=UTF-8''${encodeURIComponent(file.name)}`;
+        res.setHeader("Content-Type", file.content_type || "application/octet-stream");
+        res.setHeader("Content-Length", content.length);
+        res.setHeader("Content-Disposition", disposition);
+        res.statusCode = 200;
+        res.end(req.method === "HEAD" ? undefined : content);
+    }
+    catch (error) {
+        fail(error instanceof FileRouteError ? error.status : 502, describeError(error));
+    }
+};
+/**
+ * serveDevFilesPlugin
+ *
+ * Mounts `createDevFileRoute` on the dev server and on `vite preview`, neither of which has the
+ * platform's `/file/` route, logging through Vite's own logger.
+ *
+ * @param {ApiTokenSource} [tokens] - The token to send; created when the server starts if
+ *   omitted. `defineAppConfig` passes the one it shares with the `/api` proxy.
+ */
+export function serveDevFilesPlugin(tokens) {
+    const route = (log) => createDevFileRoute({ ...(tokens ?? createApiTokenSource()), log });
+    return {
+        name: "serve-dev-files",
+        configureServer(server) {
+            server.middlewares.use(route((message) => server.config.logger.warn(message)));
+        },
+        configurePreviewServer(server) {
+            server.middlewares.use(route((message) => server.config.logger.warn(message)));
+        },
+    };
+}
+//# sourceMappingURL=serveDevFiles.js.map

package/dist/vite/plugins/serveDevFiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serveDevFiles.js","sourceRoot":"","sources":["../../../src/vite/plugins/serveDevFiles.ts"],"names":[],"mappings":"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"}

package/dist/vite/serverProxy.d.ts

@@ -1,16 +1,16 @@
 import type { ProxyOptions } from "vite";
+import { type ApiTokenSource } from "./apiToken.js";
 /**
  * createDevServerProxy — Vite dev proxy for `/api`, authenticated with OAuth2 client credentials.
  *
  * Forwards `/api/*` to `EVERYSK_API_URL` (stripping the `/api` prefix) and injects an
- * `Authorization: Bearer <access_token>` header. The token is obtained from
- * `${EVERYSK_API_URL}/oauth2/token` with the `client_credentials` grant, cached in memory, and
- * refreshed in the background shortly before it expires. It is fetched eagerly at startup so a
- * token is ready before the first API call.
+ * `Authorization: Bearer <access_token>` header, from `createApiTokenSource`.
  *
+ * @param {ApiTokenSource} [tokens] - The token to send; a new source when omitted. The preset
+ *   passes the one it shares with the `/file/` route.
  * @returns {Record<string, string | ProxyOptions>} The Vite `server.proxy` config for `/api`.
- * @throws {Error} If `EVERYSK_API_URL`, `EVERYSK_API_CLIENT_ID`, or `EVERYSK_API_CLIENT_SECRET`
- *   is missing.
+ * @throws {Error} If `tokens` is omitted and `EVERYSK_API_URL`, `EVERYSK_API_CLIENT_ID`, or
+ *   `EVERYSK_API_CLIENT_SECRET` is missing.
  */
-export declare function createDevServerProxy(): Record<string, string | ProxyOptions>;
+export declare function createDevServerProxy(tokens?: ApiTokenSource): Record<string, string | ProxyOptions>;
 //# sourceMappingURL=serverProxy.d.ts.map

package/dist/vite/serverProxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serverProxy.d.ts","sourceRoot":"","sources":["../../src/vite/serverProxy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAMzC;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAAC,CAoE5E"}
+{"version":3,"file":"serverProxy.d.ts","sourceRoot":"","sources":["../../src/vite/serverProxy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAEzC,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAE1E;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAChC,MAAM,GAAE,cAAuC,GAChD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAAC,CAqBvC"}

package/dist/vite/serverProxy.js

@@ -1,68 +1,20 @@
-// Refresh the OAuth2 token this many ms before it actually expires, so an in-flight
-// request never races a just-expired token.
-const REFRESH_SKEW_MS = 60_000;
+import { createApiTokenSource } from "./apiToken.js";
 /**
  * createDevServerProxy — Vite dev proxy for `/api`, authenticated with OAuth2 client credentials.
  *
  * Forwards `/api/*` to `EVERYSK_API_URL` (stripping the `/api` prefix) and injects an
- * `Authorization: Bearer <access_token>` header. The token is obtained from
- * `${EVERYSK_API_URL}/oauth2/token` with the `client_credentials` grant, cached in memory, and
- * refreshed in the background shortly before it expires. It is fetched eagerly at startup so a
- * token is ready before the first API call.
+ * `Authorization: Bearer <access_token>` header, from `createApiTokenSource`.
  *
+ * @param {ApiTokenSource} [tokens] - The token to send; a new source when omitted. The preset
+ *   passes the one it shares with the `/file/` route.
  * @returns {Record<string, string | ProxyOptions>} The Vite `server.proxy` config for `/api`.
- * @throws {Error} If `EVERYSK_API_URL`, `EVERYSK_API_CLIENT_ID`, or `EVERYSK_API_CLIENT_SECRET`
- *   is missing.
+ * @throws {Error} If `tokens` is omitted and `EVERYSK_API_URL`, `EVERYSK_API_CLIENT_ID`, or
+ *   `EVERYSK_API_CLIENT_SECRET` is missing.
  */
-export function createDevServerProxy() {
-    const EVERYSK_API_URL = process.env.EVERYSK_API_URL;
-    if (!EVERYSK_API_URL)
-        throw new Error("EVERYSK_API_URL must be set.");
-    const clientId = process.env.EVERYSK_API_CLIENT_ID;
-    const clientSecret = process.env.EVERYSK_API_CLIENT_SECRET;
-    if (!clientId || !clientSecret) {
-        throw new Error("EVERYSK_API_CLIENT_ID and EVERYSK_API_CLIENT_SECRET must be set (OAuth2 client credentials).");
-    }
-    // Captured into an object so the narrowed `string` type survives inside the async closure below.
-    const credentials = { clientId, clientSecret };
-    const tokenUrl = `${EVERYSK_API_URL.replace(/\/$/, "")}/oauth2/token`;
-    let accessToken = null;
-    let refreshTimer = null;
-    /**
-     * refreshToken — fetch a fresh access token and schedule the next refresh before it expires.
-     *
-     * @returns {Promise<void>} Resolves once `accessToken` is updated.
-     * @throws {Error} If the token request fails or returns no `access_token`.
-     */
-    async function refreshToken() {
-        const res = await fetch(tokenUrl, {
-            method: "POST",
-            headers: { "Content-Type": "application/x-www-form-urlencoded" },
-            body: new URLSearchParams({
-                grant_type: "client_credentials",
-                client_id: credentials.clientId,
-                client_secret: credentials.clientSecret,
-            }),
-        });
-        if (!res.ok)
-            throw new Error(`OAuth2 token request failed: ${res.status} ${res.statusText}`);
-        const data = (await res.json());
-        if (!data.access_token)
-            throw new Error("OAuth2 token response had no access_token.");
-        accessToken = data.access_token;
-        const ttlMs = (data.expires_in ?? 3600) * 1000;
-        if (refreshTimer)
-            clearTimeout(refreshTimer);
-        refreshTimer = setTimeout(() => {
-            void refreshToken().catch((error) => console.error("[dev proxy] OAuth2 token refresh failed:", error));
-        }, Math.max(ttlMs - REFRESH_SKEW_MS, 30_000));
-        refreshTimer.unref?.();
-    }
-    // Warm the token before the first request; a failure is logged, not fatal (the request will 401).
-    void refreshToken().catch((error) => console.error("[dev proxy] initial OAuth2 token fetch failed:", error));
+export function createDevServerProxy(tokens = createApiTokenSource()) {
     return {
         "/api": {
-            target: EVERYSK_API_URL,
+            target: tokens.apiUrl,
             changeOrigin: true,
             xfwd: true,
             rewrite: (p) => p.replace(/^\/api(?=\/|$)/, ""),
@@ -70,6 +22,7 @@ export function createDevServerProxy() {
                 proxy.on("proxyReq", (proxyReq) => {
                     proxyReq.removeHeader("origin");
                     proxyReq.removeHeader("referer");
+                    const accessToken = tokens.token();
                     if (accessToken) {
                         proxyReq.setHeader("Authorization", `Bearer ${accessToken}`);
                     }

package/dist/vite/serverProxy.js.map

@@ -1 +1 @@
-{"version":3,"file":"serverProxy.js","sourceRoot":"","sources":["../../src/vite/serverProxy.ts"],"names":[],"mappings":"AAEA,oFAAoF;AACpF,4CAA4C;AAC5C,MAAM,eAAe,GAAG,MAAM,CAAC;AAE/B;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IACpD,IAAI,CAAC,eAAe;QAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAEtE,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC;IACnD,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC;IAC3D,IAAI,CAAC,QAAQ,IAAI,CAAC,YAAY,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,8FAA8F,CAAC,CAAC;IAClH,CAAC;IACD,iGAAiG;IACjG,MAAM,WAAW,GAAG,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC;IAE/C,MAAM,QAAQ,GAAG,GAAG,eAAe,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,eAAe,CAAC;IACtE,IAAI,WAAW,GAAkB,IAAI,CAAC;IACtC,IAAI,YAAY,GAAyC,IAAI,CAAC;IAE9D;;;;;OAKG;IACH,KAAK,UAAU,YAAY;QACzB,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE;YAChC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,mCAAmC,EAAE;YAChE,IAAI,EAAE,IAAI,eAAe,CAAC;gBACxB,UAAU,EAAE,oBAAoB;gBAChC,SAAS,EAAE,WAAW,CAAC,QAAQ;gBAC/B,aAAa,EAAE,WAAW,CAAC,YAAY;aACxC,CAAC;SACH,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC;QAE7F,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAmD,CAAC;QAClF,IAAI,CAAC,IAAI,CAAC,YAAY;YAAE,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;QACtF,WAAW,GAAG,IAAI,CAAC,YAAY,CAAC;QAEhC,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC;QAC/C,IAAI,YAAY;YAAE,YAAY,CAAC,YAAY,CAAC,CAAC;QAC7C,YAAY,GAAG,UAAU,CAAC,GAAG,EAAE;YAC7B,KAAK,YAAY,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,0CAA0C,EAAE,KAAK,CAAC,CAAC,CAAC;QACzG,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,eAAe,EAAE,MAAM,CAAC,CAAC,CAAC;QAC9C,YAAY,CAAC,KAAK,EAAE,EAAE,CAAC;IACzB,CAAC;IAED,kGAAkG;IAClG,KAAK,YAAY,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,gDAAgD,EAAE,KAAK,CAAC,CAAC,CAAC;IAE7G,OAAO;QACL,MAAM,EAAE;YACN,MAAM,EAAE,eAAe;YACvB,YAAY,EAAE,IAAI;YAClB,IAAI,EAAE,IAAI;YACV,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC;YAE/C,SAAS,EAAE,CAAC,KAAK,EAAE,EAAE;gBACnB,KAAK,CAAC,EAAE,CAAC,UAAU,EAAE,CAAC,QAAQ,EAAE,EAAE;oBAChC,QAAQ,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;oBAChC,QAAQ,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;oBAEjC,IAAI,WAAW,EAAE,CAAC;wBAChB,QAAQ,CAAC,SAAS,CAAC,eAAe,EAAE,UAAU,WAAW,EAAE,CAAC,CAAC;oBAC/D,CAAC;gBACH,CAAC,CAAC,CAAC;YACL,CAAC;SACF;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"serverProxy.js","sourceRoot":"","sources":["../../src/vite/serverProxy.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,oBAAoB,EAAuB,MAAM,eAAe,CAAC;AAE1E;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAChC,SAAyB,oBAAoB,EAAE;IAE/C,OAAO;QACH,MAAM,EAAE;YACJ,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,YAAY,EAAE,IAAI;YAClB,IAAI,EAAE,IAAI;YACV,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC;YAE/C,SAAS,EAAE,CAAC,KAAK,EAAE,EAAE;gBACjB,KAAK,CAAC,EAAE,CAAC,UAAU,EAAE,CAAC,QAAQ,EAAE,EAAE;oBAC9B,QAAQ,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;oBAChC,QAAQ,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;oBAEjC,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC;oBACnC,IAAI,WAAW,EAAE,CAAC;wBACd,QAAQ,CAAC,SAAS,CAAC,eAAe,EAAE,UAAU,WAAW,EAAE,CAAC,CAAC;oBACjE,CAAC;gBACL,CAAC,CAAC,CAAC;YACP,CAAC;SACJ;KACJ,CAAC;AACN,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everysk/apps-devkit",
-  "version": "0.1.0",
+  "version": "0.3.0-beta-20261016180126",
   "description": "Build-time presets for Everysk client applications: Vite, ESLint, Vitest, TypeScript and Prettier.",
   "keywords": [
     "everysk",
@@ -55,15 +55,13 @@
   },
   "dependencies": {
     "@babel/core": "^7.29.7",
-    "@eslint/js": "^9.39.4",
+    "@eslint/js": "^10.0.1",
     "@rolldown/plugin-babel": "^0.2.3",
     "@tailwindcss/vite": "^4.3.0",
     "@vitejs/plugin-react": "^6.0.2",
-    "@vitest/coverage-v8": "^4.1.8",
+    "@vitest/coverage-v8": "^5.0.1",
     "babel-plugin-react-compiler": "^1.0.0",
-    "eslint": "^9.39.4",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-prettier": "^5.5.6",
+    "eslint": "^10.10.0",
     "eslint-plugin-react-hooks": "^7.1.1",
     "eslint-plugin-react-refresh": "^0.5.2",
     "globals": "^17.6.0",
@@ -73,7 +71,7 @@
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.60.1",
     "vite": "^8.0.16",
-    "vitest": "^4.1.8"
+    "vitest": "^5.0.1"
   },
   "devDependencies": {
     "@types/babel__core": "^7.20.5",
@@ -84,7 +82,7 @@
   },
   "sideEffects": false,
   "engines": {
-    "node": ">=22",
+    "node": "^22.13.0 || >=24",
     "npm": ">=12"
   }
 }

package/src/eslint/index.ts

@@ -22,6 +22,17 @@ const noBarrelPaths = [
 const dataLayerMessage =
     "Data access only via entity hooks (@everysk/apps-sdk/<entity> or @/hooks/...). Pages and components must not call axios or an api module directly.";
 
+export type EveryskConfigOptions = {
+    /**
+     * The app's directory, `import.meta.dirname` in its `eslint.config.js`. An editor lints a
+     * repository of several apps in one ESLint process, where typescript-eslint refuses to pick
+     * among their tsconfigs; only the app's own config knows which directory is its root.
+     */
+    tsconfigRootDir?: string;
+    /** Appended after the preset, so an app can add or override rules for its own files. */
+    extra?: ReturnType<typeof defineConfig>;
+};
+
 /**
  * everyskConfig
  *
@@ -29,18 +40,23 @@ const dataLayerMessage =
  *
  * ```js
  * import { everyskConfig } from "@everysk/apps-devkit/eslint";
- * export default everyskConfig();
+ * export default everyskConfig({ tsconfigRootDir: import.meta.dirname });
  * ```
  *
  * It encodes the conventions that lint can actually check: no MUI barrel imports, and no
  * direct data access from pages or components. The rules that lint cannot express — which
  * subpath to import, which provider to wire — belong to the `everysk-apps` generator.
  *
- * @param {ReturnType<typeof defineConfig>} [extra] - Appended after the preset, so an app can
- *   add or override rules for its own files.
+ * Takes the options, or the app's own blocks alone, as it did before there were options.
  */
-export const everyskConfig = (extra: ReturnType<typeof defineConfig> = []) =>
-    defineConfig([
+export const everyskConfig = (
+    optionsOrExtra: EveryskConfigOptions | ReturnType<typeof defineConfig> = {},
+) => {
+    const { tsconfigRootDir, extra = [] } = Array.isArray(optionsOrExtra)
+        ? { extra: optionsOrExtra }
+        : optionsOrExtra;
+
+    return defineConfig([
         globalIgnores(["dist", "coverage"]),
         {
             files: ["**/*.{ts,tsx}"],
@@ -53,6 +69,7 @@ export const everyskConfig = (extra: ReturnType<typeof defineConfig> = []) =>
             languageOptions: {
                 ecmaVersion: 2020,
                 globals: globals.browser,
+                ...(tsconfigRootDir ? { parserOptions: { tsconfigRootDir } } : {}),
             },
             rules: {
                 "@typescript-eslint/no-restricted-imports": ["error", { paths: noBarrelPaths }],
@@ -88,3 +105,4 @@ export const everyskConfig = (extra: ReturnType<typeof defineConfig> = []) =>
         },
         ...extra,
     ]);
+};

package/src/vite/apiToken.ts

@@ -0,0 +1,107 @@
+/** How long before a token expires it is renewed, so a request in flight never meets an expired one. */
+const REFRESH_SKEW_MS = 60_000;
+
+/** The first wait after a failed token request; it doubles on each failure, up to the maximum. */
+const FIRST_RETRY_MS = 5_000;
+const MAX_RETRY_MS = 60_000;
+
+/** The API the dev server talks to, and the token it talks to it with. */
+export type ApiTokenSource = {
+    /** `EVERYSK_API_URL`, without a trailing slash, so a path can be appended as is. */
+    apiUrl: string;
+    /** The current access token; `null` until one arrives, and once it has expired. */
+    token: () => string | null;
+    /** Why there is no token: the last failed request, until one succeeds. */
+    lastError: () => Error | null;
+};
+
+/**
+ * createApiTokenSource
+ *
+ * An OAuth2 access token for `EVERYSK_API_URL`, from the `client_credentials` grant at
+ * `${EVERYSK_API_URL}/oauth2/token`, cached in memory and renewed in the background a minute
+ * before it expires. It is fetched at once, so a token is ready before the first request. A
+ * failed request is logged and tried again, waiting 5 seconds and doubling up to a minute, so a
+ * VPN or API that comes back later does not need a restart of the dev server; until then the
+ * `/api` proxy sends no token (the API answers 401) and the `/file/` route says why, from
+ * `lastError`. `defineAppConfig` creates one source and hands it to both, so the dev server asks
+ * for one token, not one per use.
+ *
+ * @returns {ApiTokenSource} The API URL, the current token, and the last failure.
+ * @throws {Error} If `EVERYSK_API_URL`, `EVERYSK_API_CLIENT_ID`, or `EVERYSK_API_CLIENT_SECRET`
+ *   is missing.
+ */
+export function createApiTokenSource(): ApiTokenSource {
+    const apiUrl = process.env.EVERYSK_API_URL?.replace(/\/$/, "");
+    if (!apiUrl) throw new Error("EVERYSK_API_URL must be set.");
+
+    const clientId = process.env.EVERYSK_API_CLIENT_ID;
+    const clientSecret = process.env.EVERYSK_API_CLIENT_SECRET;
+    if (!clientId || !clientSecret) {
+        throw new Error(
+            "EVERYSK_API_CLIENT_ID and EVERYSK_API_CLIENT_SECRET must be set (OAuth2 client credentials).",
+        );
+    }
+    const credentials = { clientId, clientSecret };
+
+    const tokenUrl = `${apiUrl}/oauth2/token`;
+    let accessToken: string | null = null;
+    let expiresAt = 0;
+    let lastError: Error | null = null;
+    let retryMs = FIRST_RETRY_MS;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
+    const schedule = (delayMs: number) => {
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(() => void refreshToken(), delayMs);
+        timer.unref?.();
+    };
+
+    /** Asks for a token, then schedules the next request: a renewal on success, a retry on failure. */
+    async function requestToken(): Promise<number> {
+        const res = await fetch(tokenUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: "client_credentials",
+                client_id: credentials.clientId,
+                client_secret: credentials.clientSecret,
+            }),
+        });
+        if (!res.ok)
+            throw new Error(`OAuth2 token request failed: ${res.status} ${res.statusText}`);
+
+        const data = (await res.json()) as { access_token?: string; expires_in?: number };
+        if (!data.access_token) throw new Error("OAuth2 token response had no access_token.");
+
+        const ttlMs = (data.expires_in ?? 3600) * 1000;
+        accessToken = data.access_token;
+        expiresAt = Date.now() + ttlMs;
+        return ttlMs;
+    }
+
+    async function refreshToken(): Promise<void> {
+        try {
+            const ttlMs = await requestToken();
+            lastError = null;
+            retryMs = FIRST_RETRY_MS;
+            schedule(Math.max(ttlMs - REFRESH_SKEW_MS, 30_000));
+        } catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            console.error(
+                `[dev server] OAuth2 token request failed; trying again in ${retryMs / 1000}s:`,
+                lastError,
+            );
+            schedule(retryMs);
+            retryMs = Math.min(retryMs * 2, MAX_RETRY_MS);
+        }
+    }
+
+    void refreshToken();
+
+    return {
+        apiUrl,
+        token: () => (accessToken && Date.now() < expiresAt ? accessToken : null),
+        lastError: () => lastError,
+    };
+}

package/src/vite/index.ts

@@ -6,13 +6,17 @@ import react, { reactCompilerPreset } from "@vitejs/plugin-react";
 import babel from "@rolldown/plugin-babel";
 import tailwindcss from "@tailwindcss/vite";
 
+import { createApiTokenSource } from "./apiToken.js";
 import { createDevServerProxy } from "./serverProxy.js";
 import { envVarsLocationPlugin } from "./plugins/envVarsLocation.js";
 import { serveDevAppConfigPlugin } from "./plugins/serveDevAppConfig.js";
+import { serveDevFilesPlugin } from "./plugins/serveDevFiles.js";
 
+export { createApiTokenSource, type ApiTokenSource } from "./apiToken.js";
 export { createDevServerProxy } from "./serverProxy.js";
 export { envVarsLocationPlugin } from "./plugins/envVarsLocation.js";
 export { serveDevAppConfigPlugin } from "./plugins/serveDevAppConfig.js";
+export { serveDevFilesPlugin } from "./plugins/serveDevFiles.js";
 
 /**
  * defineAppConfig
@@ -34,6 +38,8 @@ export { serveDevAppConfigPlugin } from "./plugins/serveDevAppConfig.js";
  *   authenticates against `EVERYSK_API_URL` using OAuth2 client credentials.
  * - React with the compiler preset, Tailwind, and the two plugins that carry the app's
  *   `config.json` `env_vars` into the page — a meta tag in build, `/app-config.json` in dev.
+ * - The platform's `/file/<hash>` route, on the dev server and `vite preview`, so a file's own
+ *   `url` shows it there too. It shares the `/api` proxy's OAuth2 token.
  *
  * @param {UserConfig} [overrides] - Merged over the preset with Vite's own `mergeConfig`, so
  *   arrays (plugins, aliases) are concatenated rather than replaced.
@@ -47,6 +53,8 @@ export const defineAppConfig = (overrides: UserConfig = {}) =>
         const env = loadEnv(mode, root, "");
         Object.assign(process.env, env);
 
+        const tokens = command === "serve" ? createApiTokenSource() : undefined;
+
         const preset: UserConfig = {
             base: "./",
             envDir: root,
@@ -66,7 +74,7 @@ export const defineAppConfig = (overrides: UserConfig = {}) =>
                 host: true,
                 port: Number(process.env.PORT) || 5173,
                 strictPort: true,
-                proxy: command === "serve" ? createDevServerProxy() : undefined,
+                proxy: tokens ? createDevServerProxy(tokens) : undefined,
             },
 
             plugins: [
@@ -75,6 +83,7 @@ export const defineAppConfig = (overrides: UserConfig = {}) =>
                 tailwindcss(),
                 envVarsLocationPlugin(),
                 serveDevAppConfigPlugin(),
+                serveDevFilesPlugin(tokens),
             ],
         };
 

package/src/vite/plugins/envVarsLocation.ts

@@ -1,11 +1,11 @@
 import type { Plugin } from "vite";
 
 export function envVarsLocationPlugin(): Plugin {
-  return {
-    name: "env_vars_location",
-    apply: "build",
-    transformIndexHtml() {
-      return [{ tag: "meta", attrs: { name: "app-config" }, injectTo: "head" }];
-    },
-  };
+    return {
+        name: "env_vars_location",
+        apply: "build",
+        transformIndexHtml() {
+            return [{ tag: "meta", attrs: { name: "app-config" }, injectTo: "head" }];
+        },
+    };
 }

package/src/vite/plugins/serveDevAppConfig.ts

@@ -16,36 +16,36 @@ import type { Plugin } from "vite";
  * on change — a full reload re-runs the bootstrap fetch, picking up edits to `env_vars` live.
  */
 export function serveDevAppConfigPlugin(): Plugin {
-  return {
-    name: "serve-dev-app-config",
-    apply: "serve",
-    configureServer(server) {
-      // apps/<name>/config.json — one level up from the Vite root (the app's project/ dir).
-      const configPath = path.resolve(process.cwd(), "..", "config.json");
+    return {
+        name: "serve-dev-app-config",
+        apply: "serve",
+        configureServer(server) {
+            // apps/<name>/config.json — one level up from the Vite root (the app's project/ dir).
+            const configPath = path.resolve(process.cwd(), "..", "config.json");
 
-      server.middlewares.use(async (req, res, next) => {
-        if (req.url !== "/app-config.json") return next();
+            server.middlewares.use(async (req, res, next) => {
+                if (req.url !== "/app-config.json") return next();
 
-        try {
-          const content = await fs.readFile(configPath, "utf-8");
-          const envVars = (JSON.parse(content).env_vars ?? {}) as Record<string, unknown>;
+                try {
+                    const content = await fs.readFile(configPath, "utf-8");
+                    const envVars = (JSON.parse(content).env_vars ?? {}) as Record<string, unknown>;
 
-          res.setHeader("Content-Type", "application/json; charset=utf-8");
-          res.statusCode = 200;
-          res.end(JSON.stringify(envVars));
-        } catch {
-          res.statusCode = 404;
-          res.end();
-        }
-      });
+                    res.setHeader("Content-Type", "application/json; charset=utf-8");
+                    res.statusCode = 200;
+                    res.end(JSON.stringify(envVars));
+                } catch {
+                    res.statusCode = 404;
+                    res.end();
+                }
+            });
 
-      // config.json is outside the Vite root, so watch it explicitly and full-reload on change.
-      server.watcher.add(configPath);
-      server.watcher.on("change", (file) => {
-        if (path.resolve(file) === configPath) {
-          server.hot.send({ type: "full-reload" });
-        }
-      });
-    },
-  };
+            // config.json is outside the Vite root, so watch it explicitly and full-reload on change.
+            server.watcher.add(configPath);
+            server.watcher.on("change", (file) => {
+                if (path.resolve(file) === configPath) {
+                    server.hot.send({ type: "full-reload" });
+                }
+            });
+        },
+    };
 }