@antelopejs/dms-frontend 0.1.0 → 0.1.2

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,9 +93,9 @@ 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`.
 
@@ -89,9 +126,64 @@ 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_API_BASE_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, or in the project's `.env`, 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.
+Each canonical backend URL gets an owner-only workspace under `~/.antelopejs/dms-frontend` (see [Workspaces](#workspaces) for how the key is derived). 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.
+
+## Configuration
+
+Every command loads `.env.local` then `.env` from the **current working
+directory** before it parses its options, so a project can keep its
+configuration in a file instead of exporting variables by hand:
+
+```bash
+# .env
+DMS_API_BASE_URL=http://localhost:5010
+DMS_CLIENT_BASE_URL=http://localhost:3001
+DMS_BOOTSTRAP_SECRET=replace_with_a_strong_random_value
+DMS_SESSION_SECRET=replace_with_at_least_32_characters
+```
+
+Precedence is environment, then `.env.local`, then `.env`: a variable already
+present in the environment is never overwritten, so `DMS_API_BASE_URL=… ajs dms
+build` and a CI job's injected secrets always win over a file left in the
+checkout. A variable exported as an empty string counts as set. Only the
+current directory is read — never a parent directory, and never the generated
+workspace under `~/.antelopejs/dms-frontend`, which is this tool's own output
+and is handed its environment explicitly by the command that spawns it. The
+values loaded here reach the workspace build started by `build`, the dev server
+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`.
+
+### Workspaces
+
+Each canonical backend URL gets its own owner-only workspace under
+`~/.antelopejs/dms-frontend/<sha256>/`; `build`, `start`, `clean -b` and
+`dev -b` all key on that URL, so one backend means one workspace shared by
+every command.
+
+`dev` without `-b` is the deliberate exception. It discovers the backend from
+the enclosing antelope project's `.antelope/dev.json` and keys its workspace on
+the **project directory** instead, because a development backend can land on a
+different port between runs and re-keying on the URL would discard
+`node_modules`, the manifest cache and the client-side appId scope every time it
+does. The consequence is that `ajs dms dev` followed by `ajs dms build -b <url>`
+against the same backend creates two workspaces of their own — several hundred
+megabytes each. Pass `-b` to `dev` to share a single one. `clean --all` lists
+both and names the project a workspace is keyed on; `clean -b <url>` only
+reaches the URL-keyed one.
+
+A `DMS_API_BASE_URL` line in `.env` counts as an explicit backend, so a project
+that configures one gets the single shared workspace and gives up autodiscovery
+— including its tolerance for the backend moving to another port. Leave the
+variable out of `.env` to keep autodiscovery for `dev`.
 
 ## Rendering model
 
@@ -112,6 +204,10 @@ frontend-module registry drives server and client entries.
 | `--bootstrap-secret` | `DMS_BOOTSTRAP_SECRET` | Backend bootstrap credential |
 | | `DMS_COOKIE_SECURE` | Secure cookies (`true` by default; `ajs dms dev` defaults to `false`) |
 | | `DMS_TRUSTED_PROXY_HOPS` | Number of trusted, rightmost reverse-proxy hops (default `0`) |
+| | `DMS_SESSION_SECRET` | Session cookie encryption key, 32 characters or more (required for login) |
+| | `DMS_CLIENT_BASE_URL` | Public frontend URL used in generated links and emails |
+
+All of these can be set in the project's `.env` instead of the environment; see [Configuration](#configuration).
 
 Use pnpm for all repository and workspace operations.
 

package/dist/commands/clean.js

@@ -21,14 +21,17 @@ function cmdClean() {
             }
             for (const ws of workspaces) {
                 (0, node_fs_1.rmSync)(ws.dir, { recursive: true, force: true });
-                (0, cli_ui_1.success)(`Removed ${ws.dir} (${ws.backendUrl})`);
+                (0, cli_ui_1.success)(`Removed ${ws.dir} (${(0, common_1.describeWorkspace)(ws)})`);
             }
             console.log("");
             (0, cli_ui_1.success)(`Cleaned ${workspaces.length} workspace(s).`);
             return;
         }
         if (!options.backendUrl) {
-            (0, cli_ui_1.warning)("Specify -b <url> to clean a specific workspace, or --all to clean everything.");
+            (0, cli_ui_1.warning)("Specify -b <url> to clean a specific workspace, or --all to clean everything.\n" +
+                "  -b only reaches the workspace 'build', 'start' and 'dev -b' share for that URL;\n" +
+                "  a workspace 'dev' created without -b is keyed on the project directory and is\n" +
+                "  only removable with --all.");
             process.exit(1);
         }
         const workspaceDir = (0, common_1.getWorkspaceDir)(options.backendUrl);

package/dist/config.js

@@ -88,7 +88,9 @@ exports.Options = {
         .default("3001")
         .env("PORT"),
     force: new commander_1.Option("-f, --force", "Force reinstall dependencies"),
-    offline: new commander_1.Option("--offline", "Skip the backend manifest fetch and reuse the last cached manifest (env: DMS_OFFLINE)").default(booleanFromEnv("DMS_OFFLINE")),
+    get offline() {
+        return new commander_1.Option("--offline", "Skip the backend manifest fetch and reuse the last cached manifest (env: DMS_OFFLINE)").default(booleanFromEnv("DMS_OFFLINE"));
+    },
     bootstrapSecret: new commander_1.Option("--bootstrap-secret <secret>", "Credential presented to the backend's layer endpoints (env: DMS_BOOTSTRAP_SECRET, preferred — " +
         "a secret passed on the command line is visible to every process on the machine). In dev it is " +
         "discovered from the antelope project's .antelope/dms-dev.json.").env("DMS_BOOTSTRAP_SECRET"),

package/dist/env-file.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENV_FILE_NAMES = void 0;
+exports.loadProjectEnv = loadProjectEnv;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_util_1 = require("node:util");
+exports.ENV_FILE_NAMES = [".env.local", ".env"];
+function loadProjectEnv(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const env = options.env ?? process.env;
+    const onWarning = options.onWarning ?? ((message) => console.warn(message));
+    const loaded = [];
+    for (const name of exports.ENV_FILE_NAMES) {
+        const file = (0, node_path_1.join)(cwd, name);
+        if (!(0, node_fs_1.existsSync)(file))
+            continue;
+        let parsed;
+        try {
+            parsed = (0, node_util_1.parseEnv)((0, node_fs_1.readFileSync)(file, "utf-8"));
+        }
+        catch (err) {
+            onWarning(`⚠ Ignoring ${file}: ${err?.message ?? err}`);
+            continue;
+        }
+        for (const [key, value] of Object.entries(parsed)) {
+            if (value !== undefined && env[key] === undefined)
+                env[key] = value;
+        }
+        loaded.push(file);
+    }
+    return loaded;
+}

package/dist/index.js

@@ -12,10 +12,12 @@ const dev_1 = require("./commands/dev");
 const prepare_1 = require("./commands/prepare");
 const start_1 = require("./commands/start");
 const verify_source_1 = require("./commands/verify-source");
+const env_file_1 = require("./env-file");
 const update_check_1 = require("./update-check");
 const cli_ui_1 = require("./utils/cli-ui");
 const { version } = require("../package.json");
 const runCLI = async () => {
+    (0, env_file_1.loadProjectEnv)();
     const argv = process.argv.slice(2);
     void (0, update_check_1.checkForUpdate)({ currentVersion: version, argv });
     if (process.argv.length <= 2) {
@@ -28,7 +30,21 @@ const runCLI = async () => {
         `Materializes frontend modules from an AntelopeJS backend and starts a Vue or React Vite and Inertia application.`)
         .version(version, "-v, --version", "Display version number")
         .option("--no-update-check", "Skip the daily check for a newer DMS frontend release")
-        .helpCommand("help [command]", "Display help for a specific command");
+        .helpCommand("help [command]", "Display help for a specific command")
+        .addHelpText("after", `
+Environment:
+  Every command reads ${env_file_1.ENV_FILE_NAMES.join(" then ")} from the current directory before parsing
+  its options, so DMS_API_BASE_URL, DMS_BOOTSTRAP_SECRET, DMS_SESSION_SECRET and
+  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.
+
+Workspaces:
+  Each canonical backend URL gets its own workspace under
+  ~/.antelopejs/dms-frontend. 'dev' without -b is the exception: it keys the
+  workspace on the antelope project directory instead, so a backend that lands
+  on a different port between runs keeps its node_modules and manifest cache.
+  Pass -b to 'dev' to share one workspace with 'build' and 'start'.`);
     program.addCommand((0, dev_1.cmdDev)());
     program.addCommand((0, build_1.cmdBuild)());
     program.addCommand((0, start_1.cmdStart)());

package/dist/workspace.js

@@ -3,8 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FRONTEND_MANIFEST_VERSION = void 0;
 exports.getWorkspaceDirForKey = getWorkspaceDirForKey;
 exports.projectWorkspaceKey = projectWorkspaceKey;
+exports.projectDirFromWorkspaceKey = projectDirFromWorkspaceKey;
 exports.getWorkspaceDir = getWorkspaceDir;
 exports.ensureWorkspace = ensureWorkspace;
+exports.describeWorkspace = describeWorkspace;
 exports.listWorkspaces = listWorkspaces;
 exports.writeWorkspaceMeta = writeWorkspaceMeta;
 exports.bootstrapHeaders = bootstrapHeaders;
@@ -16,8 +18,14 @@ const WORKSPACE_META_FILE = ".ajs-dms-meta.json";
 function getWorkspaceDirForKey(key) {
     return (0, node_path_1.join)(config_1.DMS_FRONTEND_HOME, (0, config_1.sha256Hex)(key));
 }
+const PROJECT_KEY_PREFIX = "project:";
 function projectWorkspaceKey(projectDir) {
-    return `project:${(0, node_path_1.resolve)(projectDir)}`;
+    return `${PROJECT_KEY_PREFIX}${(0, node_path_1.resolve)(projectDir)}`;
+}
+function projectDirFromWorkspaceKey(workspaceKey) {
+    return workspaceKey?.startsWith(PROJECT_KEY_PREFIX)
+        ? workspaceKey.slice(PROJECT_KEY_PREFIX.length)
+        : undefined;
 }
 function getWorkspaceDir(backendUrl) {
     return getWorkspaceDirForKey((0, config_1.canonicalizeBackendUrl)(backendUrl));
@@ -30,6 +38,12 @@ function ensureWorkspace(workspaceKey) {
     (0, node_fs_1.chmodSync)(dir, config_1.WORKSPACE_DIR_MODE);
     return dir;
 }
+function describeWorkspace(entry) {
+    const projectDir = projectDirFromWorkspaceKey(entry.workspaceKey);
+    return projectDir
+        ? `${entry.backendUrl}, keyed on project ${projectDir}`
+        : entry.backendUrl;
+}
 function listWorkspaces() {
     if (!(0, node_fs_1.existsSync)(config_1.DMS_FRONTEND_HOME))
         return [];
@@ -38,16 +52,20 @@ function listWorkspaces() {
         if (!entry.isDirectory())
             continue;
         const dir = (0, node_path_1.join)(config_1.DMS_FRONTEND_HOME, entry.name);
-        const backendUrl = readWorkspaceBackendUrl(dir);
-        if (backendUrl === undefined) {
+        const meta = readWorkspaceMeta(dir);
+        if (meta?.backendUrl === undefined) {
             console.warn(`⚠ Skipping ${dir}: no readable ${WORKSPACE_META_FILE}.`);
             continue;
         }
-        workspaces.push({ dir, backendUrl });
+        workspaces.push({
+            dir,
+            backendUrl: meta.backendUrl,
+            workspaceKey: meta.workspaceKey,
+        });
     }
     return workspaces;
 }
-function readWorkspaceBackendUrl(dir) {
+function readWorkspaceMeta(dir) {
     let meta;
     try {
         meta = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, WORKSPACE_META_FILE), "utf-8"));
@@ -55,8 +73,13 @@ function readWorkspaceBackendUrl(dir) {
     catch {
         return undefined;
     }
-    const backendUrl = meta?.backendUrl;
-    return typeof backendUrl === "string" ? backendUrl : undefined;
+    const record = meta;
+    return {
+        backendUrl: typeof record?.backendUrl === "string" ? record.backendUrl : undefined,
+        workspaceKey: typeof record?.workspaceKey === "string"
+            ? record.workspaceKey
+            : undefined,
+    };
 }
 function writeWorkspaceMeta(workspaceDir, backendUrl, workspaceKey) {
     (0, node_fs_1.writeFileSync)((0, node_path_1.join)(workspaceDir, WORKSPACE_META_FILE), JSON.stringify({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@antelopejs/dms-frontend",
-  "version": "0.1.0",
-  "description": "Vue 3, Vite, and Inertia frontend loader for AntelopeJS DMS",
+  "version": "0.1.2",
+  "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"
@@ -81,7 +82,7 @@
     "vue-i18n": "^11.1.12"
   },
   "peerDependencies": {
-    "@antelopejs/core": ">=1.5.0 <2"
+    "@antelopejs/core": ">=1.6.0 <2"
   },
   "peerDependenciesMeta": {
     "@antelopejs/core": {
@@ -95,5 +96,8 @@
     "@oxc-parser/binding-linux-x64-gnu": "^0.95.0",
     "@oxc-parser/binding-win32-x64-msvc": "^0.95.0"
   },
+  "engines": {
+    "node": ">=20.12.0"
+  },
   "packageManager": "pnpm@10.6.5"
 }

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

@@ -17,7 +17,10 @@ const UUID =
 function key() {
   const secret = process.env.DMS_SESSION_SECRET;
   if (!secret || secret.length < 32)
-    throw new Error("DMS_SESSION_SECRET must contain at least 32 characters");
+    throw new Error(
+      "DMS_SESSION_SECRET must contain at least 32 characters; " +
+        "generate one with: openssl rand -hex 32",
+    );
   return createHash("sha256").update(secret).digest();
 }