@antelopejs/dms-frontend 0.2.3 → 0.2.4

package/README.md

@@ -133,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/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`);
 }

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/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.3",
+  "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,