@antelopejs/dms-frontend 0.2.0 → 0.2.2

package/README.md

@@ -163,11 +163,13 @@ started by `dev`, and the production server started by `start`, because those
 child processes inherit the environment. A missing file is not an error; an
 unreadable one is reported and skipped.
 
-`DMS_SESSION_SECRET` is mandatory for anything that touches a session. The
-generated server encrypts its session cookie with it, and with no value — or
-one shorter than 32 characters — the login page at `/auth` fails the first
-sign-in attempt rather than starting degraded. Generate one with
-`openssl rand -hex 32`.
+`ajs dms dev` generates a fresh ephemeral 32-byte secret when
+`DMS_SESSION_SECRET` is absent; all sessions are invalidated when that dev
+server restarts. An explicit value is preserved, but empty or shorter than 32
+characters is rejected. `build` and `start` require a configured secret and
+never generate one, which is required for production so sessions survive
+restarts. The generated server also validates the value as a safety net.
+Generate one with `openssl rand -hex 32`.
 
 ### Opening a session from a module flow
 

package/dist/commands/build.js

@@ -21,6 +21,7 @@ function cmdBuild() {
             (0, cli_ui_1.error)("Backend URL is required. Use -b <url> or set DMS_API_BASE_URL.");
             process.exit(1);
         }
+        const sessionSecret = (0, common_1.resolveSessionSecret)("build");
         const spinner = new cli_ui_1.Spinner("Setting up workspace...");
         await spinner.start();
         try {
@@ -44,6 +45,7 @@ function cmdBuild() {
                 cwd: workspaceDir,
                 env: {
                     ...process.env,
+                    DMS_SESSION_SECRET: sessionSecret,
                     NODE_OPTIONS: "--max-old-space-size=4096",
                     NODE_PATH: nodeModulesDir,
                 },

package/dist/commands/dev.js

@@ -44,6 +44,7 @@ function cmdDev() {
         .action(async (options) => {
         const { backendUrl, workspaceKey } = resolveBackend(options);
         const bootstrapSecret = (0, common_1.resolveBootstrapSecret)(options.bootstrapSecret, backendUrl);
+        const sessionSecret = (0, common_1.resolveSessionSecret)("dev");
         const requestedPort = Number.parseInt(options.port, 10);
         if (Number.isNaN(requestedPort)) {
             (0, cli_ui_1.error)(`Invalid port: ${options.port}`);
@@ -101,6 +102,7 @@ function cmdDev() {
                     DMS_COOKIE_SECURE: process.env.DMS_COOKIE_SECURE ?? "false",
                     DMS_API_BASE_URL: backendUrl,
                     DMS_BOOTSTRAP_SECRET: bootstrapSecret,
+                    DMS_SESSION_SECRET: sessionSecret,
                     NODE_OPTIONS: "--max-old-space-size=4096",
                     NODE_PATH: nodeModulesDir,
                 },

package/dist/commands/start.js

@@ -20,6 +20,7 @@ function cmdStart() {
             (0, cli_ui_1.error)("Backend URL is required. Use -b <url> or set DMS_API_BASE_URL.");
             process.exit(1);
         }
+        const sessionSecret = (0, common_1.resolveSessionSecret)("start");
         const workspaceDir = (0, common_1.getWorkspaceDir)(options.backendUrl);
         const serverPath = (0, node_path_1.join)(workspaceDir, "server.mjs");
         const clientPath = (0, node_path_1.join)(workspaceDir, "dist", "client", "index.html");
@@ -41,6 +42,7 @@ function cmdStart() {
                 ...process.env,
                 PORT: options.port,
                 DMS_API_BASE_URL: options.backendUrl,
+                DMS_SESSION_SECRET: sessionSecret,
                 DMS_COOKIE_SECURE: process.env.DMS_COOKIE_SECURE ?? "true",
             },
         });

package/dist/config.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Options = exports.TAILWIND_SOURCE_GLOB = exports.PNPM_LIFECYCLE_SCRIPTS = exports.layerCopyIgnore = exports.LAYER_COPY_BLOCKLIST = exports.AUTH_ESTABLISH_FILE = exports.FRONTEND_MODULE_ENTRY = exports.LAYERS_SUBDIR = exports.TEMPLATE_FILES = exports.WORKSPACE_DIR_MODE = exports.DEPS_HASH_FILE = exports.DMS_FRONTEND_HOME = void 0;
 exports.writeSecretBearingFile = writeSecretBearingFile;
 exports.normalizeBootstrapSecret = normalizeBootstrapSecret;
+exports.resolveSessionSecret = resolveSessionSecret;
 exports.resolveBootstrapSecret = resolveBootstrapSecret;
 exports.sha256Hex = sha256Hex;
 exports.canonicalizeBackendUrl = canonicalizeBackendUrl;
@@ -38,6 +39,7 @@ exports.TEMPLATE_FILES = [
     ["frontend-module.ts", "frontend-module.ts"],
     ["globals.d.ts", "globals.d.ts"],
     ["compress-assets.mjs", "compress-assets.mjs"],
+    ["head-order.mjs", "head-order.mjs"],
     ["email-renderer.ts", "email-renderer.ts"],
     ["email-runtime.ts", "email-runtime.ts"],
     ["email-locales.ts", "email-locales.ts"],
@@ -109,6 +111,18 @@ function normalizeBootstrapSecret(value, source = DEFAULT_CREDENTIAL_SOURCE) {
     }
     return trimmed;
 }
+function resolveSessionSecret(mode, value = process.env.DMS_SESSION_SECRET) {
+    if (value === undefined && mode === "dev") {
+        return (0, node_crypto_1.randomBytes)(32).toString("hex");
+    }
+    if (value === undefined || value.length < 32) {
+        throw new Error("DMS_SESSION_SECRET must contain at least 32 characters; " +
+            (mode === "dev"
+                ? "set it explicitly or omit it to generate an ephemeral dev secret"
+                : "set it explicitly for build and start"));
+    }
+    return value;
+}
 function resolveBootstrapSecret(explicit, backendUrl, options = {}) {
     const normalized = normalizeBootstrapSecret(explicit);
     if (normalized)

package/dist/index.js

@@ -38,6 +38,9 @@ Environment:
   the other variables below can live in the project's .env. A variable already
   set in the environment always wins over a file, and .env.local wins over .env.
   The generated workspace never loads a .env of its own.
+  'dev' generates an ephemeral 32-byte DMS_SESSION_SECRET when it is absent;
+  restarting dev invalidates its sessions. 'build' and 'start' require a
+  configured secret of at least 32 characters.
 
 Workspaces:
   Each canonical backend URL gets its own workspace under

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-frontend",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Frontend-agnostic loader for AntelopeJS DMS, shipping the Vue 3 renderer (Vite, Inertia, SSR)",
   "keywords": [
     "antelope",

package/templates/vue/head-order.mjs

@@ -0,0 +1,39 @@
+// Restoring "paint before hydrate" in the built document.
+//
+// The source index.html marks the entry script `fetchpriority="low"` so the
+// browser spends its bandwidth on the render-blocking stylesheet first. Vite
+// rewrites that script tag when it builds and drops the attribute, and it emits
+// the script *before* the stylesheet — so the production document did the
+// opposite of what the template asked: it discovered a 250 kB hydration bundle
+// first and let it compete with the 27 kB the first paint actually waits on,
+// over the plain HTTP/1.1 the generated server speaks.
+//
+// Kept beside vite.config.ts rather than inside it so the transform can be
+// exercised on its own, the way client-manifest.mjs is.
+
+const SCRIPT = /<script[^>]*\stype="module"[^>]*><\/script>/;
+const STYLESHEET = /[ \t]*<link rel="stylesheet"[^>]*>\n?/;
+
+function deprioritize(html) {
+  return html.replace(SCRIPT, (tag) =>
+    tag.includes("fetchpriority")
+      ? tag
+      : tag.replace("<script ", '<script fetchpriority="low" '),
+  );
+}
+
+/**
+ * Give the entry script back its low fetch priority and move the stylesheet
+ * ahead of it. A document that already has them in that order is returned
+ * unchanged, so the transform is safe to run twice.
+ */
+export function orderHeadForFirstPaint(html) {
+  const prioritized = deprioritize(html);
+  const stylesheet = prioritized.match(STYLESHEET);
+  const script = prioritized.match(SCRIPT);
+  if (!stylesheet || !script || stylesheet.index < script.index)
+    return prioritized;
+  return prioritized
+    .replace(STYLESHEET, "")
+    .replace(SCRIPT, (tag) => `${stylesheet[0].trim()}\n    ${tag}`);
+}

package/templates/vue/main.ts

@@ -6,10 +6,47 @@ import { configureDmsApp, resolveDmsInertiaPage } from "./app-runtime";
 import { setupFrontendModules } from "./frontend-module";
 import { frontendModules } from "./frontend-modules.generated";
 
+const DEV_STYLE_ATTRIBUTE = "data-dms-dev-style";
+
+/**
+ * Hand each development stylesheet over to Vite.
+ *
+ * The development server puts the page's stylesheets in the document so it
+ * never paints unstyled (see `server/dev-styles.mjs`). Vite then injects its
+ * own copy of each one as a `<style data-vite-dev-id>`, and keeping both would
+ * make a later CSS edit look like it removed nothing: Vite rewrites its copy,
+ * ours keeps the deleted rules alive.
+ *
+ * We drop ours the moment Vite's appears, keyed by module id, rather than at a
+ * fixed point in the boot. A component reached through a dynamic import — most
+ * of them — has not been loaded when the app mounts, so removing its scoped
+ * rules then would flash exactly what this whole change exists to prevent.
+ */
+function adoptViteDevStyles(): void {
+  const pending = new Map<string, Element>();
+  for (const node of document.querySelectorAll(`[${DEV_STYLE_ATTRIBUTE}]`)) {
+    pending.set(node.getAttribute(DEV_STYLE_ATTRIBUTE) ?? "", node);
+  }
+  if (pending.size === 0) return;
+  const adopt = (): void => {
+    for (const style of document.querySelectorAll("style[data-vite-dev-id]")) {
+      const id = style.getAttribute("data-vite-dev-id") ?? "";
+      pending.get(id)?.remove();
+      pending.delete(id);
+    }
+    if (pending.size === 0) observer.disconnect();
+  };
+  const observer = new MutationObserver(adopt);
+  observer.observe(document.head, { childList: true });
+  adopt();
+}
+
 function markDmsReady(): void {
   document.documentElement.dataset.dmsReady = "true";
 }
 
+if (import.meta.env.DEV) adoptViteDevStyles();
+
 await setupFrontendModules(frontendModules);
 
 createInertiaApp({

package/templates/vue/server/dev-styles.mjs

@@ -0,0 +1,98 @@
+// Putting the page's stylesheets in the document the development server
+// returns, instead of letting the client entry inject them from JavaScript
+// once it has executed.
+//
+// Vite serves every stylesheet as a JavaScript module in development, so a
+// plain SSR document carries no styles at all and the browser paints raw HTML
+// until `/main.ts` and its module graph have run. Production has no such gap:
+// the built `index.html` already links the entry stylesheet, which is why this
+// module is development-only and lives beside client-manifest.mjs rather than
+// inside server.mjs, whose size the linter caps.
+//
+// Each tag carries the module id Vite will use for its own copy
+// (`data-vite-dev-id`), under our own attribute name. `main.ts` hands the
+// stylesheet over as soon as Vite injects that copy — see `adoptViteDevStyles`.
+// We deliberately do NOT reuse `data-vite-dev-id` itself: Vite's client adopts
+// any pre-existing link with that attribute and then skips `updateStyle` for
+// it, which would leave CSS edits stranded.
+
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { pageModulePreloads } from "./client-manifest.mjs";
+
+const PROJECT_ROOT = fileURLToPath(new URL("../", import.meta.url));
+const STYLE_ATTRIBUTE = "data-dms-dev-style";
+const SFC_STYLE = /[?&]vue&type=style/;
+const STYLE_EXTENSION =
+  /\.(?:css|less|pcss|postcss|sass|scss|styl|stylus)(?:$|\?)/;
+
+/**
+ * The workspace's generated entry stylesheet. `main.ts` is its only importer,
+ * so it never enters the SSR module graph, yet it carries Tailwind, Nuxt UI and
+ * one `@source` per materialized module — nearly every rule a page needs.
+ * Naming it is the one enumeration this module accepts, and the comment is the
+ * reason why.
+ */
+const ENTRY_STYLESHEET = "/dms-main.css";
+
+function ssrModuleGraph(devServer) {
+  return devServer.environments?.ssr?.moduleGraph ?? devServer.moduleGraph;
+}
+
+function directUrl(url) {
+  return `${url}${url.includes("?") ? "&" : "?"}direct`;
+}
+
+function styleModules(devServer) {
+  const graph = ssrModuleGraph(devServer);
+  if (!graph) return [];
+  return [...graph.urlToModuleMap.entries()]
+    .filter(([url]) => SFC_STYLE.test(url) || STYLE_EXTENSION.test(url))
+    .map(([url, module]) => ({ url, id: module?.id ?? url }));
+}
+
+function linkTag({ url, id }) {
+  return `<link rel="stylesheet" ${STYLE_ATTRIBUTE}="${id}" href="${directUrl(url)}">`;
+}
+
+/**
+ * A single-file component's `<style>` block is served with a JavaScript content
+ * type even when requested directly, so a browser would refuse it as a
+ * stylesheet. They are small; inline them instead. A block that could close its
+ * own tag is dropped rather than escaped — CSS has no escape that is valid in
+ * every position, and a scoped component rule is not worth the risk.
+ */
+async function inlineTag(devServer, { url, id }) {
+  const result = await devServer
+    .transformRequest(directUrl(url))
+    .catch(() => undefined);
+  const css = result?.code;
+  if (!css || /<\/style/i.test(css)) return "";
+  return `<style ${STYLE_ATTRIBUTE}="${id}">${css}</style>`;
+}
+
+/** Style tags for everything the development render touched, entry sheet first. */
+export async function developmentStyleTags(devServer) {
+  const modules = styleModules(devServer);
+  const links = [
+    { url: ENTRY_STYLESHEET, id: join(PROJECT_ROOT, "dms-main.css") },
+    ...modules.filter(({ url }) => !SFC_STYLE.test(url)),
+  ].map(linkTag);
+  const inlined = await Promise.all(
+    modules
+      .filter(({ url }) => SFC_STYLE.test(url))
+      .map((module) => inlineTag(devServer, module)),
+  );
+  return [...links, ...inlined].join("");
+}
+
+/**
+ * The style tags a document needs, whichever server is answering it: collected
+ * from the live module graph in development, read from the build manifest in
+ * production.
+ */
+export async function documentStyleTags(devServer, page, template) {
+  return devServer
+    ? developmentStyleTags(devServer)
+    : pageModulePreloads(page, template);
+}

package/templates/vue/server/homepage.mjs

@@ -0,0 +1,32 @@
+// Working out which page a visit to `/` means.
+//
+// The answer lives in the module registry the workspace was materialized with:
+// a module declares `homepage` somewhere in its options, at whatever depth its
+// own configuration shape puts it, and the highest-priority declaration wins —
+// the registry is already sorted. Read once at boot, because the registry is a
+// build artifact and cannot change while the server is up.
+//
+// Split out of server.mjs, whose size the linter caps.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PROJECT_ROOT = fileURLToPath(new URL("../", import.meta.url));
+const REGISTRY_PATH = join(PROJECT_ROOT, "generated-frontend-modules.json");
+const REGISTRY = existsSync(REGISTRY_PATH)
+  ? JSON.parse(readFileSync(REGISTRY_PATH, "utf8"))
+  : { modules: [] };
+
+function findHomepage(options) {
+  if (!options || typeof options !== "object") return undefined;
+  if (typeof options.homepage === "string") return options.homepage;
+  return Object.values(options)
+    .map(findHomepage)
+    .find((homepage) => homepage !== undefined);
+}
+
+export const HOMEPAGE =
+  REGISTRY.modules
+    .map((module) => findHomepage(module.options))
+    .find(Boolean) ?? "/";

package/templates/vue/server/inertia.mjs

@@ -7,6 +7,17 @@ const CLIENT_MANIFEST_PATH = fileURLToPath(
 );
 let productionAssetVersion;
 
+/**
+ * Every document and Inertia payload this server writes carries the visitor's
+ * own session: the user, the session, and the page tree their permissions
+ * allow. `private` is what keeps a shared cache from ever holding it;
+ * `no-cache` keeps the browser's own copy from being reused without asking us
+ * first, so a revoked session cannot resurface from disk. We stop short of
+ * `no-store`, which would additionally forfeit the back-forward cache on every
+ * page of a dashboard people navigate constantly.
+ */
+export const PRIVATE_CACHE_CONTROL = "private, no-cache";
+
 export function assetVersion() {
   if (process.env.DMS_DEV === "true" || !existsSync(CLIENT_MANIFEST_PATH))
     return "development";
@@ -32,6 +43,7 @@ export function createInertiaPage(url, props, version = assetVersion()) {
 
 export function inertiaHeaders(version = assetVersion()) {
   return {
+    "cache-control": PRIVATE_CACHE_CONTROL,
     "content-type": "application/json",
     "x-inertia": "true",
     vary: "X-Inertia",
@@ -39,6 +51,15 @@ export function inertiaHeaders(version = assetVersion()) {
   };
 }
 
+/** Headers for a rendered document: same cache stance as an Inertia payload. */
+export function htmlHeaders() {
+  return {
+    "cache-control": PRIVATE_CACHE_CONTROL,
+    "content-type": "text/html",
+    vary: "X-Inertia",
+  };
+}
+
 export function handleAssetVersionMismatch(request, response) {
   if (
     !request.headers["x-inertia"] ||

package/templates/vue/server.mjs

@@ -18,14 +18,14 @@ import {
   refreshSession,
 } from "./server/auth/routes.mjs";
 import { readSession } from "./server/auth/session.mjs";
-import {
-  pageModulePreloads,
-  productionHtmlTemplate,
-} from "./server/client-manifest.mjs";
+import { productionHtmlTemplate } from "./server/client-manifest.mjs";
+import { documentStyleTags } from "./server/dev-styles.mjs";
 import { handleEmailRender } from "./server/email.mjs";
+import { HOMEPAGE } from "./server/homepage.mjs";
 import { handleTester } from "./server/tester.mjs";
 import {
   createInertiaPage,
+  htmlHeaders,
   inertiaAppHtml,
   inertiaHeaders,
   redirectFrontendVisit,
@@ -36,13 +36,6 @@ export * from "./server/inertia.mjs";
 const INERTIA_HEADER = "x-inertia";
 const JSON_TYPE = "application/json";
 const PROJECT_ROOT = fileURLToPath(new URL(".", import.meta.url));
-const MODULE_REGISTRY_PATH = join(
-  PROJECT_ROOT,
-  "generated-frontend-modules.json",
-);
-const MODULE_REGISTRY = existsSync(MODULE_REGISTRY_PATH)
-  ? JSON.parse(readFileSync(MODULE_REGISTRY_PATH, "utf8"))
-  : { modules: [] };
 const MIME_TYPES = {
   ".css": "text/css",
   ".js": "text/javascript",
@@ -74,19 +67,6 @@ let vite;
 let vitePromise;
 let frontendHttpServer;
 
-function findHomepage(options) {
-  if (!options || typeof options !== "object") return undefined;
-  if (typeof options.homepage === "string") return options.homepage;
-  return Object.values(options)
-    .map(findHomepage)
-    .find((homepage) => homepage !== undefined);
-}
-
-const HOMEPAGE =
-  MODULE_REGISTRY.modules
-    .map((module) => findHomepage(module.options))
-    .find(Boolean) ?? "/";
-
 class BackendResponseError extends Error {
   constructor(status) {
     super(`DMS backend returned ${status}`);
@@ -358,7 +338,7 @@ export async function renderHtml(page, requestUrl, serverFetch) {
   }
   if (rendered.redirect)
     return { html: "", status: 200, redirect: rendered.redirect };
-  const preloads = devServer ? "" : pageModulePreloads(page, template);
+  const preloads = await documentStyleTags(devServer, page, template);
   const html = template
     .replace("<title>Antelope DMS</title>", rendered.head.headTags)
     .replace("<html", `<html ${rendered.head.htmlAttrs}`)
@@ -410,13 +390,7 @@ async function writeBackendError(error, request, response) {
       request.url,
       serverComponentFetch(request),
     );
-    return writeContent(
-      request,
-      response,
-      status,
-      { "content-type": "text/html", vary: "X-Inertia" },
-      html,
-    );
+    return writeContent(request, response, status, htmlHeaders(), html);
   }
   const payload =
     error instanceof UpstreamError || error instanceof RequestBodyError
@@ -481,7 +455,7 @@ export async function handleRequest(request, response) {
     request,
     response,
     rendered.status,
-    { "content-type": "text/html", vary: "X-Inertia" },
+    htmlHeaders(),
     rendered.html,
   );
 }

package/templates/vue/vite.config.ts

@@ -2,7 +2,8 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import ui from "@nuxt/ui/vite";
 import vue from "@vitejs/plugin-vue";
-import { defineConfig } from "vite";
+import { defineConfig, type Plugin } from "vite";
+import { orderHeadForFirstPaint } from "./head-order.mjs";
 
 interface FrontendModuleRegistryEntry {
   id: string;
@@ -66,6 +67,38 @@ const optimizedDependencies = [
   "json-schema-to-zod",
   "striptags",
 ];
+
+/**
+ * Entry points the dependency optimizer crawls at startup.
+ *
+ * Every materialized module brings its own dependency set — subpath exports and
+ * transitive CommonJS included — and none of it can be listed in
+ * `optimizedDependencies` by hand, because the modules are only known at
+ * materialization time. Leaving the crawl off and letting Vite discover them as
+ * pages load meant the first visit to a cold page re-ran the optimizer
+ * mid-request: the chunks already in flight answered 504 and the client was
+ * told to reload the whole document. Crawling the module sources once, at
+ * startup, pays that cost a single time and in a place where it reads as
+ * startup rather than as a crash.
+ */
+const optimizerEntries = [
+  resolve(__dirname, "main.ts"),
+  ...moduleRoots.map((root) => resolve(root, "dms.frontend.ts")),
+  ...frontendSourceRoots.flatMap((root) => [
+    resolve(root, "app/**/*.vue"),
+    resolve(root, "app/**/*.ts"),
+  ]),
+];
+
+function paintBeforeHydrate(): Plugin {
+  return {
+    name: "dms-paint-before-hydrate",
+    apply: "build",
+    enforce: "post",
+    transformIndexHtml: { order: "post", handler: orderHeadForFirstPaint },
+  };
+}
+
 const uiLinkImport = "@nuxt/ui/components/Link.vue";
 const uiInertiaLinkImport = resolve(
   __dirname,
@@ -131,6 +164,7 @@ export default defineConfig({
         vueTemplate: true,
       },
     }),
+    paintBeforeHydrate(),
   ],
   resolve: {
     dedupe: ["vue", "reka-ui", "@nuxt/ui"],
@@ -152,8 +186,7 @@ export default defineConfig({
   },
   optimizeDeps: {
     include: optimizedDependencies,
-    // Avoid crawling every module page at startup, but optimize dependencies as pages load.
-    entries: [],
+    entries: optimizerEntries,
   },
   ssr: { noExternal: ["@nuxt/icon", "@nuxt/ui"] },
   server: { strictPort: true, allowedHosts: [".onamp.dev"] },