@antelopejs/dms-frontend 0.0.1 → 0.1.1

package/README.md

@@ -6,7 +6,44 @@
 <a href="https://antelopejs.com"><img src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000" alt="Documentation"></a>
 </div>
 
-Official Vue 3, Vite, Inertia, and SSR frontend loader for AntelopeJS DMS. The `ajs dms` CLI generates a Vue workspace and runs its Node frontend server.
+Frontend-agnostic loader for AntelopeJS DMS. The backend serves a frontend
+manifest and the matching frontend-module archives; the `ajs dms` CLI
+materializes them into a generated workspace for one renderer, builds it, and
+runs its Node frontend server. The `vue` renderer — Vue 3, Vite, Inertia, and
+SSR — is the one shipped today.
+
+## Renderers
+
+A renderer is the target framework a generated workspace is built for. The
+loader's contract with a renderer has three parts:
+
+- **Manifest negotiation.** `prepare`, `dev`, and `build` request the versioned
+  `/dms/frontend` manifest with `renderer=vue&rendererVersion=3`
+  (`src/manifest.ts`) and reject every module whose `renderer` does not match.
+  The backend side is renderer-keyed too: `AddFrontendModule` takes a
+  `renderer: { name, version }`, and each manifest module carries it back
+  (`ManifestModule.renderer` in `src/workspace.ts`).
+- **Workspace templates.** Every file of the generated workspace comes from
+  `templates/<renderer>/` — `templates/vue/` today. `TEMPLATE_FILES` in
+  `src/config.ts` lists what is copied verbatim, and `src/materialize.ts`
+  resolves the template root, copies it, materializes the frontend modules
+  under `frontend-modules/`, and writes `generated-frontend-modules.json` in
+  manifest-priority order.
+- **Generated server.** `templates/vue/server.mjs` and `templates/vue/server/`
+  become the Node server that `ajs dms start` runs from the built workspace:
+  Inertia visits, backend proxying, sessions, and email rendering.
+
+`vue` (version `3`) is the only renderer this package ships, and the loader
+rejects a manifest that declares any other. Renderers for other frameworks —
+React, Svelte, Solid — are a direction, not a promise: nothing in the package
+implements them yet. Adding one means a new `templates/<renderer>/` tree, plus
+making the template root (`src/materialize.ts`) and the manifest query
+(`src/manifest.ts`) renderer-aware instead of hardcoding `vue`. There is no
+`--renderer` flag and no renderer registry; the single-renderer assumption is
+deliberate until a second renderer exists. Whatever a renderer names its module
+entry is its own convention: `dms.frontend.ts` and the
+`#dms-inertia/frontend-module` alias belong to the Vue renderer, not to the
+loader.
 
 ## Application ownership
 
@@ -56,13 +93,13 @@ throttle stamp lives at `~/.antelopejs/dms-frontend/update-check.json`. Set
 `NO_UPDATE_NOTIFIER=1`, pass `--no-update-check`, or run under `CI` to turn the
 check off.
 
-The loader renders Vue 3 only: a manifest that declares any other renderer is rejected. `prepare`, `dev`, and `build` request the versioned `/dms/frontend` manifest with `renderer=vue&rendererVersion=3`. Modules are materialized under `frontend-modules/` and registered in deterministic manifest-priority order in `generated-frontend-modules.json`.
+Manifest negotiation and module materialization are the renderer contract described in [Renderers](#renderers).
 
-The generated application uses `@inertiajs/vue3`, `@nuxt/ui/vite` with `{ router: "inertia" }`, and `@nuxt/ui/vue-plugin`. The Node server resolves each Inertia visit through `/dms/page?path=…`, including fresh shared data so account, tenant, and permission changes update navigation state. It proxies backend routes and manages authentication through server-side sessions. `DMS_BOOTSTRAP_SECRET` is used only by the CLI's server-to-server frontend manifest and module archive requests and is never sent by, or exposed to, browser traffic.
+The generated Vue application uses `@inertiajs/vue3`, `@nuxt/ui/vite` with `{ router: "inertia" }`, and `@nuxt/ui/vue-plugin`. The Node server resolves each Inertia visit through `/dms/page?path=…`, including fresh shared data so account, tenant, and permission changes update navigation state. It proxies backend routes and manages authentication through server-side sessions. `DMS_BOOTSTRAP_SECRET` is used only by the CLI's server-to-server frontend manifest and module archive requests and is never sent by, or exposed to, browser traffic.
 
 Vue modules use `dms.frontend.ts` and the `#dms-inertia/frontend-module` SDK alias, which replaces the former `#cms-inertia` alias and is the import path every DMS frontend module now uses. Email templates register separately through `dms.email.ts`.
 
-An email entry exports `serverEmailTemplates` and may export a plain `appConfig` object, such as shared branding defaults. Email rendering merges these configurations in manifest-priority order and provides them to `useDmsAppConfig` per render. Public runtime options come from the module manifest; `DMS_CLIENT_URL` overrides `public.dms.clientBaseUrl`. Email entries must not import the browser frontend module.
+An email entry exports `serverEmailTemplates` and may export a plain `appConfig` object, such as shared branding defaults. Email rendering merges these configurations in manifest-priority order and provides them to `useDmsAppConfig` per render. Public runtime options come from the module manifest; `DMS_CLIENT_BASE_URL` overrides `public.dms.clientBaseUrl`. Email entries must not import the browser frontend module.
 
 Email builds ship complete merged translation catalogs as JSON under `dist/server/locales/`, separate from executable JavaScript. Deploy the entire `dist/server` directory. Each render loads only its requested language and the English fallback; arbitrary translation keys and module overrides remain available. Unknown languages fall back to English, while missing or corrupt files for a supported language fail rendering rather than silently dropping translations. The source harness keeps the 256 KiB JavaScript ceiling and reports locale-data bytes separately.
 
@@ -89,7 +126,7 @@ The SDK also exposes `use` for Vue plugins. Entries execute by descending manife
 
 ## Discovery, caching, and security
 
-In development, `ajs dms` discovers the backend from the nearest live `.antelope/dev.json`. It reads the local bootstrap credential from `.antelope/dms-dev.json` only when that discovered backend matches the destination URL. For production and CI, set `DMS_BACKEND_URL` and `DMS_BOOTSTRAP_SECRET` in the environment rather than passing credentials on the command line.
+In development, `ajs dms` discovers the backend from the nearest live `.antelope/dev.json`. It reads the local bootstrap credential from `.antelope/dms-dev.json` only when that discovered backend matches the destination URL. For production and CI, set `DMS_API_BASE_URL` and `DMS_BOOTSTRAP_SECRET` in the environment rather than passing credentials on the command line.
 
 Each canonical backend URL gets an owner-only workspace under `~/.antelopejs/dms-frontend`. Manifest caches, private module configuration, and extracted archives retain restrictive permissions. `--offline` reuses the last successful manifest and archive; an authorization failure never falls back to privileged cached data.
 
@@ -105,7 +142,7 @@ frontend-module registry drives server and client entries.
 
 | Option | Environment | Purpose |
 | --- | --- | --- |
-| `-b, --backend-url` | `DMS_BACKEND_URL` | DMS backend URL |
+| `-b, --backend-url` | `DMS_API_BASE_URL` | DMS backend URL |
 | `-p, --port` | `PORT` | Frontend port, default `3001` |
 | `-f, --force` | | Reinstall workspace dependencies |
 | `--offline` | `DMS_OFFLINE` | Reuse cached manifest and archives |

package/dist/commands/build.js

@@ -18,7 +18,7 @@ function cmdBuild() {
         .addOption(common_1.Options.bootstrapSecret)
         .action(async (options) => {
         if (!options.backendUrl) {
-            (0, cli_ui_1.error)("Backend URL is required. Use -b <url> or set DMS_BACKEND_URL.");
+            (0, cli_ui_1.error)("Backend URL is required. Use -b <url> or set DMS_API_BASE_URL.");
             process.exit(1);
         }
         const spinner = new cli_ui_1.Spinner("Setting up workspace...");

package/dist/commands/dev.js

@@ -99,7 +99,7 @@ function cmdDev() {
                     PORT: String(port),
                     DMS_DEV: "true",
                     DMS_COOKIE_SECURE: process.env.DMS_COOKIE_SECURE ?? "false",
-                    DMS_BACKEND_URL: backendUrl,
+                    DMS_API_BASE_URL: backendUrl,
                     DMS_BOOTSTRAP_SECRET: bootstrapSecret,
                     NODE_OPTIONS: "--max-old-space-size=4096",
                     NODE_PATH: nodeModulesDir,

package/dist/commands/prepare.js

@@ -17,7 +17,7 @@ function cmdPrepare() {
         .addOption(common_1.Options.bootstrapSecret)
         .action(async (options) => {
         if (!options.backendUrl) {
-            (0, cli_ui_1.warning)("Backend URL not set; skipping prepare. Pass -b <url> or set DMS_BACKEND_URL to generate types.");
+            (0, cli_ui_1.warning)("Backend URL not set; skipping prepare. Pass -b <url> or set DMS_API_BASE_URL to generate types.");
             process.exit(0);
         }
         const spinner = new cli_ui_1.Spinner("Setting up workspace...");

package/dist/commands/start.js

@@ -17,7 +17,7 @@ function cmdStart() {
         .addOption(common_1.Options.port)
         .action(async (options) => {
         if (!options.backendUrl) {
-            (0, cli_ui_1.error)("Backend URL is required. Use -b <url> or set DMS_BACKEND_URL.");
+            (0, cli_ui_1.error)("Backend URL is required. Use -b <url> or set DMS_API_BASE_URL.");
             process.exit(1);
         }
         const workspaceDir = (0, common_1.getWorkspaceDir)(options.backendUrl);
@@ -40,7 +40,7 @@ function cmdStart() {
             env: {
                 ...process.env,
                 PORT: options.port,
-                DMS_BACKEND_URL: options.backendUrl,
+                DMS_API_BASE_URL: options.backendUrl,
                 DMS_COOKIE_SECURE: process.env.DMS_COOKIE_SECURE ?? "true",
             },
         });

package/dist/config.js

@@ -83,7 +83,7 @@ function booleanFromEnv(name) {
     return !["", "0", "false", "no", "off"].includes(value.trim().toLowerCase());
 }
 exports.Options = {
-    backendUrl: new commander_1.Option("-b, --backend-url <url>", "Backend DMS URL (when omitted, dev mode discovers it from the enclosing antelope project's .antelope/dev.json)").env("DMS_BACKEND_URL"),
+    backendUrl: new commander_1.Option("-b, --backend-url <url>", "Backend DMS URL (when omitted, dev mode discovers it from the enclosing antelope project's .antelope/dev.json)").env("DMS_API_BASE_URL"),
     port: new commander_1.Option("-p, --port <port>", "Port to run on")
         .default("3001")
         .env("PORT"),

package/dist/discovery.js

@@ -82,7 +82,7 @@ function describeDiscoveryFailure(result) {
             return ("No backend URL provided and no running antelope project found.\n" +
                 `  Searched for ${exports.DEV_REGISTRY_RELATIVE_PATH} from the current directory upward.\n` +
                 "  Either run this command inside an antelope project started with 'ajs project dev',\n" +
-                "  or pass the backend explicitly with -b <url> (env: DMS_BACKEND_URL).");
+                "  or pass the backend explicitly with -b <url> (env: DMS_API_BASE_URL).");
         case "stale":
             return (`Found ${(0, node_path_1.join)(result.projectDir, exports.DEV_REGISTRY_RELATIVE_PATH)} but its process (pid ${result.pid}) is no longer running.\n` +
                 "  Start the backend with 'ajs project dev', or pass -b <url> explicitly.");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@antelopejs/dms-frontend",
-  "version": "0.0.1",
-  "description": "Vue 3, Vite, and Inertia frontend loader for AntelopeJS DMS",
+  "version": "0.1.1",
+  "description": "Frontend-agnostic loader for AntelopeJS DMS, shipping the Vue 3 renderer (Vite, Inertia, SSR)",
   "keywords": [
     "antelope",
     "antelopejs",
@@ -10,6 +10,7 @@
     "frontend-modules",
     "inertia",
     "loader",
+    "renderer",
     "ui",
     "vite",
     "vue"
@@ -31,6 +32,19 @@
     "provenance": true,
     "registry": "https://registry.npmjs.org/"
   },
+  "scripts": {
+    "build": "rimraf dist && tsc -p tsconfig.build.json",
+    "prepack": "pnpm run build",
+    "release": "pnpm run lint && pnpm run test && pnpm run prepack && release-it",
+    "test": "node --import tsx --test tests/*.test.ts tests/*.test.mts",
+    "test:real-source": "pnpm run build && node dist/verify-source-runner.js",
+    "format": "oxfmt .",
+    "lint": "oxlint && oxfmt --check .",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint:fix": "oxlint --fix --max-warnings=1000000 && oxfmt .",
+    "knip": "knip --dependencies",
+    "knip:all": "knip"
+  },
   "dependencies": {
     "boxen": "^5.1.2",
     "chalk": "^4.1.2",
@@ -68,7 +82,7 @@
     "vue-i18n": "^11.1.12"
   },
   "peerDependencies": {
-    "@antelopejs/core": ">=1.5.0 <2"
+    "@antelopejs/core": ">=1.6.0 <2"
   },
   "peerDependenciesMeta": {
     "@antelopejs/core": {
@@ -82,16 +96,5 @@
     "@oxc-parser/binding-linux-x64-gnu": "^0.95.0",
     "@oxc-parser/binding-win32-x64-msvc": "^0.95.0"
   },
-  "scripts": {
-    "build": "rimraf dist && tsc -p tsconfig.build.json",
-    "release": "pnpm run lint && pnpm run test && pnpm run prepack && release-it",
-    "test": "node --import tsx --test tests/*.test.ts tests/*.test.mts",
-    "test:real-source": "pnpm run build && node dist/verify-source-runner.js",
-    "format": "oxfmt .",
-    "lint": "oxlint && oxfmt --check .",
-    "typecheck": "tsc -p tsconfig.json",
-    "lint:fix": "oxlint --fix --max-warnings=1000000 && oxfmt .",
-    "knip": "knip --dependencies",
-    "knip:all": "knip"
-  }
-}
+  "packageManager": "pnpm@10.6.5"
+}

package/templates/vue/email-renderer.ts

@@ -147,8 +147,8 @@ export async function renderEmail(
   );
   app.provide("dmsEmailRuntimeConfig", {
     public: defu(
-      process.env.DMS_CLIENT_URL
-        ? { dms: { clientBaseUrl: process.env.DMS_CLIENT_URL } }
+      process.env.DMS_CLIENT_BASE_URL
+        ? { dms: { clientBaseUrl: process.env.DMS_CLIENT_BASE_URL } }
         : {},
       publicConfig,
       { dms: { clientBaseUrl: "" } },

package/templates/vue/email-runtime.ts

@@ -12,7 +12,7 @@ export function useDmsAppConfig(): Record<string, unknown> {
 
 export function useDmsRuntimeConfig(): EmailRuntimeConfig {
   return inject<EmailRuntimeConfig>("dmsEmailRuntimeConfig", {
-    public: { dms: { clientBaseUrl: process.env.DMS_CLIENT_URL ?? "" } },
+    public: { dms: { clientBaseUrl: process.env.DMS_CLIENT_BASE_URL ?? "" } },
   });
 }
 

package/templates/vue/server/auth/backend.mjs

@@ -34,7 +34,7 @@ export async function backend(path, request, options = {}) {
   if (options.relay)
     headers["x-dms-oauth-relay"] = process.env.DMS_OAUTH_RELAY_SECRET ?? "";
   if (options.body !== undefined) headers["content-type"] = "application/json";
-  const response = await fetch(new URL(path, process.env.DMS_BACKEND_URL), {
+  const response = await fetch(new URL(path, process.env.DMS_API_BASE_URL), {
     method: options.method ?? "GET",
     headers,
     body: options.body === undefined ? undefined : JSON.stringify(options.body),

package/templates/vue/server/tester.mjs

@@ -71,7 +71,7 @@ function targetUrl(path) {
   )
     return invalidInput();
   path.split("?", 1)[0].split("/").forEach(validatePathSegment);
-  const base = new URL(process.env.DMS_BACKEND_URL);
+  const base = new URL(process.env.DMS_API_BASE_URL);
   if (
     !["http:", "https:"].includes(base.protocol) ||
     base.username ||

package/templates/vue/server.mjs

@@ -142,14 +142,14 @@ function serverComponentFetch(request) {
     });
     return ofetch(path, {
       ...options,
-      baseURL: process.env.DMS_BACKEND_URL,
+      baseURL: process.env.DMS_API_BASE_URL,
       headers,
     });
   };
 }
 
 async function backendJson(path, request) {
-  const response = await fetch(new URL(path, process.env.DMS_BACKEND_URL), {
+  const response = await fetch(new URL(path, process.env.DMS_API_BASE_URL), {
     headers: backendHeaders(request),
   });
   if (!response.ok) {
@@ -245,7 +245,7 @@ async function proxy(request, response, fallbackOnNotFound = false) {
     response.end(JSON.stringify({ error: "Forbidden" }));
     return true;
   }
-  const target = new URL(request.url, process.env.DMS_BACKEND_URL);
+  const target = new URL(request.url, process.env.DMS_API_BASE_URL);
   const upstream = await fetch(target, {
     method: request.method,
     headers: backendHeaders(request),