@antelopejs/dms-frontend 0.9.0 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-frontend",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Frontend-agnostic loader for AntelopeJS DMS, shipping the Vue 3 renderer (Vite, Inertia, SSR)",
   "keywords": [
     "antelope",
@@ -60,17 +60,26 @@
   "scripts": {
     "build": "rimraf dist && tsc",
     "prepack": "pnpm run build",
-    "release": "pnpm run lint && pnpm run build && pnpm run test && release-it",
-    "test": "node --import tsx --test tests/*.test.ts tests/*.test.mts",
+    "release": "pnpm run lint && pnpm run format:check && pnpm run test && pnpm run test:cli && release-it",
+    "test": "node --import tsx --test 'tests/!(cli|cli-*).test.{ts,mts}'",
+    "test:cli": "pnpm run build && DMS_PREBUILT=1 node --import tsx --test tests/cli.test.ts 'tests/cli-*.test.{ts,mts}'",
     "test:real-source": "pnpm run build && node dist/verify-source-runner.js",
     "format": "oxfmt .",
-    "lint": "oxlint && oxfmt --check . && antelopejs-check-interface-ranges && pnpm run docs:reference:check",
+    "lint": "oxlint && antelopejs-check-interface-ranges && pnpm run docs:reference:check",
     "typecheck": "tsc --noEmit",
     "lint:fix": "oxlint --fix --max-warnings=1000000 && oxfmt .",
     "knip": "knip --dependencies",
     "knip:all": "knip",
     "docs:reference": "tsx scripts/docs-reference.ts",
-    "docs:reference:check": "tsx scripts/docs-reference.ts --check"
+    "docs:reference:check": "tsx scripts/docs-reference.ts --check",
+    "prepare": "if git rev-parse --is-inside-work-tree >/dev/null 2>&1 && command -v lefthook >/dev/null 2>&1; then lefthook install; fi",
+    "checks": "antelopejs-checks",
+    "size": "antelopejs-check-size",
+    "ratchet": "antelopejs-ratchet",
+    "sync": "antelopejs-sync",
+    "ratchet:update": "antelopejs-ratchet --update",
+    "sync:check": "antelopejs-sync --check",
+    "format:check": "oxfmt --check ."
   },
   "dependencies": {
     "@intlify/message-compiler": "^11.1.12",
@@ -81,7 +90,7 @@
   },
   "devDependencies": {
     "@antelopejs/core": "^1.16.0",
-    "@antelopejs/tooling-configs": ">=0.0.9 <1.0.0",
+    "@antelopejs/tooling-configs": "^0.2.0",
     "@iconify/utils": "^3.1.0",
     "@iconify/vue": "^5.0.1",
     "@inertiajs/vue3": "^3.7.1",
@@ -94,6 +103,7 @@
     "defu": "^6.1.4",
     "devalue": "^5.9.4",
     "knip": "^6.34.0",
+    "lefthook": "^2.2.2",
     "ofetch": "^1.5.1",
     "oxfmt": "^0.66.0",
     "oxlint": "1.81.0",

package/skills/dms-frontend/SKILL.md

@@ -29,6 +29,7 @@ tags: [frontend, cli, renderer, vue, inertia, ssr, deployment, dms-module]
 - The entry is `dms.frontend.ts`, default-exporting `{ componentPrefix?, setup(sdk) }`. `setup` only registers: under `dev` it runs again on every layer change.
 - Set a `componentPrefix`; the backend names a component by its full name (`CustomComponent("AcmeBanner")`). Replace another module's component with `registerComponent(fullName, c, { prefix: false })`.
 - Nothing is auto-imported unless `dms.frontend.build.ts` declares it; `app/build/` never is.
+- `dms.frontend.build.ts` can also add Vite plugins with `build.registerVitePlugins(() => [plugin])`, for dev, build and preview, after the renderer's own plugins.
 - Server routes, auth hooks, route rules and backend proxies go in `dms.server.ts` (`defineDmsServer` from `#dms/server`). It is trusted Node.js code: import what it uses, never `.vue` files or `dms.frontend.ts`.
 - The browser reaches the backend only through declared prefixes (`registerBackendProxy`, `backendProxies`, `DMS_BACKEND_PROXIES`). An undeclared backend route answers `404`; in development, the `x-dms-route-owner` header names who answered.
 - Declare `engines["@antelopejs/dms-frontend"]`, capped below the next minor (`">=0.6.0 <0.7.0"`); a range that excludes the installed loader stops `dev`, `build` and `verify-source`.

package/templates/vue/frontend-build-loader.ts

@@ -1,6 +1,9 @@
 import { isAbsolute, posix, resolve } from "node:path";
-import { normalizePath } from "vite";
-import type { DmsFrontendBuildSetup } from "./frontend-build.ts";
+import { normalizePath, type Plugin } from "vite";
+import type {
+  DmsFrontendBuild,
+  DmsFrontendBuildSetup,
+} from "./frontend-build.ts";
 
 /** A module's `dms.frontend.build.ts`, as the generated loader imports it. */
 export interface FrontendBuildDeclaration {
@@ -22,12 +25,31 @@ export interface AutoImportDirectory {
 /** A module's private code: never auto-imported, whatever it declares. */
 const PRIVATE_DIRECTORY = /(?:^|\/)app\/build(?:\/|$)/;
 
-function declaredDirectories(setup: DmsFrontendBuildSetup): string[] {
-  const directories: string[] = [];
+interface FrontendModuleName {
+  id: string;
+  name?: string;
+}
+
+type VitePluginFactory = Parameters<DmsFrontendBuild["registerVitePlugins"]>[0];
+
+interface DeclaredBuild {
+  directories: string[];
+  pluginFactories: VitePluginFactory[];
+}
+
+/** Each setup runs once, whichever declaration is read first. */
+const declarations = new WeakMap<DmsFrontendBuildSetup, DeclaredBuild>();
+
+function declared(setup: DmsFrontendBuildSetup): DeclaredBuild {
+  const known = declarations.get(setup);
+  if (known) return known;
+  const build: DeclaredBuild = { directories: [], pluginFactories: [] };
   setup({
-    registerAutoImports: (entries) => directories.push(...entries),
+    registerAutoImports: (entries) => build.directories.push(...entries),
+    registerVitePlugins: (create) => build.pluginFactories.push(create),
   });
-  return directories;
+  declarations.set(setup, build);
+  return build;
 }
 
 function rejection(directory: string): string | undefined {
@@ -50,15 +72,15 @@ function rejection(directory: string): string | undefined {
  */
 export function autoImportDirectories(
   modules: readonly FrontendModuleRoot[],
-  declarations: readonly FrontendBuildDeclaration[],
+  buildDeclarations: readonly FrontendBuildDeclaration[],
   warn: (message: string) => void,
 ): AutoImportDirectory[] {
   const roots = new Map(modules.map((module) => [module.id, module.root]));
-  return declarations.flatMap(({ id, setup }) => {
+  return buildDeclarations.flatMap(({ id, setup }) => {
     const root = roots.get(id);
     if (root === undefined) return [];
     const scan = (pattern: string) => normalizePath(resolve(root, pattern));
-    const accepted = declaredDirectories(setup).filter((directory) => {
+    const accepted = declared(setup).directories.filter((directory) => {
       const reason = rejection(directory);
       if (reason)
         warn(
@@ -76,3 +98,199 @@ export function autoImportDirectories(
     ];
   });
 }
+
+/** The keys of a Vite plugin that hold a value, not a function Vite calls. */
+const PLUGIN_PROPERTIES = new Set([
+  "name",
+  "enforce",
+  "apply",
+  "sharedDuringBuild",
+  "perEnvironmentState",
+  "api",
+]);
+
+/** The hooks whose function result is itself a hook, run after the server starts. */
+const SERVER_HOOKS = new Set(["configureServer", "configurePreviewServer"]);
+
+const attributedErrors = new WeakSet<object>();
+
+/** The fields of a Rollup or Vite error that diagnostics and the overlay read. */
+const ERROR_FIELDS = [
+  "id",
+  "loc",
+  "frame",
+  "plugin",
+  "pluginCode",
+  "hook",
+  "code",
+] as const;
+
+/**
+ * A new error naming the module, with the original as its cause: the original
+ * may be frozen. It carries the original's diagnostic fields and its stack
+ * frames, so the error still points at the file and the line.
+ */
+function attribute(label: string, error: unknown): Error {
+  if (error instanceof Error && attributedErrors.has(error)) return error;
+  const message = error instanceof Error ? error.message : String(error);
+  const attributed = new Error(`Frontend module ${label}: ${message}`, {
+    cause: error,
+  });
+  attributedErrors.add(attributed);
+  if (!(error instanceof Error)) return attributed;
+  for (const field of ERROR_FIELDS) {
+    if (field in error)
+      Reflect.set(attributed, field, Reflect.get(error, field));
+  }
+  const frames = error.stack?.split(error.message).slice(1).join(error.message);
+  if (frames !== undefined && error.stack?.includes(error.message)) {
+    attributed.stack = `${error.name}: ${attributed.message}${frames}`;
+  }
+  return attributed;
+}
+
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "then" in value &&
+    typeof value.then === "function"
+  );
+}
+
+function attributedHook(
+  label: string,
+  hook: unknown,
+  returnsHook: boolean,
+): unknown {
+  if (typeof hook === "function") {
+    const attributedResult = (result: unknown): unknown =>
+      returnsHook ? attributedHook(label, result, false) : result;
+    return function (this: unknown, ...args: unknown[]) {
+      try {
+        const result: unknown = hook.apply(this, args);
+        if (isThenable(result)) {
+          return Promise.resolve(result).then(
+            attributedResult,
+            (error: unknown) => {
+              throw attribute(label, error);
+            },
+          );
+        }
+        return attributedResult(result);
+      } catch (error) {
+        throw attribute(label, error);
+      }
+    };
+  }
+  if (typeof hook === "object" && hook !== null && "handler" in hook) {
+    return {
+      ...hook,
+      handler: attributedHook(label, hook.handler, returnsHook),
+    };
+  }
+  return hook;
+}
+
+function isPlugin(value: unknown): value is Plugin {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    "name" in value &&
+    typeof value.name === "string" &&
+    value.name !== ""
+  );
+}
+
+/** Every property name of an object, inherited ones included. */
+function propertyNames(plugin: object): Set<string> {
+  const names = new Set<string>();
+  for (
+    let object: object | null = plugin;
+    object !== null && object !== Object.prototype;
+    object = Object.getPrototypeOf(object)
+  ) {
+    for (const name of Object.getOwnPropertyNames(object)) {
+      if (name !== "constructor") names.add(name);
+    }
+  }
+  return names;
+}
+
+/**
+ * A copy of the plugin whose hooks, own or inherited from its class, name the
+ * module in the errors they throw. The module's own object is left as it is.
+ */
+function attributedPlugin(label: string, plugin: Plugin): Plugin {
+  const copy: Record<string, unknown> = {};
+  for (const key of propertyNames(plugin)) {
+    const value: unknown = Reflect.get(plugin, key);
+    copy[key] = PLUGIN_PROPERTIES.has(key)
+      ? value
+      : attributedHook(label, value, SERVER_HOOKS.has(key));
+  }
+  if (!isPlugin(copy)) throw invalidPlugins(label);
+  return copy;
+}
+
+function invalidPlugins(label: string): Error {
+  return new Error(
+    `Frontend module ${label} registered Vite plugins that are not valid: the function given to registerVitePlugins must return an array of Vite plugin objects, each with a name (false, null and undefined entries are skipped, nested arrays are flattened), or nothing.`,
+  );
+}
+
+function flattened(label: string, entries: readonly unknown[]): Plugin[] {
+  return entries.flatMap((entry): Plugin[] => {
+    if (entry === false || entry === null || entry === undefined) return [];
+    if (Array.isArray(entry)) return flattened(label, entry);
+    if (isThenable(entry)) throw promisedPlugins(label);
+    if (!isPlugin(entry)) throw invalidPlugins(label);
+    return [entry];
+  });
+}
+
+function promisedPlugins(label: string): Error {
+  return new Error(
+    `Frontend module ${label} registered Vite plugins as a Promise: Vite's configuration is built synchronously, so the function given to registerVitePlugins must return the plugins themselves, not a Promise.`,
+  );
+}
+
+function createdPlugins(label: string, create: VitePluginFactory): Plugin[] {
+  let created: unknown;
+  try {
+    created = create();
+  } catch (error) {
+    throw attribute(label, error);
+  }
+  if (created === undefined) return [];
+  if (isThenable(created)) throw promisedPlugins(label);
+  if (!Array.isArray(created)) throw invalidPlugins(label);
+  return flattened(label, created);
+}
+
+/**
+ * The Vite plugins the modules registered with `registerVitePlugins`, in module
+ * order and then call order. Each module's factories run here, in the build
+ * process. A factory that throws, returns a Promise, or returns anything but an
+ * array of plugin objects (or nothing) fails with a message naming the module,
+ * and so does an error thrown by a hook of one of its plugins. As in a Vite
+ * configuration, false, null and undefined entries are skipped and nested
+ * arrays are flattened.
+ */
+export function vitePlugins(
+  modules: readonly FrontendModuleName[],
+  buildDeclarations: readonly FrontendBuildDeclaration[],
+): Plugin[] {
+  const names = new Map(
+    modules.map((module) => [module.id, module.name ?? module.id]),
+  );
+  return buildDeclarations.flatMap(({ id, setup }) => {
+    const label = names.get(id) ?? id;
+    return declared(setup).pluginFactories.flatMap((create) =>
+      createdPlugins(label, create).map((plugin) =>
+        attributedPlugin(label, plugin),
+      ),
+    );
+  });
+}

package/templates/vue/frontend-build.ts

@@ -1,3 +1,17 @@
+import type { Plugin } from "vite";
+
+/**
+ * What a `registerVitePlugins` function may return, as in a Vite
+ * configuration's `plugins`, except that a Promise is refused: Vite's
+ * configuration is built synchronously.
+ */
+export type DmsVitePluginEntry =
+  | Plugin
+  | false
+  | null
+  | undefined
+  | readonly DmsVitePluginEntry[];
+
 /**
  * What a frontend module's `dms.frontend.build.ts` declares about how the
  * application is built from it. Read when Vite starts, by `ajs dms dev` and
@@ -14,6 +28,24 @@ export interface DmsFrontendBuild {
    * holds the module's private code, which its own files import by path.
    */
   registerAutoImports(directories: readonly string[]): void;
+
+  /**
+   * Adds Vite plugins to the application's build, for `ajs dms dev`,
+   * `ajs dms build` and the preview alike.
+   *
+   * `create` runs in the build process each time Vite loads its configuration,
+   * and returns real Vite plugin objects (an array, each with a `name`; false,
+   * null and undefined entries are skipped and nested arrays flattened, as in a
+   * Vite configuration) or nothing. It is synchronous: a Promise is refused,
+   * because the configuration is built synchronously. The plugins come after
+   * the renderer's own plugins, in module order, then in the order of the
+   * calls. A value that is not an array of plugin objects, or an error thrown
+   * by `create` or by any hook of a plugin (the function `configureServer`
+   * returns included), fails Vite with a message that names the module.
+   */
+  registerVitePlugins(
+    create: () => readonly DmsVitePluginEntry[] | undefined,
+  ): void;
 }
 
 export type DmsFrontendBuildSetup = (build: DmsFrontendBuild) => void;
@@ -27,10 +59,11 @@ export type DmsFrontendBuildSetup = (build: DmsFrontendBuild) => void;
  *
  * export default defineDmsFrontendBuild((build) => {
  *   build.registerAutoImports(["layers/*\/app/composables"]);
+ *   build.registerVitePlugins(() => [boundaryPlugin()]);
  * });
  * ```
  *
- * A module without this file has nothing auto-imported. The file runs in
+ * A module without this file has nothing auto-imported and adds no plugin. The file runs in
  * Node.js when Vite starts, not in the application: it may import Node.js
  * built-ins, never the application's own code.
  */

package/templates/vue/vite.config.ts

@@ -15,7 +15,7 @@ import { rejectServerSourcesInClient } from "./client-server-guard.mjs";
 import { uiInertiaPage } from "./ui-inertia-page.mjs";
 import { uiKbd } from "./ui-kbd.mjs";
 import { uiRequestState } from "./ui-request-state.mjs";
-import { autoImportDirectories } from "./frontend-build-loader.ts";
+import { autoImportDirectories, vitePlugins } from "./frontend-build-loader.ts";
 import { frontendBuilds } from "./frontend-builds.generated.ts";
 import { orderHeadForFirstPaint } from "./head-order.mjs";
 import { iconScanGlobs } from "./icon-scan.mjs";
@@ -263,6 +263,7 @@ export default defineConfig({
       },
     }),
     paintBeforeHydrate(),
+    ...vitePlugins(registry.modules, frontendBuilds),
   ],
   resolve: {
     // `@iconify/vue` keeps its API providers in module state: `main.ts` and