@antelopejs/dms-frontend 0.2.2 → 0.2.4

package/README.md

@@ -94,9 +94,11 @@ 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
+The CLI checks npm for a newer release at most once a day and prints a one-line
+notice on stderr. A lookup that comes back empty — offline, throttled, or simply
+raced by a command that blocked the event loop past the deadline — is retried
+after an hour instead of counting as the day's attempt. 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.
 
@@ -131,6 +133,34 @@ 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.
 
+### Layer aliases outside the workspace
+
+Every layer a module ships under `layers/<name>/` answers to `#<name>` inside
+the generated workspace. That convention is exported, so a module's own tooling
+can reuse it instead of restating it — a unit test runs the module's Vue
+sources outside the workspace, where nothing otherwise supplies `#dms-core` or
+`#dms-ui`:
+
+```ts
+// vitest.config.ts, in a DMS frontend module
+import { frontendLayerAliases } from "@antelopejs/dms-frontend/common";
+
+export default defineConfig({
+  resolve: {
+    alias: frontendLayerAliases(
+      resolve(__dirname, ".antelope/cache/@antelopejs/dms/frontend-vue"),
+    ),
+  },
+});
+```
+
+`frontendLayerAliases` reads a module root on disk and needs no backend,
+manifest or materialized workspace. `frontendLayerTypePaths` returns the same
+layers in tsconfig `paths` shape, and `resolveFrontendLayers` is the primitive
+behind both. Pass several module roots in increasing precedence to overlay
+them: when two modules expose a layer of the same name, the last one wins,
+which is the order the loader itself materializes them in.
+
 ## 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, or in the project's `.env`, rather than passing credentials on the command line.

package/dist/commands/build.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function cmdBuild(): Command;

package/dist/commands/clean.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function cmdClean(): Command;

package/dist/commands/dev.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function cmdDev(): Command;

package/dist/commands/prepare.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function cmdPrepare(): Command;

package/dist/commands/start.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function cmdStart(): Command;

package/dist/commands/verify-source.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function parseLocalPackages(values: string[]): Record<string, string>;
+export declare function cmdVerifySource(): Command;

package/dist/common.d.ts

@@ -0,0 +1,9 @@
+export * from "./config";
+export * from "./layers";
+export * from "./layer-aliases";
+export * from "./manifest";
+export * from "./fs-sync";
+export * from "./layer-watch";
+export * from "./materialize";
+export * from "./workspace";
+export * from "./workspace-setup";

package/dist/common.js

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./config"), exports);
 __exportStar(require("./layers"), exports);
+__exportStar(require("./layer-aliases"), exports);
 __exportStar(require("./manifest"), exports);
 __exportStar(require("./fs-sync"), exports);
 __exportStar(require("./layer-watch"), exports);

package/dist/config.d.ts

@@ -0,0 +1,31 @@
+import { Option } from "commander";
+import ignore from "ignore";
+import { type DiscoveryOptions } from "./discovery";
+export declare const DMS_FRONTEND_HOME: string;
+export declare const DEPS_HASH_FILE = ".deps-hash";
+export declare const WORKSPACE_DIR_MODE = 448;
+export declare function writeSecretBearingFile(file: string, content: string): void;
+export declare const TEMPLATE_FILES: ReadonlyArray<readonly [string, string]>;
+export declare const LAYERS_SUBDIR = "frontend-modules";
+export declare const FRONTEND_MODULE_ENTRY = "dms.frontend.ts";
+export declare const AUTH_ESTABLISH_FILE = "generated-auth-establish.json";
+export declare const LAYER_COPY_BLOCKLIST: readonly string[];
+export declare const layerCopyIgnore: ignore.Ignore;
+export declare const PNPM_LIFECYCLE_SCRIPTS: readonly string[];
+export declare const TAILWIND_SOURCE_GLOB = "**/*.{vue,ts,tsx,js,jsx,mjs,cjs}";
+export declare const Options: {
+    backendUrl: Option;
+    port: Option;
+    force: Option;
+    readonly offline: Option;
+    bootstrapSecret: Option;
+};
+export interface BootstrapDiscoveryOptions extends DiscoveryOptions {
+    cwd?: string;
+}
+export declare function normalizeBootstrapSecret(value: string | undefined, source?: string): string | undefined;
+export type SessionSecretMode = "dev" | "build" | "start";
+export declare function resolveSessionSecret(mode: SessionSecretMode, value?: string | undefined): string;
+export declare function resolveBootstrapSecret(explicit: string | undefined, backendUrl: string, options?: BootstrapDiscoveryOptions): string | undefined;
+export declare function sha256Hex(input: string): string;
+export declare function canonicalizeBackendUrl(backendUrl: string): string;

package/dist/discovery.d.ts

@@ -0,0 +1,48 @@
+export interface DevRegistryEndpoint {
+    protocol: string;
+    host: string;
+    port: number;
+}
+export interface DevRegistry {
+    pid: number;
+    startedAt?: string;
+    servers: Record<string, {
+        endpoints: DevRegistryEndpoint[];
+    }>;
+}
+export declare const DEV_REGISTRY_RELATIVE_PATH: string;
+export interface DiscoveredBackend {
+    projectDir: string;
+    registry: DevRegistry;
+    backendUrl: string;
+}
+export interface DiscoveryOptions {
+    isPidAlive?: (pid: number) => boolean;
+}
+export declare function isPidAlive(pid: number): boolean;
+export declare function buildBackendUrl(endpoint: DevRegistryEndpoint): string;
+export type DiscoveryResult = {
+    status: "found";
+    backend: DiscoveredBackend;
+} | {
+    status: "not-found";
+} | {
+    status: "stale";
+    projectDir: string;
+    pid: number;
+} | {
+    status: "no-api-endpoint";
+    projectDir: string;
+} | {
+    status: "malformed";
+    projectDir: string;
+};
+export declare function discoverBackend(cwd: string, options?: DiscoveryOptions): DiscoveryResult;
+export declare function describeDiscoveryFailure(result: DiscoveryResult): string;
+export interface DevHandshake {
+    pid: number;
+    bootstrapSecret: string;
+    updatedAt?: string;
+}
+export declare const DEV_HANDSHAKE_RELATIVE_PATH: string;
+export declare function readDevBootstrapCredential(projectDir: string, options?: DiscoveryOptions): string | undefined;

package/dist/env-file.d.ts

@@ -0,0 +1,7 @@
+export declare const ENV_FILE_NAMES: readonly [".env.local", ".env"];
+export interface LoadProjectEnvOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    onWarning?: (message: string) => void;
+}
+export declare function loadProjectEnv(options?: LoadProjectEnvOptions): string[];

package/dist/fs-sync.d.ts

@@ -0,0 +1,9 @@
+export declare function stripExtendedLengthPrefix(p: string): string;
+export declare function toPosixPath(path: string, separator?: string): string;
+export declare function isBlocklistedCopyPath(src: string, srcPath: string): boolean;
+export declare function sanitizedPackageContent(raw: string): string;
+export declare function filesIdentical(srcPath: string, destPath: string): boolean;
+export declare function applyContent(content: string, destPath: string): void;
+export declare function applyFile(srcPath: string, destPath: string): void;
+export declare function collectFiles(dir: string, baseDir?: string): string[];
+export declare function syncDirectories(src: string, dest: string): void;

package/dist/fs-sync.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stripExtendedLengthPrefix = stripExtendedLengthPrefix;
+exports.toPosixPath = toPosixPath;
 exports.isBlocklistedCopyPath = isBlocklistedCopyPath;
 exports.sanitizedPackageContent = sanitizedPackageContent;
 exports.filesIdentical = filesIdentical;
@@ -18,11 +19,14 @@ const config_1 = require("./config");
 function stripExtendedLengthPrefix(p) {
     return p.replace(/^\\\\\?\\/, "");
 }
+function toPosixPath(path, separator = node_path_1.sep) {
+    return separator === "/" ? path : path.split(separator).join("/");
+}
 function isBlocklistedCopyPath(src, srcPath) {
     const rel = (0, node_path_1.relative)((0, node_path_1.resolve)(stripExtendedLengthPrefix(src)), (0, node_path_1.resolve)(stripExtendedLengthPrefix(srcPath)));
     if (!rel || rel.startsWith(".."))
         return false;
-    return config_1.layerCopyIgnore.ignores(rel.split(node_path_1.sep).join("/"));
+    return config_1.layerCopyIgnore.ignores(toPosixPath(rel));
 }
 function sanitizedPackageContent(raw) {
     const pkg = JSON.parse(raw);

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/layer-aliases.d.ts

@@ -0,0 +1,12 @@
+export declare const MODULE_LAYERS_DIRNAME = "layers";
+export interface FrontendLayer {
+    name: string;
+    alias: string;
+    directory: string;
+}
+export interface FrontendLayerPathOptions {
+    relativeTo?: string;
+}
+export declare function resolveFrontendLayers(moduleRoots: string | readonly string[]): FrontendLayer[];
+export declare function frontendLayerAliases(moduleRoots: string | readonly string[]): Record<string, string>;
+export declare function frontendLayerTypePaths(moduleRoots: string | readonly string[], options?: FrontendLayerPathOptions): Record<string, string[]>;

package/dist/layer-aliases.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MODULE_LAYERS_DIRNAME = void 0;
+exports.resolveFrontendLayers = resolveFrontendLayers;
+exports.frontendLayerAliases = frontendLayerAliases;
+exports.frontendLayerTypePaths = frontendLayerTypePaths;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const fs_sync_1 = require("./fs-sync");
+exports.MODULE_LAYERS_DIRNAME = "layers";
+const LAYER_ALIAS_PREFIX = "#";
+function isDirectory(path) {
+    try {
+        return (0, node_fs_1.statSync)(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function readModuleLayers(moduleRoot) {
+    const layersRoot = (0, node_path_1.join)((0, node_path_1.resolve)(moduleRoot), exports.MODULE_LAYERS_DIRNAME);
+    if (!(0, node_fs_1.existsSync)(layersRoot))
+        return [];
+    return (0, node_fs_1.readdirSync)(layersRoot)
+        .map((name) => ({
+        name,
+        alias: `${LAYER_ALIAS_PREFIX}${name}`,
+        directory: (0, node_path_1.join)(layersRoot, name),
+    }))
+        .filter((layer) => isDirectory(layer.directory));
+}
+function resolveFrontendLayers(moduleRoots) {
+    const roots = typeof moduleRoots === "string" ? [moduleRoots] : moduleRoots;
+    const layers = new Map();
+    for (const root of roots) {
+        for (const layer of readModuleLayers(root)) {
+            layers.set(layer.name, layer);
+        }
+    }
+    return [...layers.values()];
+}
+function frontendLayerAliases(moduleRoots) {
+    return Object.fromEntries(resolveFrontendLayers(moduleRoots).map((layer) => [
+        layer.alias,
+        layer.directory,
+    ]));
+}
+function frontendLayerTypePaths(moduleRoots, options = {}) {
+    const base = options.relativeTo;
+    return Object.fromEntries(resolveFrontendLayers(moduleRoots).map((layer) => {
+        const target = base === undefined
+            ? (0, fs_sync_1.toPosixPath)(layer.directory)
+            : (0, fs_sync_1.toPosixPath)((0, node_path_1.relative)((0, node_path_1.resolve)(base), layer.directory));
+        const specifier = base === undefined || target.startsWith("..") ? target : `./${target}`;
+        return [`${layer.alias}/*`, [`${specifier}/*`]];
+    }));
+}

package/dist/layer-watch.d.ts

@@ -0,0 +1,2 @@
+import { ResolvedLayer } from "./workspace";
+export declare function startLayerWatchers(workspaceDir: string, layers: ResolvedLayer[]): () => Promise<void>;

package/dist/layers.d.ts

@@ -0,0 +1,9 @@
+import { ServedWithPath } from "./manifest";
+import { ManifestModule, ResolvedLayer } from "./workspace";
+export declare function assertLayerPathsServed(modules: ManifestModule[]): asserts modules is ServedWithPath[];
+export declare function assertCachedArchivesExist(modules: ManifestModule[], cacheDir: string, fetchedAt?: string): void;
+export declare function buildLayersFromPaths(modules: ManifestModule[]): ResolvedLayer[];
+export declare function downloadAndExtractLayers(backendUrl: string, packUrl: string, cacheDir: string, force: boolean, bootstrapSecret?: string): Promise<void>;
+export declare function buildLayersFromCache(modules: ManifestModule[], cacheDir: string): Promise<ResolvedLayer[]>;
+export declare function getLayerSafeName(layer: ResolvedLayer): string;
+export declare function getLayerWorkspacePath(workspaceDir: string, layer: ResolvedLayer): string;

package/dist/manifest.d.ts

@@ -0,0 +1,22 @@
+import { Manifest, ManifestModule } from "./workspace";
+export declare class ManifestUnauthorizedError extends Error {
+    readonly url: string;
+    readonly status: number;
+    constructor(url: string, status: number);
+}
+export declare function fetchManifest(backendUrl: string, clientUrl?: string, bootstrapSecret?: string): Promise<Manifest>;
+export interface ManifestCacheEntry {
+    manifest: Manifest;
+    fetchedAt: string;
+}
+export declare function readCachedManifest(workspaceDir: string): ManifestCacheEntry | undefined;
+export interface ResolvedManifest {
+    manifest: Manifest;
+    fromCache: boolean;
+    fetchedAt?: string;
+}
+export declare function resolveManifest(workspaceDir: string, backendUrl: string, offline: boolean, clientUrl?: string, bootstrapSecret?: string): Promise<ResolvedManifest>;
+export declare function assertCachedLayerPathsExist(modules: ServedWithPath[], fetchedAt?: string): void;
+export type ServedWithPath = ManifestModule & {
+    path: string;
+};

package/dist/materialize.d.ts

@@ -0,0 +1,20 @@
+import { FrontendModuleOptions, ResolvedLayer } from "./workspace";
+export declare function getPackageRoot(): string;
+export declare function copyStaticTemplates(workspaceDir: string): void;
+export declare function writeWorkspacePackageJson(workspaceDir: string, layers: ResolvedLayer[]): void;
+export declare function materializeLayers(workspaceDir: string, layers: ResolvedLayer[]): void;
+export interface FrontendModuleRegistryEntry {
+    id: string;
+    packageName?: string;
+    root: string;
+    priority: number;
+    entry?: string;
+    options: FrontendModuleOptions;
+}
+export interface FrontendModuleRegistry {
+    modules: FrontendModuleRegistryEntry[];
+}
+export declare function createFrontendModuleRegistry(workspaceDir: string, layers: ResolvedLayer[]): FrontendModuleRegistry;
+export declare function collectAuthEstablishEndpoints(layers: ResolvedLayer[]): string[];
+export declare function writeFrontendModuleRegistry(workspaceDir: string, layers: ResolvedLayer[]): void;
+export declare function writeDmsMainCss(workspaceDir: string, layers: ResolvedLayer[]): void;

package/dist/materialize.js

@@ -11,6 +11,7 @@ exports.writeDmsMainCss = writeDmsMainCss;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const config_1 = require("./config");
+const layer_aliases_1 = require("./layer-aliases");
 const layers_1 = require("./layers");
 const fs_sync_1 = require("./fs-sync");
 function getPackageRoot() {
@@ -142,17 +143,8 @@ function writeFrontendTypePaths(workspaceDir, registry) {
     const paths = {
         "#dms/frontend-module": ["./frontend-module.ts"],
         "@frontend/*": ["./frontend-modules/*"],
+        ...(0, layer_aliases_1.frontendLayerTypePaths)([...registry.modules].reverse().map((module) => module.root), { relativeTo: workspaceDir }),
     };
-    [...registry.modules].reverse().forEach((module) => {
-        const layersRoot = (0, node_path_1.join)(module.root, "layers");
-        if (!(0, node_fs_1.existsSync)(layersRoot))
-            return;
-        (0, node_fs_1.readdirSync)(layersRoot).forEach((name) => {
-            paths[`#${name}/*`] = [
-                `./frontend-modules/${module.id}/layers/${name}/*`,
-            ];
-        });
-    });
     const config = { compilerOptions: { paths } };
     (0, node_fs_1.writeFileSync)((0, node_path_1.join)(workspaceDir, "frontend-paths.generated.json"), `${JSON.stringify(config, null, 2)}\n`);
 }
@@ -198,7 +190,7 @@ function discoverAssets(registry, directory, extensions) {
                 .sort()
                 .map((relativePath) => ({
                 moduleId: module.id,
-                relativePath: `${assetRoot.relativePrefix}${(0, node_path_1.join)(directory, relativePath).split(node_path_1.sep).join("/")}`,
+                relativePath: `${assetRoot.relativePrefix}${(0, fs_sync_1.toPosixPath)((0, node_path_1.join)(directory, relativePath))}`,
             }));
         });
     });
@@ -259,7 +251,7 @@ function writeShortcutExports(workspaceDir, registry) {
 }
 function writeDmsMainCss(workspaceDir, layers) {
     const sources = layers
-        .map((layer) => `@source "${(0, layers_1.getLayerWorkspacePath)(workspaceDir, layer)}/${config_1.TAILWIND_SOURCE_GLOB}";`)
+        .map((layer) => `@source "${(0, fs_sync_1.toPosixPath)((0, layers_1.getLayerWorkspacePath)(workspaceDir, layer))}/${config_1.TAILWIND_SOURCE_GLOB}";`)
         .join("\n");
     const content = `@import "tailwindcss";
 @import "@nuxt/ui";

package/dist/ports.d.ts

@@ -0,0 +1,6 @@
+export declare const PORT_FALLBACK_RANGE = 20;
+export interface ReservedPort {
+    port: number;
+    release: () => Promise<void>;
+}
+export declare function reserveFreePort(preferred: number, range?: number): Promise<ReservedPort>;

package/dist/update-check.d.ts

@@ -0,0 +1,19 @@
+export declare const UPDATE_CHECK_PACKAGE = "@antelopejs/dms-frontend";
+export declare const UPDATE_CHECK_INTERVAL_MS: number;
+export declare const UPDATE_CHECK_RETRY_INTERVAL_MS: number;
+export declare const UPDATE_CHECK_TIMEOUT_MS = 3000;
+export declare const NO_UPDATE_CHECK_FLAG = "--no-update-check";
+export interface UpdateCheckOptions {
+    currentVersion: string;
+    argv?: readonly string[];
+    env?: NodeJS.ProcessEnv;
+    now?: () => number;
+    cacheFile?: string;
+    fetchLatestVersion?: (packageName: string) => Promise<string | undefined>;
+    write?: (message: string) => void;
+}
+export declare function stripUpdateCheckFlag(argv: readonly string[]): string[];
+export declare function isUpdateCheckEnabled(argv: readonly string[], env: NodeJS.ProcessEnv): boolean;
+export declare function updateCheckCacheFile(): string;
+export declare function fetchLatestVersionFromRegistry(packageName: string, registryUrl?: string, timeoutMs?: number): Promise<string | undefined>;
+export declare function checkForUpdate(options: UpdateCheckOptions): Promise<void>;

package/dist/update-check.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NO_UPDATE_CHECK_FLAG = exports.UPDATE_CHECK_TIMEOUT_MS = exports.UPDATE_CHECK_INTERVAL_MS = exports.UPDATE_CHECK_PACKAGE = void 0;
+exports.NO_UPDATE_CHECK_FLAG = exports.UPDATE_CHECK_TIMEOUT_MS = exports.UPDATE_CHECK_RETRY_INTERVAL_MS = exports.UPDATE_CHECK_INTERVAL_MS = exports.UPDATE_CHECK_PACKAGE = void 0;
 exports.stripUpdateCheckFlag = stripUpdateCheckFlag;
 exports.isUpdateCheckEnabled = isUpdateCheckEnabled;
 exports.updateCheckCacheFile = updateCheckCacheFile;
@@ -18,6 +18,7 @@ const config_1 = require("./config");
 exports.UPDATE_CHECK_PACKAGE = "@antelopejs/dms-frontend";
 const DEFAULT_REGISTRY_URL = "https://registry.npmjs.org/";
 exports.UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+exports.UPDATE_CHECK_RETRY_INTERVAL_MS = 60 * 60 * 1000;
 exports.UPDATE_CHECK_TIMEOUT_MS = 3000;
 exports.NO_UPDATE_CHECK_FLAG = "--no-update-check";
 const HELP_OR_VERSION_FLAGS = ["--help", "-h", "--version", "-v"];
@@ -73,7 +74,11 @@ function readCache(file) {
         if (latestVersion !== undefined && typeof latestVersion !== "string") {
             return undefined;
         }
-        return { checkedAt: parsed.checkedAt, latestVersion };
+        const succeeded = parsed.succeeded;
+        if (succeeded !== undefined && typeof succeeded !== "boolean") {
+            return undefined;
+        }
+        return { checkedAt: parsed.checkedAt, latestVersion, succeeded };
     }
     catch {
         return undefined;
@@ -156,13 +161,20 @@ async function checkForUpdate(options) {
             return;
         const cached = readCache(cacheFile);
         const checkedAt = now();
-        const withinInterval = cached !== undefined &&
-            checkedAt - cached.checkedAt < exports.UPDATE_CHECK_INTERVAL_MS;
+        const lastAttemptAnswered = cached?.succeeded ?? cached?.latestVersion !== undefined;
+        const interval = lastAttemptAnswered
+            ? exports.UPDATE_CHECK_INTERVAL_MS
+            : exports.UPDATE_CHECK_RETRY_INTERVAL_MS;
+        const withinInterval = cached !== undefined && checkedAt - cached.checkedAt < interval;
         let latestVersion = cached?.latestVersion;
         if (!withinInterval) {
-            latestVersion =
-                (await fetchLatestVersion(exports.UPDATE_CHECK_PACKAGE)) ?? latestVersion;
-            writeCache(cacheFile, { checkedAt, latestVersion });
+            const published = await fetchLatestVersion(exports.UPDATE_CHECK_PACKAGE);
+            latestVersion = published ?? latestVersion;
+            writeCache(cacheFile, {
+                checkedAt,
+                latestVersion,
+                succeeded: published !== undefined,
+            });
         }
         if (latestVersion && isNewer(currentVersion, latestVersion)) {
             write(formatNotice(currentVersion, latestVersion));

package/dist/utils/cli-ui.d.ts

@@ -0,0 +1,27 @@
+import { type Options as BoxenOptions } from "boxen";
+export declare class Spinner {
+    private text;
+    private isRunning;
+    private interval?;
+    private currentCharIndex;
+    private isTerminal;
+    constructor(text: string);
+    start(text?: string): Promise<Spinner>;
+    update(text: string): Spinner;
+    log(stream: NodeJS.WriteStream, message: string): Spinner;
+    succeed(text?: string): Promise<void>;
+    fail(text?: string): Promise<void>;
+    info(text?: string): Promise<void>;
+    warn(text?: string): Promise<void>;
+    pause(): Promise<void>;
+    stop(): Promise<void>;
+    clear(): Promise<void>;
+}
+export declare function displayBox(message: string, title?: string, options?: BoxenOptions): void;
+export declare function displayBanner(text: string, font?: string): void;
+export declare function success(message: string): void;
+export declare function error(message: string): void;
+export declare function warning(message: string): void;
+export declare function info(message: string): void;
+export declare function header(text: string): void;
+export declare function keyValue(key: string, value: string | number | boolean): string;

package/dist/verify-source-runner.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/workspace-setup.d.ts

@@ -0,0 +1,23 @@
+import { type SpawnOptions } from "node:child_process";
+import { ResolvedLayer } from "./workspace";
+export declare function computeDepsHash(layerPaths: string[], workspacePackage?: string): string;
+export declare function needsInstall(workspaceDir: string, layerPaths: string[], force: boolean): boolean;
+export declare function saveDepsHash(workspaceDir: string, layerPaths: string[]): void;
+export declare function installDeps(workspaceDir: string): void;
+export declare function runCommand(command: string, args: string[], options?: SpawnOptions): Promise<number>;
+export interface SetupWorkspaceOptions {
+    backendUrl: string;
+    force: boolean;
+    mode: "dev" | "build";
+    offline?: boolean;
+    clientUrl?: string;
+    workspaceKey?: string;
+    bootstrapSecret?: string;
+}
+export interface SetupWorkspaceResult {
+    workspaceDir: string;
+    layers: ResolvedLayer[];
+    manifestFromCache: boolean;
+    manifestFetchedAt?: string;
+}
+export declare function setupWorkspace(opts: SetupWorkspaceOptions): Promise<SetupWorkspaceResult>;

package/dist/workspace.d.ts

@@ -0,0 +1,51 @@
+export type FrontendModuleValue = string | number | boolean | null | FrontendModuleValue[] | FrontendModuleOptions;
+export interface FrontendModuleOptions {
+    [key: string]: FrontendModuleValue;
+}
+export interface ManifestModule {
+    name: string;
+    archiveName: string;
+    renderer?: {
+        name: string;
+        version: string;
+    };
+    path?: string;
+    priority: number;
+    options?: FrontendModuleOptions;
+    privateOptions?: FrontendModuleOptions;
+    configKey?: string;
+    authEstablishEndpoints?: string[];
+}
+export interface Manifest {
+    pack: string;
+    modules: ManifestModule[];
+}
+export interface FrontendManifest {
+    version: number;
+    archive: string;
+    modules: ManifestModule[];
+}
+export interface ResolvedLayer {
+    path: string;
+    packageName?: string;
+    priority?: number;
+    configKey?: string;
+    options?: FrontendModuleOptions;
+    authEstablishEndpoints?: string[];
+}
+export declare function getWorkspaceDirForKey(key: string): string;
+export declare function projectWorkspaceKey(projectDir: string): string;
+export declare function projectDirFromWorkspaceKey(workspaceKey: string | undefined): string | undefined;
+export declare function getWorkspaceDir(backendUrl: string): string;
+export declare function ensureWorkspace(workspaceKey: string): string;
+export interface WorkspaceEntry {
+    dir: string;
+    backendUrl: string;
+    workspaceKey?: string;
+}
+export declare function describeWorkspace(entry: WorkspaceEntry): string;
+export declare function listWorkspaces(): WorkspaceEntry[];
+export declare function writeWorkspaceMeta(workspaceDir: string, backendUrl: string, workspaceKey: string): void;
+export declare const FRONTEND_MANIFEST_VERSION = 1;
+export declare function bootstrapHeaders(secret?: string): Record<string, string>;
+export declare function isUnauthorized(status: number): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-frontend",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Frontend-agnostic loader for AntelopeJS DMS, shipping the Vue 3 renderer (Vite, Inertia, SSR)",
   "keywords": [
     "antelope",
@@ -27,6 +27,25 @@
     "dist/",
     "templates/"
   ],
+  "main": "./dist/common.js",
+  "types": "./dist/common.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/common.d.ts",
+      "default": "./dist/common.js"
+    },
+    "./common": {
+      "types": "./dist/common.d.ts",
+      "default": "./dist/common.js"
+    },
+    "./dist/*.js": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./dist/*": "./dist/*",
+    "./templates/*": "./templates/*",
+    "./package.json": "./package.json"
+  },
   "publishConfig": {
     "access": "public",
     "provenance": true,

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

@@ -16,7 +16,7 @@
 // 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 { join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { pageModulePreloads } from "./client-manifest.mjs";
 
@@ -32,8 +32,16 @@ const STYLE_EXTENSION =
  * 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.
+ *
+ * `ENTRY_STYLESHEET_ID` is matched against the `data-vite-dev-id` Vite puts on
+ * its own copy, and Vite normalizes every module id onto POSIX separators — so
+ * the native path `join` returns has to be normalized too, or the handover
+ * never happens on Windows and both copies stay in the document.
  */
 const ENTRY_STYLESHEET = "/dms-main.css";
+const ENTRY_STYLESHEET_ID = join(PROJECT_ROOT, "dms-main.css")
+  .split(sep)
+  .join("/");
 
 function ssrModuleGraph(devServer) {
   return devServer.environments?.ssr?.moduleGraph ?? devServer.moduleGraph;
@@ -75,7 +83,7 @@ async function inlineTag(devServer, { url, id }) {
 export async function developmentStyleTags(devServer) {
   const modules = styleModules(devServer);
   const links = [
-    { url: ENTRY_STYLESHEET, id: join(PROJECT_ROOT, "dms-main.css") },
+    { url: ENTRY_STYLESHEET, id: ENTRY_STYLESHEET_ID },
     ...modules.filter(({ url }) => !SFC_STYLE.test(url)),
   ].map(linkTag);
   const inlined = await Promise.all(

package/templates/vue/server.mjs

@@ -1,6 +1,6 @@
 import { createReadStream, existsSync, readFileSync, statSync } from "node:fs";
 import { createServer } from "node:http";
-import { extname, join, resolve } from "node:path";
+import { extname, join, resolve, sep } from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { fileURLToPath } from "node:url";
@@ -254,7 +254,9 @@ function acceptedAsset(pathname, request) {
 
 function serveAsset(pathname, request, response) {
   const selected = acceptedAsset(pathname, request);
-  const assetRoot = `${resolve(PROJECT_ROOT, "dist/client")}/`;
+  // Native separator: `selected.source` comes from `resolve`, so a hardcoded
+  // `/` here would make the containment check fail for every asset on Windows.
+  const assetRoot = `${resolve(PROJECT_ROOT, "dist/client")}${sep}`;
   if (
     !selected.source.startsWith(assetRoot) ||
     !existsSync(selected.file) ||

package/templates/vue/vite.config.ts

@@ -2,7 +2,7 @@ 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, type Plugin } from "vite";
+import { defineConfig, normalizePath, type Plugin } from "vite";
 import { orderHeadForFirstPaint } from "./head-order.mjs";
 
 interface FrontendModuleRegistryEntry {
@@ -38,6 +38,14 @@ const stableModuleAliases = Object.fromEntries(
     return [[`#${moduleName}`, module.root]];
   }),
 );
+/**
+ * Globs are POSIX, always.
+ *
+ * `resolve` returns a native path, so on Windows every pattern below would
+ * carry backslashes — which a glob matcher reads as escape characters, not as
+ * separators, and which therefore match nothing at all. `normalizePath` is
+ * Vite's own answer to this and is the identity function on POSIX.
+ */
 const importDirectories = frontendSourceRoots.flatMap((root) =>
   [
     "app/composables/**/*",
@@ -45,7 +53,7 @@ const importDirectories = frontendSourceRoots.flatMap((root) =>
     "app/utils/**/*",
     "app/build/composables/**/*",
     "app/build/types/**/*",
-  ].map((glob) => ({ glob: resolve(root, glob), types: true })),
+  ].map((glob) => ({ glob: normalizePath(resolve(root, glob)), types: true })),
 );
 const optimizedDependencies = [
   "vue",
@@ -80,6 +88,9 @@ const optimizedDependencies = [
  * 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.
+ *
+ * Normalized for the same reason as `importDirectories`: Vite hands these
+ * patterns straight to its glob matcher without touching the separators.
  */
 const optimizerEntries = [
   resolve(__dirname, "main.ts"),
@@ -88,7 +99,7 @@ const optimizerEntries = [
     resolve(root, "app/**/*.vue"),
     resolve(root, "app/**/*.ts"),
   ]),
-];
+].map(normalizePath);
 
 function paintBeforeHydrate(): Plugin {
   return {
@@ -125,7 +136,13 @@ export default defineConfig({
         imports: [
           "vue",
           {
-            [resolve(__dirname, "frontend-module.ts")]: [
+            // This key is inlined verbatim as the module specifier of the
+            // import the auto-importer prepends to each file. A native Windows
+            // path would land inside a single-quoted JavaScript string with its
+            // backslashes intact, where `\U`, `\M` and `\f` are read as escape
+            // sequences: the specifier the bundler then resolves is a mangled
+            // path that cannot exist. Keep it POSIX.
+            [normalizePath(resolve(__dirname, "frontend-module.ts"))]: [
               "$fetch",
               "abortNavigation",
               "clearError",

package/templates/vue/vite.email.config.ts

@@ -2,7 +2,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import vue from "@vitejs/plugin-vue";
 import AutoImport from "unplugin-auto-import/vite";
-import { defineConfig } from "vite";
+import { defineConfig, normalizePath } from "vite";
 
 interface FrontendModuleRegistryEntry {
   id: string;
@@ -55,7 +55,10 @@ export default defineConfig({
       dts: false,
       imports: [
         {
-          [resolve(__dirname, "email-runtime.ts")]: [
+          // Inlined verbatim as a module specifier in the generated import, so
+          // it has to be POSIX: a native Windows path would reach the parser
+          // with its backslashes read as string escapes. See vite.config.ts.
+          [normalizePath(resolve(__dirname, "email-runtime.ts"))]: [
             "useDmsAppConfig",
             "useDmsRuntimeConfig",
             "defineAppConfig",