@antelopejs/dms-frontend 0.3.8 → 0.3.9

package/dist/commands/workspaces-action.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readWorkspaceRecords = readWorkspaceRecords;
+exports.describeKey = describeKey;
+exports.renderWorkspaces = renderWorkspaces;
+exports.reportSkipped = reportSkipped;
+exports.runWorkspaces = runWorkspaces;
+const cli_1 = require("@antelopejs/core/cli");
+const common_1 = require("../common");
+const output_1 = require("../output");
+function readWorkspaceRecords() {
+    const { workspaces, skipped } = (0, common_1.listWorkspaces)();
+    const records = workspaces.map((workspace) => {
+        const projectDir = (0, common_1.projectDirFromWorkspaceKey)(workspace.workspaceKey);
+        return {
+            id: (0, output_1.workspaceId)(workspace.dir, false),
+            dir: workspace.dir,
+            backendUrl: workspace.backendUrl,
+            key: projectDir ? { type: "project", path: projectDir } : { type: "url" },
+            sizeBytes: (0, common_1.directorySize)(workspace.dir),
+            lastUsedAt: workspace.lastUsedAt,
+        };
+    });
+    return { records, skipped };
+}
+function describeKey(record) {
+    return record.key.type === "project"
+        ? `project ${(0, output_1.showPath)(record.key.path)}`
+        : "url";
+}
+const TERMINAL_COLUMNS = [
+    { header: "id", value: (record) => (0, output_1.workspaceId)(record.dir, true) },
+    { header: "backend", value: (record) => record.backendUrl },
+    { header: "key", value: describeKey },
+    { header: "size", value: (record) => (0, output_1.formatSize)(record.sizeBytes) },
+    { header: "last used", value: (record) => (0, output_1.formatAge)(record.lastUsedAt) },
+];
+const PIPED_COLUMNS = [
+    { header: "id", value: (record) => record.id },
+    { header: "backend", value: (record) => record.backendUrl },
+    { header: "key", value: (record) => record.key.type },
+    {
+        header: "project",
+        value: (record) => (record.key.type === "project" ? record.key.path : ""),
+    },
+    { header: "size", value: (record) => String(record.sizeBytes) },
+    { header: "last used", value: (record) => record.lastUsedAt },
+    { header: "dir", value: (record) => record.dir },
+];
+function renderWorkspaces(ui, records, isTerminal) {
+    if (records.length === 0) {
+        ui.message("info", `No workspaces in ${(0, output_1.showPath)(common_1.DMS_FRONTEND_HOME)}`);
+        return;
+    }
+    ui.table(records, isTerminal ? TERMINAL_COLUMNS : PIPED_COLUMNS);
+}
+function reportSkipped(ui, skipped) {
+    for (const dir of skipped) {
+        ui.message("skip", `Skipped ${(0, output_1.showPath)(dir)} (not a workspace)`);
+    }
+}
+function runWorkspaces(options) {
+    const ui = (0, cli_1.getProcessUi)();
+    const { records, skipped } = readWorkspaceRecords();
+    (0, cli_1.writeData)(ui, {
+        data: records,
+        isJson: options.json,
+        render: (target) => renderWorkspaces(target, records, (0, output_1.isTerminalResult)()),
+    });
+    reportSkipped(ui, skipped);
+}

package/dist/commands/workspaces.d.ts

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

package/dist/commands/workspaces.js

@@ -0,0 +1,60 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmdWorkspaces = cmdWorkspaces;
+const commander_1 = require("commander");
+const cli_1 = require("@antelopejs/core/cli");
+const WORKSPACES_EXAMPLES = [
+    {
+        description: "On a terminal: an aligned table",
+        command: "ajs dms workspaces",
+    },
+    {
+        description: "In a script",
+        command: "ajs dms workspaces --json",
+    },
+];
+function cmdWorkspaces() {
+    const command = new commander_1.Command("workspaces")
+        .summary("List generated workspaces")
+        .description("List generated workspaces, with their size and last use.")
+        .option("--json", "Print the list as one JSON document on stdout")
+        .addHelpText("after", `
+Piped, it prints one tab-separated line per workspace, without a header:
+id, backend URL, key type (url or project), project directory, size in bytes,
+last use (ISO 8601) and workspace directory.`)
+        .action(async (options) => (await Promise.resolve().then(() => __importStar(require("./workspaces-action")))).runWorkspaces(options));
+    return (0, cli_1.withExamples)(command, WORKSPACES_EXAMPLES);
+}

package/dist/common.d.ts

@@ -1,3 +1,4 @@
+export * from "./cancellation";
 export * from "./config";
 export * from "./layers";
 export * from "./layer-aliases";

package/dist/common.js

@@ -14,6 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./cancellation"), exports);
 __exportStar(require("./config"), exports);
 __exportStar(require("./layers"), exports);
 __exportStar(require("./layer-aliases"), exports);

package/dist/config.d.ts

@@ -1,3 +1,4 @@
+import { CliError, type CliProblem } from "@antelopejs/core/cli";
 import { Option } from "commander";
 import ignore from "ignore";
 import { type DiscoveryOptions } from "./discovery";
@@ -13,12 +14,20 @@ 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 class UsageError extends CliError {
+    constructor(problem: Omit<CliProblem, "exitCode">);
+}
+export declare function parseBackendUrl(value: string): string;
+export declare function requireBackendUrl(value: string | undefined): string;
+export declare function parsePort(value: string): number;
+export declare function flagOrEnv(flag: boolean | undefined, name: string): boolean;
 export declare const Options: {
-    backendUrl: Option;
+    backendUrl(description: string): Option;
     port: Option;
-    force: Option;
-    readonly offline: Option;
-    bootstrapSecret: Option;
+    force(description: string): Option;
+    offline(description: string): Option;
+    strict: Option;
+    bootstrapSecret(discovery?: string): Option;
 };
 export interface BootstrapDiscoveryOptions extends DiscoveryOptions {
     cwd?: string;

package/dist/config.js

@@ -3,8 +3,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Options = exports.TAILWIND_SOURCE_GLOB = exports.PNPM_LIFECYCLE_SCRIPTS = exports.layerCopyIgnore = exports.LAYER_COPY_BLOCKLIST = exports.AUTH_ESTABLISH_FILE = exports.FRONTEND_MODULE_ENTRY = exports.LAYERS_SUBDIR = exports.TEMPLATE_FILES = exports.WORKSPACE_DIR_MODE = exports.DEPS_HASH_FILE = exports.DMS_FRONTEND_HOME = void 0;
+exports.Options = exports.UsageError = exports.TAILWIND_SOURCE_GLOB = exports.PNPM_LIFECYCLE_SCRIPTS = exports.layerCopyIgnore = exports.LAYER_COPY_BLOCKLIST = exports.AUTH_ESTABLISH_FILE = exports.FRONTEND_MODULE_ENTRY = exports.LAYERS_SUBDIR = exports.TEMPLATE_FILES = exports.WORKSPACE_DIR_MODE = exports.DEPS_HASH_FILE = exports.DMS_FRONTEND_HOME = void 0;
 exports.writeSecretBearingFile = writeSecretBearingFile;
+exports.parseBackendUrl = parseBackendUrl;
+exports.requireBackendUrl = requireBackendUrl;
+exports.parsePort = parsePort;
+exports.flagOrEnv = flagOrEnv;
 exports.normalizeBootstrapSecret = normalizeBootstrapSecret;
 exports.resolveSessionSecret = resolveSessionSecret;
 exports.resolveBootstrapSecret = resolveBootstrapSecret;
@@ -14,9 +18,11 @@ const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
+const cli_1 = require("@antelopejs/core/cli");
 const commander_1 = require("commander");
 const ignore_1 = __importDefault(require("ignore"));
 const discovery_1 = require("./discovery");
+const ports_1 = require("./ports");
 const ANTELOPEJS_HOME = (0, node_path_1.join)((0, node_os_1.homedir)(), ".antelopejs");
 exports.DMS_FRONTEND_HOME = (0, node_path_1.join)(ANTELOPEJS_HOME, "dms-frontend");
 exports.DEPS_HASH_FILE = ".deps-hash";
@@ -85,49 +91,140 @@ exports.PNPM_LIFECYCLE_SCRIPTS = [
     "postpack",
 ];
 exports.TAILWIND_SOURCE_GLOB = "**/*.{vue,ts,tsx,js,jsx,mjs,cjs}";
+class UsageError extends cli_1.CliError {
+    constructor(problem) {
+        super({ ...problem, exitCode: cli_1.USAGE_EXIT_CODE });
+        this.name = "UsageError";
+    }
+}
+exports.UsageError = UsageError;
+const BACKEND_URL_PROTOCOLS = ["http:", "https:"];
+function parseBackendUrl(value) {
+    let protocol;
+    try {
+        protocol = new URL(value.trim()).protocol;
+    }
+    catch {
+        protocol = undefined;
+    }
+    if (protocol && BACKEND_URL_PROTOCOLS.includes(protocol))
+        return value;
+    throw new UsageError({
+        title: `Invalid backend URL '${value}'`,
+        fixes: [
+            value.includes("://")
+                ? "Use an http:// or https:// URL: -b http://localhost:5010"
+                : `Include the scheme: -b http://${value.trim()}`,
+        ],
+    });
+}
+function requireBackendUrl(value) {
+    if (value)
+        return parseBackendUrl(value);
+    throw new UsageError({
+        title: "Backend URL is required",
+        fixes: ["Pass -b <url> or set DMS_API_BASE_URL"],
+    });
+}
+function parsePort(value) {
+    const port = /^\d+$/.test(value.trim()) ? Number(value.trim()) : Number.NaN;
+    if (port >= 0 && port <= ports_1.MAX_TCP_PORT)
+        return port;
+    throw new UsageError({
+        title: `Invalid port '${value}'`,
+        fixes: [
+            `Pass a number between 1 and ${ports_1.MAX_TCP_PORT}, or 0 for any free port: -p 3001`,
+        ],
+    });
+}
 function booleanFromEnv(name) {
     const value = process.env[name];
     if (value === undefined)
         return false;
     return !["", "0", "false", "no", "off"].includes(value.trim().toLowerCase());
 }
+function flagOrEnv(flag, name) {
+    return flag ?? booleanFromEnv(name);
+}
+const BOOTSTRAP_SECRET_DESCRIPTION = "Credential for the backend's layer endpoints; prefer the variable, a command line is visible to other processes";
 exports.Options = {
-    backendUrl: new commander_1.Option("-b, --backend-url <url>", "Backend DMS URL (when omitted, dev mode discovers it from the enclosing antelope project's .antelope/dev.json)").env("DMS_API_BASE_URL"),
-    port: new commander_1.Option("-p, --port <port>", "Port to run on")
+    backendUrl(description) {
+        return new commander_1.Option("-b, --backend-url <url>", description).env("DMS_API_BASE_URL");
+    },
+    port: new commander_1.Option("-p, --port <port>", "Port to serve on")
         .default("3001")
         .env("PORT"),
-    force: new commander_1.Option("-f, --force", "Force reinstall dependencies"),
-    get offline() {
-        return new commander_1.Option("--offline", "Skip the backend manifest fetch and reuse the last cached manifest (env: DMS_OFFLINE)").default(booleanFromEnv("DMS_OFFLINE"));
+    force(description) {
+        return new commander_1.Option("-f, --force", description);
+    },
+    offline(description) {
+        return new commander_1.Option("--offline", `${description} (env: DMS_OFFLINE)`);
+    },
+    strict: new commander_1.Option("--strict", "Exit 1 when the workspace cannot be prepared, and 2 when the backend URL is missing or invalid, instead of warning and exiting 0 (env: DMS_PREPARE_STRICT)"),
+    bootstrapSecret(discovery) {
+        return new commander_1.Option("--bootstrap-secret <secret>", discovery
+            ? `${BOOTSTRAP_SECRET_DESCRIPTION}. ${discovery}`
+            : BOOTSTRAP_SECRET_DESCRIPTION).env("DMS_BOOTSTRAP_SECRET");
     },
-    bootstrapSecret: new commander_1.Option("--bootstrap-secret <secret>", "Credential presented to the backend's layer endpoints (env: DMS_BOOTSTRAP_SECRET, preferred — " +
-        "a secret passed on the command line is visible to every process on the machine). In dev it is " +
-        "discovered from the antelope project's .antelope/dms-dev.json.").env("DMS_BOOTSTRAP_SECRET"),
 };
 const HEADER_SAFE_CREDENTIAL = /^[\x21-\x7e]+$/;
+const HEADER_UNSAFE_CHARACTER = /[^\x21-\x7e]/u;
+const UNSAFE_CHARACTER_NAMES = {
+    " ": "a space",
+    "\t": "a tab",
+    "\r": "a line break",
+    "\n": "a line break",
+};
+const LAST_ASCII_CODE_POINT = 0x7f;
+function describeUnsafeCharacter(value) {
+    const char = HEADER_UNSAFE_CHARACTER.exec(value)?.[0] ?? "";
+    const named = UNSAFE_CHARACTER_NAMES[char];
+    if (named)
+        return named;
+    return (char.codePointAt(0) ?? 0) > LAST_ASCII_CODE_POINT
+        ? "a non-ASCII character"
+        : "a control character";
+}
 const DEFAULT_CREDENTIAL_SOURCE = "DMS_BOOTSTRAP_SECRET";
 function normalizeBootstrapSecret(value, source = DEFAULT_CREDENTIAL_SOURCE) {
     const trimmed = value?.trim();
     if (!trimmed)
         return undefined;
     if (!HEADER_SAFE_CREDENTIAL.test(trimmed)) {
-        throw new Error("The bootstrap credential contains characters that cannot travel in an HTTP header.\n" +
-            `  Check ${source} for a line break or a non-ASCII byte — a secret read from\n` +
-            "  a file commonly keeps its trailing newline.");
+        throw new UsageError({
+            title: "The bootstrap credential cannot travel in an HTTP header",
+            reason: `${source} contains ${describeUnsafeCharacter(trimmed)}.`,
+            fixes: [
+                "Use printable ASCII characters only, without spaces or line breaks",
+            ],
+        });
     }
     return trimmed;
 }
+const SESSION_SECRET_MIN_LENGTH = 32;
 function resolveSessionSecret(mode, value = process.env.DMS_SESSION_SECRET) {
     if (value === undefined && mode === "dev") {
         return (0, node_crypto_1.randomBytes)(32).toString("hex");
     }
-    if (value === undefined || value.length < 32) {
-        throw new Error("DMS_SESSION_SECRET must contain at least 32 characters; " +
-            (mode === "dev"
-                ? "set it explicitly or omit it to generate an ephemeral dev secret"
-                : "set it explicitly for build and start"));
+    if (value !== undefined && value.length >= SESSION_SECRET_MIN_LENGTH) {
+        return value;
     }
-    return value;
+    throw new UsageError({
+        title: `DMS_SESSION_SECRET ${describeSessionSecret(value)}`,
+        reason: mode === "dev"
+            ? "dev generates an ephemeral secret only when the variable is not set at all."
+            : "build and start sign sessions with it, so it must stay the same across restarts.",
+        fixes: [
+            "Create one: openssl rand -hex 32, then set it in the environment or ./.env",
+        ],
+    });
+}
+function describeSessionSecret(value) {
+    if (value === undefined)
+        return "is not set";
+    if (value === "")
+        return "is empty";
+    return `is too short: ${value.length} characters, at least ${SESSION_SECRET_MIN_LENGTH} needed`;
 }
 function resolveBootstrapSecret(explicit, backendUrl, options = {}) {
     const normalized = normalizeBootstrapSecret(explicit);

package/dist/derived-outputs.d.ts

@@ -11,12 +11,17 @@ export interface FrontendModuleRegistry {
     modules: FrontendModuleRegistryEntry[];
 }
 export declare function createFrontendModuleRegistry(workspaceDir: string, layers: ResolvedLayer[]): FrontendModuleRegistry;
+export declare class InvalidLocaleFileError extends Error {
+    readonly path: string;
+    readonly reason: string;
+    constructor(path: string, reason: string);
+}
 export declare function affectsLocaleMessages(relativePath: string): boolean;
 export declare function writeLocaleMessages(workspaceDir: string, registry: FrontendModuleRegistry): boolean;
 export interface DerivedOutput {
     name: string;
     affects(relativePath: string): boolean;
     write(workspaceDir: string, registry: FrontendModuleRegistry): boolean;
-    restartNotice?: string;
+    restartHint?: string;
 }
 export declare const DERIVED_OUTPUTS: readonly DerivedOutput[];

package/dist/derived-outputs.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DERIVED_OUTPUTS = void 0;
+exports.DERIVED_OUTPUTS = exports.InvalidLocaleFileError = void 0;
 exports.createFrontendModuleRegistry = createFrontendModuleRegistry;
 exports.affectsLocaleMessages = affectsLocaleMessages;
 exports.writeLocaleMessages = writeLocaleMessages;
@@ -120,13 +120,22 @@ function mergeLocaleMessages(source, existing) {
     return merged;
 }
 const LOCALE_DIRECTORY = "i18n/locales";
+class InvalidLocaleFileError extends Error {
+    constructor(path, reason) {
+        super(`Invalid locale file ${path}: ${reason}`);
+        this.path = path;
+        this.reason = reason;
+        this.name = "InvalidLocaleFileError";
+    }
+}
+exports.InvalidLocaleFileError = InvalidLocaleFileError;
 function readLocaleFile(path) {
     try {
         return JSON.parse((0, node_fs_1.readFileSync)(path, "utf8"));
     }
     catch (error) {
         const reason = error instanceof Error ? error.message : String(error);
-        throw new Error(`Invalid locale file ${path}: ${reason}`);
+        throw new InvalidLocaleFileError(path, reason);
     }
 }
 function readLocaleMessages(assets, registry) {
@@ -276,7 +285,7 @@ exports.DERIVED_OUTPUTS = [
         name: "type paths",
         affects: isLayerDirectory,
         write: writeFrontendTypePaths,
-        restartNotice: "A layer directory was added or removed: restart 'ajs dms dev' to apply it. Vite reads the '#<layer>' aliases and the auto-imported directories at startup only.",
+        restartHint: "Restart ajs dms dev to apply it (Vite reads the '#<layer>' aliases and the auto-imported directories at startup)",
     },
     {
         name: "locale catalogs",

package/dist/discovery.d.ts

@@ -1,3 +1,4 @@
+import type { CliProblem } from "@antelopejs/core/cli";
 export interface DevRegistryEndpoint {
     protocol: string;
     host: string;
@@ -38,7 +39,7 @@ export type DiscoveryResult = {
     projectDir: string;
 };
 export declare function discoverBackend(cwd: string, options?: DiscoveryOptions): DiscoveryResult;
-export declare function describeDiscoveryFailure(result: DiscoveryResult): string;
+export declare function describeDiscoveryFailure(result: DiscoveryResult): CliProblem;
 export interface DevHandshake {
     pid: number;
     bootstrapSecret: string;

package/dist/discovery.js

@@ -8,6 +8,7 @@ exports.describeDiscoveryFailure = describeDiscoveryFailure;
 exports.readDevBootstrapCredential = readDevBootstrapCredential;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const output_1 = require("./output");
 exports.DEV_REGISTRY_RELATIVE_PATH = (0, node_path_1.join)(".antelope", "dev.json");
 function isPidAlive(pid) {
     if (!Number.isInteger(pid) || pid <= 0)
@@ -79,21 +80,37 @@ function discoverBackend(cwd, options = {}) {
 function describeDiscoveryFailure(result) {
     switch (result.status) {
         case "not-found":
-            return ("No backend URL provided and no running antelope project found.\n" +
-                `  Searched for ${exports.DEV_REGISTRY_RELATIVE_PATH} from the current directory upward.\n` +
-                "  Either run this command inside an antelope project started with 'ajs project dev',\n" +
-                "  or pass the backend explicitly with -b <url> (env: DMS_API_BASE_URL).");
+            return {
+                title: "No backend URL provided and no running antelope project found",
+                reason: `Searched for ${exports.DEV_REGISTRY_RELATIVE_PATH} from the current directory upward.`,
+                fixes: [
+                    "Run this command inside an antelope project started with 'ajs project dev'",
+                    "Or pass the backend explicitly with -b <url> (env: DMS_API_BASE_URL)",
+                ],
+            };
         case "stale":
-            return (`Found ${(0, node_path_1.join)(result.projectDir, exports.DEV_REGISTRY_RELATIVE_PATH)} but its process (pid ${result.pid}) is no longer running.\n` +
-                "  Start the backend with 'ajs project dev', or pass -b <url> explicitly.");
+            return {
+                title: `Found ${(0, output_1.showPath)((0, node_path_1.join)(result.projectDir, exports.DEV_REGISTRY_RELATIVE_PATH))} but its process (pid ${result.pid}) is no longer running`,
+                fixes: [
+                    "Start the backend with 'ajs project dev', or pass -b <url> explicitly",
+                ],
+            };
         case "no-api-endpoint":
-            return (`Found a running antelope project at ${result.projectDir} but it exposes no 'api' server endpoint.\n` +
-                "  Make sure the api module is loaded, or pass -b <url> explicitly.");
+            return {
+                title: `Found a running antelope project at ${(0, output_1.showPath)(result.projectDir)} but it exposes no 'api' server endpoint`,
+                fixes: [
+                    "Make sure the api module is loaded, or pass -b <url> explicitly",
+                ],
+            };
         case "malformed":
-            return (`Found ${(0, node_path_1.join)(result.projectDir, exports.DEV_REGISTRY_RELATIVE_PATH)} but could not parse it.\n` +
-                "  Restart the backend with 'ajs project dev' to rewrite it, or pass -b <url> explicitly.");
+            return {
+                title: `Found ${(0, output_1.showPath)((0, node_path_1.join)(result.projectDir, exports.DEV_REGISTRY_RELATIVE_PATH))} but could not parse it`,
+                fixes: [
+                    "Restart the backend with 'ajs project dev' to rewrite it, or pass -b <url> explicitly",
+                ],
+            };
         case "found":
-            return "";
+            return { title: "" };
     }
 }
 exports.DEV_HANDSHAKE_RELATIVE_PATH = (0, node_path_1.join)(".antelope", "dms-dev.json");

package/dist/env-file.js

@@ -5,11 +5,14 @@ exports.loadProjectEnv = loadProjectEnv;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_util_1 = require("node:util");
+const cli_1 = require("@antelopejs/core/cli");
+const output_1 = require("./output");
 exports.ENV_FILE_NAMES = [".env.local", ".env"];
 function loadProjectEnv(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const env = options.env ?? process.env;
-    const onWarning = options.onWarning ?? ((message) => console.warn(message));
+    const onWarning = options.onWarning ??
+        ((message) => (0, cli_1.getProcessUi)().message("warn", message));
     const loaded = [];
     for (const name of exports.ENV_FILE_NAMES) {
         const file = (0, node_path_1.join)(cwd, name);
@@ -20,7 +23,7 @@ function loadProjectEnv(options = {}) {
             parsed = (0, node_util_1.parseEnv)((0, node_fs_1.readFileSync)(file, "utf-8"));
         }
         catch (err) {
-            onWarning(`⚠ Ignoring ${file}: ${err?.message ?? err}`);
+            onWarning(`Ignoring ${(0, output_1.showPath)(file)}: ${err?.message ?? err}`);
             continue;
         }
         for (const [key, value] of Object.entries(parsed)) {

package/dist/help.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from "commander";
+export declare const ENVIRONMENT_TOPIC = "environment";
+export declare const ENVIRONMENT_VARIABLES: ReadonlyArray<readonly [string, string]>;
+export declare function applyDmsHelp(program: Command): void;
+export declare function formatEnvironmentHelp(width?: number): string;

package/dist/help.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENVIRONMENT_VARIABLES = exports.ENVIRONMENT_TOPIC = void 0;
+exports.applyDmsHelp = applyDmsHelp;
+exports.formatEnvironmentHelp = formatEnvironmentHelp;
+const cli_1 = require("@antelopejs/core/cli");
+const env_file_1 = require("./env-file");
+exports.ENVIRONMENT_TOPIC = "environment";
+exports.ENVIRONMENT_VARIABLES = [
+    ["DMS_API_BASE_URL", "Backend URL, same as -b; clean ignores it"],
+    ["DMS_BOOTSTRAP_SECRET", "Same as --bootstrap-secret"],
+    [
+        "DMS_SESSION_SECRET",
+        "Session key, 32 characters or more; build and start need one, dev makes one when unset",
+    ],
+    ["DMS_OFFLINE", "Same as --offline, unless 0, false, no or off"],
+    ["DMS_PREPARE_STRICT", "Same as prepare --strict, read like DMS_OFFLINE"],
+    ["PORT", "Same as -p"],
+    ["HOST", "Address the server binds to (default: 0.0.0.0)"],
+    [
+        "DMS_COOKIE_SECURE",
+        "Secure cookies unless false (default: false in dev, true in start)",
+    ],
+    [
+        "DMS_TRUSTED_PROXY_HOPS",
+        "Trusted reverse-proxy hops, counted from the right (default: 0)",
+    ],
+    [
+        "DMS_HTML_RENDER_SECRET",
+        "Overrides the e-mail render secret the backend publishes",
+    ],
+    [
+        "DMS_OAUTH_RELAY_SECRET",
+        "Overrides the OAuth relay secret the backend publishes",
+    ],
+    [
+        "DMS_AUTH_ESTABLISH_ENDPOINTS",
+        "More backend endpoints /auth/establish may open a session from, comma-separated",
+    ],
+    ["DMS_CLIENT_BASE_URL", "Public frontend URL used in links and e-mails"],
+    ["NO_COLOR", "Same as --no-color"],
+    ["ANTELOPEJS_VERBOSE", "Same as --verbose"],
+    ["NO_UPDATE_NOTIFIER, CI", "Either one turns the update check off"],
+];
+const ENVIRONMENT_NOTES = [
+    "A variable set in the shell wins over both files, and .env.local wins over .env. Only the current directory is read: the generated workspace never loads a .env of its own.",
+    "Workspaces live in ~/.antelopejs/dms-frontend, one per backend URL. dev without -b keys its own on the project directory instead; pass -b to share one with build and start. ajs dms workspaces lists them.",
+];
+function subcommandTerm(command) {
+    const args = command.registeredArguments.map((argument) => argument.required ? `<${argument.name()}>` : `[${argument.name()}]`);
+    return [command.name(), ...args].join(" ");
+}
+function applyDmsHelp(program) {
+    (0, cli_1.applyHelpConventions)(program);
+    const apply = (command) => {
+        command.configureHelp({ ...command.configureHelp(), subcommandTerm });
+        command.commands.forEach(apply);
+    };
+    apply(program);
+}
+function formatEnvironmentHelp(width = (0, cli_1.helpWidth)()) {
+    const files = env_file_1.ENV_FILE_NAMES.map((name) => `./${name}`).join(", then ");
+    const nameWidth = Math.max(...exports.ENVIRONMENT_VARIABLES.map(([name]) => name.length));
+    return [
+        ...(0, cli_1.wrapText)(`Environment (read from the shell, then ${files})`, width),
+        "",
+        ...exports.ENVIRONMENT_VARIABLES.flatMap(([name, description]) => (0, cli_1.formatHelpItem)(name, nameWidth, description, width)),
+        ...ENVIRONMENT_NOTES.flatMap((note) => ["", ...(0, cli_1.wrapText)(note, width)]),
+    ].join("\n");
+}