@antelopejs/dms-frontend 0.0.1

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright (c) 2025-present - AntelopeJS Team
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,131 @@
+# @antelopejs/dms-frontend
+
+<div align="center">
+<a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-blue?style=for-the-badge&labelColor=000000"></a>
+<a href="https://discord.gg/sjK28QHrA7"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000" alt="Discord"></a>
+<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.
+
+## Application ownership
+
+The generated Inertia application owns page resolution, SSR, hydration, and the
+root Vue tree. Every frontend module explicitly owns its native
+`dms.frontend.ts` entry. That entry registers reusable pages, layouts,
+components, plugins, and middleware through the frontend SDK; the loader does
+not infer application ownership from other framework configuration.
+
+## Install
+
+The loader is an AntelopeJS CLI plugin: install it next to `@antelopejs/core`
+and `ajs` delegates its `dms` command to the `ajs-dms` executable.
+
+```bash
+pnpm add -g @antelopejs/core @antelopejs/dms-frontend
+```
+
+`npm install -g` works too; this repository and every generated workspace use
+pnpm.
+
+## Commands
+
+```bash
+ajs dms prepare -b http://localhost:5010
+ajs dms dev -b http://localhost:5010 -p 3001
+ajs dms build -b https://dms.example.com
+ajs dms start -b https://dms.example.com -p 3001
+ajs dms clean -b https://dms.example.com
+ajs dms clean --all
+```
+
+`ajs dms <command>` and `ajs-dms <command>` are the same program; the delegation
+only saves you from remembering a second executable name. Package scripts should
+call `ajs-dms` directly so they do not depend on the CLI being installed.
+`--help`, `--version` and `clean` run from any directory. `prepare` also runs
+anywhere: with no backend in reach it warns and exits 0, so a frontend module's
+`postinstall` hook never fails an install, and the generated types are refreshed
+later from a development environment. `dev`, `build` and `start` need a backend
+URL, either through `-b` or through the enclosing antelope project's
+`.antelope/dev.json`, and say so on exit 1 when they have neither;
+`verify-source` needs `--layer` instead.
+
+The CLI checks npm for a newer release at most once a day — a failed lookup
+counts as the day's attempt — and prints a one-line notice on stderr. The
+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`.
+
+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.
+
+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.
+
+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.
+
+## Frontend modules
+
+A materialized module opts into the Vue adapter with a root `dms.frontend.ts`:
+
+```ts
+import MyBlock from "./components/MyBlock.vue";
+import MyPage from "./pages/MyPage.vue";
+import type { DmsFrontendModule } from "../../frontend-module";
+
+const frontendModule: DmsFrontendModule = {
+  setup(sdk) {
+    sdk.registerComponent("MyBlock", MyBlock);
+    sdk.registerPage("default", MyPage);
+  },
+};
+
+export default frontendModule;
+```
+
+The SDK also exposes `use` for Vue plugins. Entries execute by descending manifest priority, then stable module id. Modules without `dms.frontend.ts` are skipped by the generated loader. Registered page keys match a route's `fullSlug`, request path, or `default`; unregistered pages and components use the generic card renderer.
+
+## 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.
+
+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.
+
+## Rendering model
+
+The Node server renders full-page requests through the Vite SSR bundle and sends
+the matching Inertia page object to the browser for hydration. Subsequent
+`X-Inertia` visits receive page objects and render client-side. Client-only
+plugins and `DmsClientOnly` defer browser-only work while the same generated
+frontend-module registry drives server and client entries.
+
+## Options
+
+| Option | Environment | Purpose |
+| --- | --- | --- |
+| `-b, --backend-url` | `DMS_BACKEND_URL` | DMS backend URL |
+| `-p, --port` | `PORT` | Frontend port, default `3001` |
+| `-f, --force` | | Reinstall workspace dependencies |
+| `--offline` | `DMS_OFFLINE` | Reuse cached manifest and archives |
+| `--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`) |
+
+Use pnpm for all repository and workspace operations.
+
+## Verify local frontend modules
+
+Use the packaged source verifier to validate an unpublished DMS frontend package against this exact adapter version. Additional modules and local package bindings are repeatable. All supplied frontend packages are copied into the generated workspace and bound with `workspace:*`.
+
+```bash
+ajs dms verify-source \
+  --layer /path/to/dms/frontend-vue \
+  --module /path/to/module/frontend-vue \
+  --local-package @antelopejs/dms=/path/to/dms
+```
+
+The verifier prints its generated workspace path, builds client, SSR, and email bundles, runs `vue-tsc`, renders eight DMS email templates, and checks that the email bundle excludes browser-only modules. It leaves the generated workspace in the temporary directory for inspection. It does not start a backend or publish packages. Repository development can invoke the same runner with `DMS_LAYER_SOURCE` through `pnpm test:real-source`.
+
+Refresh rotation is single-flight within one frontend process. Horizontally scaled deployments must use sticky routing so a browser reaches the same process, or replace this process-local behavior with an external session adapter. It does not provide a distributed rotation guarantee.

package/dist/commands/build.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmdBuild = cmdBuild;
+const node_path_1 = require("node:path");
+const chalk_1 = __importDefault(require("chalk"));
+const commander_1 = require("commander");
+const common_1 = require("../common");
+const cli_ui_1 = require("../utils/cli-ui");
+function cmdBuild() {
+    return new commander_1.Command("build")
+        .description("Build for production (downloads layers via ZIP from backend)")
+        .addOption(common_1.Options.backendUrl)
+        .addOption(common_1.Options.force)
+        .addOption(common_1.Options.offline)
+        .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.");
+            process.exit(1);
+        }
+        const spinner = new cli_ui_1.Spinner("Setting up workspace...");
+        await spinner.start();
+        try {
+            const { workspaceDir, manifestFromCache, manifestFetchedAt } = await (0, common_1.setupWorkspace)({
+                backendUrl: options.backendUrl,
+                force: !!options.force,
+                mode: "build",
+                offline: options.offline,
+                bootstrapSecret: (0, common_1.normalizeBootstrapSecret)(options.bootstrapSecret),
+            });
+            await spinner.succeed("Workspace ready");
+            if (manifestFromCache) {
+                (0, cli_ui_1.warning)(`Building from cached manifest and layers archive${manifestFetchedAt ? ` (cached on ${manifestFetchedAt})` : ""} — output may not match the current backend`);
+            }
+            console.log("");
+            (0, cli_ui_1.info)("Building for production...");
+            console.log(chalk_1.default.dim(`  Workspace: ${workspaceDir}`));
+            console.log("");
+            const nodeModulesDir = (0, node_path_1.join)(workspaceDir, "node_modules");
+            const code = await (0, common_1.runCommand)("pnpm", ["run", "build"], {
+                cwd: workspaceDir,
+                env: {
+                    ...process.env,
+                    NODE_OPTIONS: "--max-old-space-size=4096",
+                    NODE_PATH: nodeModulesDir,
+                },
+            });
+            if (code === 0) {
+                console.log("");
+                (0, cli_ui_1.success)("Build completed successfully!");
+                console.log(chalk_1.default.dim("  Run 'ajs-dms start' to start the production server"));
+            }
+            else {
+                (0, cli_ui_1.error)("Build failed");
+            }
+            process.exit(code);
+        }
+        catch (err) {
+            await spinner.fail(`Setup failed: ${err.message}`);
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/clean.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmdClean = cmdClean;
+const node_fs_1 = require("node:fs");
+const commander_1 = require("commander");
+const common_1 = require("../common");
+const cli_ui_1 = require("../utils/cli-ui");
+function cmdClean() {
+    return new commander_1.Command("clean")
+        .description("Remove workspace build artifacts")
+        .addOption(common_1.Options.backendUrl)
+        .option("-a, --all", "Clean all workspaces")
+        .action(async (options) => {
+        console.log("");
+        if (options.all) {
+            (0, cli_ui_1.info)("Cleaning all workspaces...");
+            const workspaces = (0, common_1.listWorkspaces)();
+            if (workspaces.length === 0) {
+                (0, cli_ui_1.info)("No workspaces found.");
+                return;
+            }
+            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})`);
+            }
+            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.");
+            process.exit(1);
+        }
+        const workspaceDir = (0, common_1.getWorkspaceDir)(options.backendUrl);
+        if (!(0, node_fs_1.existsSync)(workspaceDir)) {
+            (0, cli_ui_1.info)("Workspace not found — nothing to clean.");
+            return;
+        }
+        (0, node_fs_1.rmSync)(workspaceDir, { recursive: true, force: true });
+        (0, cli_ui_1.success)(`Removed workspace: ${workspaceDir}`);
+    });
+}

package/dist/commands/dev.js

@@ -0,0 +1,116 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmdDev = cmdDev;
+const node_path_1 = require("node:path");
+const chalk_1 = __importDefault(require("chalk"));
+const commander_1 = require("commander");
+const common_1 = require("../common");
+const discovery_1 = require("../discovery");
+const ports_1 = require("../ports");
+const cli_ui_1 = require("../utils/cli-ui");
+function clientHost() {
+    const host = process.env.HOST?.trim();
+    if (!host || host === "0.0.0.0" || host === "::" || host === "[::]") {
+        return "localhost";
+    }
+    return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+}
+function resolveBackend(options) {
+    if (options.backendUrl) {
+        return { backendUrl: options.backendUrl };
+    }
+    const result = (0, discovery_1.discoverBackend)(process.cwd());
+    if (result.status !== "found") {
+        (0, cli_ui_1.error)((0, discovery_1.describeDiscoveryFailure)(result));
+        process.exit(1);
+    }
+    (0, cli_ui_1.info)(`Backend discovered from ${chalk_1.default.cyan(result.backend.projectDir)}: ${chalk_1.default.cyan(result.backend.backendUrl)}`);
+    return {
+        backendUrl: result.backend.backendUrl,
+        workspaceKey: (0, common_1.projectWorkspaceKey)(result.backend.projectDir),
+    };
+}
+function cmdDev() {
+    return new commander_1.Command("dev")
+        .description("Start development server with hot reload (direct paths, same machine)")
+        .addOption(common_1.Options.backendUrl)
+        .addOption(common_1.Options.port)
+        .addOption(common_1.Options.force)
+        .addOption(common_1.Options.offline)
+        .addOption(common_1.Options.bootstrapSecret)
+        .action(async (options) => {
+        const { backendUrl, workspaceKey } = resolveBackend(options);
+        const bootstrapSecret = (0, common_1.resolveBootstrapSecret)(options.bootstrapSecret, backendUrl);
+        const requestedPort = Number.parseInt(options.port, 10);
+        if (Number.isNaN(requestedPort)) {
+            (0, cli_ui_1.error)(`Invalid port: ${options.port}`);
+            process.exit(1);
+        }
+        let reserved;
+        try {
+            reserved = await (0, ports_1.reserveFreePort)(requestedPort);
+        }
+        catch (err) {
+            (0, cli_ui_1.error)(err.message);
+            process.exit(1);
+        }
+        const port = reserved.port;
+        if (port !== requestedPort) {
+            (0, cli_ui_1.warning)(`Port ${requestedPort} in use, using ${port} instead`);
+        }
+        const clientUrl = `http://${clientHost()}:${port}`;
+        const spinner = new cli_ui_1.Spinner("Setting up workspace...");
+        await spinner.start();
+        try {
+            const { workspaceDir, layers, manifestFromCache, manifestFetchedAt } = await (0, common_1.setupWorkspace)({
+                backendUrl,
+                force: !!options.force,
+                mode: "dev",
+                offline: options.offline,
+                clientUrl,
+                workspaceKey,
+                bootstrapSecret,
+            });
+            await spinner.succeed("Workspace ready");
+            if (manifestFromCache) {
+                (0, cli_ui_1.warning)(`Using cached layers manifest${manifestFetchedAt ? ` (cached on ${manifestFetchedAt})` : ""} — API calls will fail until the backend is up`);
+            }
+            const stopWatchers = (0, common_1.startLayerWatchers)(workspaceDir, layers);
+            const handleShutdown = async () => {
+                await stopWatchers();
+            };
+            process.once("SIGINT", handleShutdown);
+            process.once("SIGTERM", handleShutdown);
+            console.log("");
+            (0, cli_ui_1.info)(`Starting dev server on port ${chalk_1.default.cyan(String(port))}...`);
+            console.log(chalk_1.default.dim(`  Workspace: ${workspaceDir}`));
+            console.log(chalk_1.default.dim(`  Backend:   ${backendUrl}`));
+            console.log(chalk_1.default.dim(`  Watching:  ${layers.length} layer source tree(s)`));
+            console.log("");
+            const nodeModulesDir = (0, node_path_1.join)(workspaceDir, "node_modules");
+            await reserved.release();
+            const code = await (0, common_1.runCommand)("node", ["server.mjs"], {
+                cwd: workspaceDir,
+                env: {
+                    ...process.env,
+                    PORT: String(port),
+                    DMS_DEV: "true",
+                    DMS_COOKIE_SECURE: process.env.DMS_COOKIE_SECURE ?? "false",
+                    DMS_BACKEND_URL: backendUrl,
+                    DMS_BOOTSTRAP_SECRET: bootstrapSecret,
+                    NODE_OPTIONS: "--max-old-space-size=4096",
+                    NODE_PATH: nodeModulesDir,
+                },
+            });
+            await stopWatchers();
+            process.exit(code);
+        }
+        catch (err) {
+            await spinner.fail(`Setup failed: ${err.message}`);
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/prepare.js

@@ -0,0 +1,60 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmdPrepare = cmdPrepare;
+const chalk_1 = __importDefault(require("chalk"));
+const commander_1 = require("commander");
+const common_1 = require("../common");
+const cli_ui_1 = require("../utils/cli-ui");
+function cmdPrepare() {
+    return new commander_1.Command("prepare")
+        .description("Prepare the generated Vite workspace and frontend-module registry")
+        .addOption(common_1.Options.backendUrl)
+        .addOption(common_1.Options.force)
+        .addOption(common_1.Options.offline)
+        .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.");
+            process.exit(0);
+        }
+        const spinner = new cli_ui_1.Spinner("Setting up workspace...");
+        await spinner.start();
+        let workspaceDir;
+        let manifestFromCache;
+        let manifestFetchedAt;
+        try {
+            const result = await (0, common_1.setupWorkspace)({
+                backendUrl: options.backendUrl,
+                force: !!options.force,
+                mode: "dev",
+                offline: options.offline,
+                bootstrapSecret: (0, common_1.resolveBootstrapSecret)(options.bootstrapSecret, options.backendUrl),
+            });
+            workspaceDir = result.workspaceDir;
+            manifestFromCache = result.manifestFromCache;
+            manifestFetchedAt = result.manifestFetchedAt;
+        }
+        catch (err) {
+            await spinner.warn(`Skipping prepare: ${err.message}`);
+            process.exit(0);
+        }
+        await spinner.succeed("Workspace ready");
+        if (manifestFromCache) {
+            const cachedOn = manifestFetchedAt
+                ? ` (cached on ${manifestFetchedAt})`
+                : "";
+            if (options.offline) {
+                (0, cli_ui_1.info)(`Offline mode — using cached frontend-module manifest${cachedOn}`);
+            }
+            else {
+                (0, cli_ui_1.warning)(`Backend unreachable — using cached frontend-module manifest${cachedOn}`);
+            }
+        }
+        console.log("");
+        (0, cli_ui_1.success)(`Vite workspace prepared ${chalk_1.default.dim(`(${workspaceDir})`)}`);
+        process.exit(0);
+    });
+}

package/dist/commands/start.js

@@ -0,0 +1,49 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmdStart = cmdStart;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const chalk_1 = __importDefault(require("chalk"));
+const commander_1 = require("commander");
+const common_1 = require("../common");
+const cli_ui_1 = require("../utils/cli-ui");
+function cmdStart() {
+    return new commander_1.Command("start")
+        .description("Start the production server from a built workspace")
+        .addOption(common_1.Options.backendUrl)
+        .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.");
+            process.exit(1);
+        }
+        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");
+        if (!(0, node_fs_1.existsSync)(serverPath) || !(0, node_fs_1.existsSync)(clientPath)) {
+            console.log("");
+            (0, cli_ui_1.error)("Production build not found!");
+            console.log(chalk_1.default.dim("  Run 'ajs-dms build -b " +
+                options.backendUrl +
+                "' first to create a production build"));
+            process.exit(1);
+        }
+        console.log("");
+        (0, cli_ui_1.info)(`Starting production server on port ${chalk_1.default.cyan(options.port)}...`);
+        console.log(chalk_1.default.dim(`  Workspace: ${workspaceDir}`));
+        console.log("");
+        const code = await (0, common_1.runCommand)("node", [serverPath], {
+            cwd: workspaceDir,
+            env: {
+                ...process.env,
+                PORT: options.port,
+                DMS_BACKEND_URL: options.backendUrl,
+                DMS_COOKIE_SECURE: process.env.DMS_COOKIE_SECURE ?? "true",
+            },
+        });
+        process.exit(code);
+    });
+}