@antelopejs/dms-frontend 0.3.8 → 0.3.10

package/dist/manifest-secrets.js

@@ -1,15 +1,12 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MANIFEST_SECRET_ENV = void 0;
 exports.collectManifestSecrets = collectManifestSecrets;
 exports.resolveManifestSecrets = resolveManifestSecrets;
 exports.formatSecretConflicts = formatSecretConflicts;
-exports.formatSecretSources = formatSecretSources;
+exports.describeSecretSources = describeSecretSources;
 exports.reportManifestSecrets = reportManifestSecrets;
-const chalk_1 = __importDefault(require("chalk"));
+const cli_1 = require("@antelopejs/core/cli");
 exports.MANIFEST_SECRET_ENV = {
     DMS_HTML_RENDER_SECRET: ["htmlRender", "serviceSecret"],
     DMS_OAUTH_RELAY_SECRET: ["oauth", "relaySecret"],
@@ -80,22 +77,29 @@ function resolveManifestSecrets(secrets, env = process.env) {
 function formatSecretConflicts(conflicts) {
     return conflicts.map(({ name, used, ignored }) => `${name}: ${ignored.join(", ")} publish${ignored.length === 1 ? "es" : ""} a different value than ${used}; using ${used}'s`);
 }
-function formatSecretSources(sources, manifestLabel = "manifest") {
-    const width = Math.max(...SECRET_NAMES.map((name) => name.length));
-    return SECRET_NAMES.map((name) => {
-        const source = sources[name];
-        const label = source === "manifest"
-            ? manifestLabel
-            : source === "not set"
-                ? `not set (${UNSET_CONSEQUENCE[name]})`
-                : source;
-        return `${name.padEnd(width)}  ${label}`;
-    });
+const SOURCE_LABELS = {
+    env: "the environment",
+    manifest: "the manifest",
+};
+function describeSecretSources(sources, manifestLabel = SOURCE_LABELS.manifest) {
+    const labels = { ...SOURCE_LABELS, manifest: manifestLabel };
+    const groups = ["env", "manifest"]
+        .map((source) => ({
+        names: SECRET_NAMES.filter((name) => sources[name] === source),
+        label: labels[source],
+    }))
+        .filter(({ names }) => names.length > 0)
+        .map(({ names, label }) => `${names.join(", ")} from ${label}`);
+    return groups.length > 0 ? groups.join("; ") : undefined;
 }
-function reportManifestSecrets(resolved, manifestLabel = "manifest", log = console.log) {
+function reportManifestSecrets(resolved, fix, ui = (0, cli_1.getProcessUi)()) {
     for (const line of formatSecretConflicts(resolved.conflicts))
-        log(`${chalk_1.default.yellow.bold("⚠")} ${chalk_1.default.yellow(line)}`);
-    log(chalk_1.default.dim("  Server secrets:"));
-    for (const line of formatSecretSources(resolved.sources, manifestLabel))
-        log(chalk_1.default.dim(`    ${line}`));
+        ui.message("warn", line);
+    const unset = SECRET_NAMES.filter((name) => resolved.sources[name] === "not set");
+    unset.forEach((name, index) => {
+        const isLast = index === unset.length - 1;
+        ui.message("warn", `${name} is not set: ${UNSET_CONSEQUENCE[name]}`, {
+            details: isLast ? [`${ui.symbols.levels.hint} ${fix(unset.length)}`] : [],
+        });
+    });
 }

package/dist/manifest.d.ts

@@ -1,11 +1,27 @@
+import { CliError, type CliProblem } from "@antelopejs/core/cli";
 import { Manifest, ManifestModule } from "./workspace";
-export declare class ManifestUnauthorizedError extends Error {
+export declare class ManifestUnauthorizedError extends CliError {
     readonly url: string;
     readonly status: number;
-    constructor(url: string, status: number);
+    constructor(url: string, status: number, credentialSent: boolean);
 }
-export declare class ManifestRefusedError extends Error {
-    constructor(reason: string);
+export declare class BackendUnreachableError extends CliError {
+    readonly url: string;
+    readonly code?: string;
+    constructor(url: string, failure: unknown);
+}
+export declare function displayUrl(url: string | URL): string;
+export declare function backendEndpoint(backendUrl: string, path: string): URL;
+export declare function fetchFromBackend(backendUrl: string, url: URL, bootstrapSecret?: string): Promise<Response>;
+export declare class ManifestRefusedError extends CliError {
+    constructor(problem: string | CliProblem);
+}
+export declare function describeManifestVersion(version: unknown): CliProblem;
+export declare class BackendResponseError extends CliError {
+    constructor(subject: string, url: string | URL, response: Pick<Response, "status" | "statusText">);
+}
+export declare class NoCachedManifestError extends CliError {
+    constructor();
 }
 export declare function fetchManifest(backendUrl: string, clientUrl?: string, bootstrapSecret?: string): Promise<Manifest>;
 export interface ManifestCacheEntry {
@@ -13,12 +29,13 @@ export interface ManifestCacheEntry {
     fetchedAt: string;
 }
 export declare function readCachedManifest(workspaceDir: string): ManifestCacheEntry | undefined;
+export type ManifestCacheUse = "fallback" | "offline" | "never";
 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 resolveManifest(workspaceDir: string, backendUrl: string, cacheUse: ManifestCacheUse, clientUrl?: string, bootstrapSecret?: string): Promise<ResolvedManifest>;
 export declare function assertCachedLayerPathsExist(modules: ServedWithPath[], fetchedAt?: string): void;
 export type ServedWithPath = ManifestModule & {
     path: string;

package/dist/manifest.js

@@ -1,53 +1,192 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ManifestRefusedError = exports.ManifestUnauthorizedError = void 0;
+exports.NoCachedManifestError = exports.BackendResponseError = exports.ManifestRefusedError = exports.BackendUnreachableError = exports.ManifestUnauthorizedError = void 0;
+exports.displayUrl = displayUrl;
+exports.backendEndpoint = backendEndpoint;
+exports.fetchFromBackend = fetchFromBackend;
+exports.describeManifestVersion = describeManifestVersion;
 exports.fetchManifest = fetchManifest;
 exports.readCachedManifest = readCachedManifest;
 exports.resolveManifest = resolveManifest;
 exports.assertCachedLayerPathsExist = assertCachedLayerPathsExist;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const cli_1 = require("@antelopejs/core/cli");
 const config_1 = require("./config");
+const output_1 = require("./output");
 const workspace_1 = require("./workspace");
-class ManifestUnauthorizedError extends Error {
-    constructor(url, status) {
-        super(`Backend refused the layers request (${status}) at ${url}.\n` +
-            "  This DMS backend requires a bootstrap credential for its layer endpoints.\n" +
-            "  • Production/CI: set DMS_BOOTSTRAP_SECRET to the backend's frontend.bootstrapSecret.\n" +
-            "  • Local dev: run inside the antelope project started with `ajs project dev` —\n" +
-            "    the credential is read from .antelope/dms-dev.json automatically.");
+class ManifestUnauthorizedError extends cli_1.CliError {
+    constructor(url, status, credentialSent) {
+        super({
+            title: credentialSent
+                ? `The backend refused the bootstrap credential (${status}) at ${url}`
+                : `The backend requires a bootstrap credential (${status}) at ${url}, and none was sent`,
+            fixes: [
+                "Production/CI: set DMS_BOOTSTRAP_SECRET to the backend's frontend.bootstrapSecret",
+                "Local dev: run inside the antelope project started with `ajs project dev`; the credential is read from .antelope/dms-dev.json automatically",
+            ],
+        });
         this.url = url;
         this.status = status;
         this.name = "ManifestUnauthorizedError";
     }
 }
 exports.ManifestUnauthorizedError = ManifestUnauthorizedError;
-class ManifestRefusedError extends Error {
-    constructor(reason) {
-        super(reason);
+const UNREACHABLE_REASONS = {
+    ECONNREFUSED: "Connection refused",
+    ECONNRESET: "Connection reset",
+    ENOTFOUND: "Unknown host",
+    EAI_AGAIN: "Host name lookup failed",
+    ETIMEDOUT: "Connection timed out",
+    UND_ERR_CONNECT_TIMEOUT: "Connection timed out",
+};
+const UNKNOWN_HOST_CODES = ["ENOTFOUND", "EAI_AGAIN"];
+class BackendUnreachableError extends cli_1.CliError {
+    constructor(url, failure) {
+        const cause = failure?.cause ?? failure;
+        const code = errorCode(cause);
+        const detail = code
+            ? (UNREACHABLE_REASONS[code] ?? errorMessage(cause))
+            : `The request failed: ${errorMessage(cause)}`;
+        const fix = code && UNKNOWN_HOST_CODES.includes(code)
+            ? `Check the host name '${new URL(url).hostname}' in -b <url> or DMS_API_BASE_URL`
+            : "Start the backend (`ajs project dev` for a local one), or pass its URL with -b <url>";
+        super({
+            title: `Cannot reach the DMS backend at ${url}`,
+            reason: `${code ? `${detail} (${code})` : detail}.`,
+            fixes: [fix],
+        }, { cause: failure });
+        this.url = url;
+        this.name = "BackendUnreachableError";
+        this.code = code;
+    }
+}
+exports.BackendUnreachableError = BackendUnreachableError;
+function errorCode(err) {
+    const { code, errors } = (err ?? {});
+    if (typeof code === "string")
+        return code;
+    return Array.isArray(errors) ? errorCode(errors[0]) : undefined;
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function displayUrl(url) {
+    const { origin, pathname } = new URL(url);
+    return `${origin}${pathname.replace(/\/$/, "")}`;
+}
+function backendEndpoint(backendUrl, path) {
+    try {
+        return new URL(`${(0, config_1.parseBackendUrl)(backendUrl)}${path}`);
+    }
+    catch (err) {
+        if (!(err instanceof config_1.UsageError))
+            throw err;
+        throw new cli_1.CliError({ ...err.problem, exitCode: cli_1.FAILURE_EXIT_CODE }, { cause: err });
+    }
+}
+async function fetchFromBackend(backendUrl, url, bootstrapSecret) {
+    let response;
+    try {
+        response = await fetch(url, { headers: (0, workspace_1.bootstrapHeaders)(bootstrapSecret) });
+    }
+    catch (err) {
+        throw new BackendUnreachableError(displayUrl(backendUrl), err);
+    }
+    if ((0, workspace_1.isUnauthorized)(response.status)) {
+        throw new ManifestUnauthorizedError(displayUrl(url), response.status, !!bootstrapSecret);
+    }
+    return response;
+}
+class ManifestRefusedError extends cli_1.CliError {
+    constructor(problem) {
+        super(typeof problem === "string" ? { title: problem } : problem);
         this.name = "ManifestRefusedError";
     }
 }
 exports.ManifestRefusedError = ManifestRefusedError;
+const OWN_RELEASE = require("../package.json");
+const BACKEND_PACKAGE = "@antelopejs/dms";
+const LOADER_UPDATE_COMMAND = "ajs update dms";
+function describeManifestVersion(version) {
+    const loader = `${OWN_RELEASE.name} ${OWN_RELEASE.version}`;
+    const supported = `This loader reads version ${workspace_1.FRONTEND_MANIFEST_VERSION}`;
+    if (typeof version !== "number") {
+        return {
+            title: "The backend served a frontend manifest without a protocol version",
+            reason: `${supported}; the answer does not look like one from ${BACKEND_PACKAGE}.`,
+            fixes: [
+                `Check that -b <url> points at a DMS backend running ${BACKEND_PACKAGE}`,
+            ],
+        };
+    }
+    const title = `The backend serves frontend manifest version ${version}, which ${loader} cannot read`;
+    if (version > workspace_1.FRONTEND_MANIFEST_VERSION) {
+        return {
+            title,
+            reason: `${supported}; the backend's ${BACKEND_PACKAGE} is newer than this loader.`,
+            fixes: [
+                `Upgrade the loader (${LOADER_UPDATE_COMMAND}) to a release that reads version ${version}`,
+            ],
+        };
+    }
+    return {
+        title,
+        reason: `${supported}; the backend's ${BACKEND_PACKAGE} is older than this loader.`,
+        fixes: [
+            `Upgrade ${BACKEND_PACKAGE} on the backend, or use a ${OWN_RELEASE.name} release that reads version ${version}`,
+        ],
+    };
+}
+class BackendResponseError extends cli_1.CliError {
+    constructor(subject, url, response) {
+        const { status, statusText } = response;
+        const answer = `HTTP ${status}${statusText ? ` ${statusText}` : ""}`;
+        const shown = displayUrl(url);
+        const problem = status >= 500
+            ? {
+                title: `The DMS backend failed to serve ${subject} (${answer})`,
+                reason: `${shown} answered ${status}: the backend failed on the request.`,
+                fixes: [
+                    "Check the backend logs (the `ajs project dev` output for a local backend), then run again",
+                ],
+            }
+            : {
+                title: `The DMS backend did not serve ${subject} (${answer})`,
+                reason: `${shown} answered ${status}.`,
+                fixes: [
+                    `Check that -b <url> points at a DMS backend running ${BACKEND_PACKAGE}`,
+                ],
+            };
+        super(problem);
+        this.name = "BackendResponseError";
+    }
+}
+exports.BackendResponseError = BackendResponseError;
+class NoCachedManifestError extends cli_1.CliError {
+    constructor() {
+        super({
+            title: "No cached manifest for this workspace",
+            fixes: ["Run once with the backend reachable before using --offline"],
+        });
+        this.name = "NoCachedManifestError";
+    }
+}
+exports.NoCachedManifestError = NoCachedManifestError;
 async function fetchManifest(backendUrl, clientUrl, bootstrapSecret) {
-    const frontendUrl = new URL(`${backendUrl}/dms/frontend`);
+    const frontendUrl = backendEndpoint(backendUrl, "/dms/frontend");
     frontendUrl.searchParams.set("renderer", "vue");
     frontendUrl.searchParams.set("rendererVersion", "3");
     if (clientUrl) {
         frontendUrl.searchParams.set("clientUrl", clientUrl);
     }
-    const response = await fetch(frontendUrl, {
-        headers: (0, workspace_1.bootstrapHeaders)(bootstrapSecret),
-    });
-    if ((0, workspace_1.isUnauthorized)(response.status)) {
-        throw new ManifestUnauthorizedError(frontendUrl.href, response.status);
-    }
+    const response = await fetchFromBackend(backendUrl, frontendUrl, bootstrapSecret);
     if (!response.ok) {
-        throw new Error(`Failed to fetch manifest from ${frontendUrl.href} (${response.status})`);
+        throw new BackendResponseError("the frontend manifest", frontendUrl, response);
     }
     const manifest = (await response.json());
     if (manifest.version !== workspace_1.FRONTEND_MANIFEST_VERSION) {
-        throw new ManifestRefusedError(`Unsupported frontend manifest version: ${String(manifest.version)}`);
+        throw new ManifestRefusedError(describeManifestVersion(manifest.version));
     }
     const incompatible = manifest.modules.filter((module) => module.renderer?.name !== "vue" || module.renderer?.version !== "3");
     if (incompatible.length) {
@@ -77,8 +216,8 @@ function writeCachedManifest(workspaceDir, manifest) {
     };
     (0, config_1.writeSecretBearingFile)((0, node_path_1.join)(workspaceDir, MANIFEST_CACHE_FILE), `${JSON.stringify(entry, null, 2)}\n`);
 }
-async function resolveManifest(workspaceDir, backendUrl, offline, clientUrl, bootstrapSecret) {
-    if (!offline) {
+async function resolveManifest(workspaceDir, backendUrl, cacheUse, clientUrl, bootstrapSecret) {
+    if (cacheUse !== "offline") {
         try {
             const manifest = await fetchManifest(backendUrl, clientUrl, bootstrapSecret);
             writeCachedManifest(workspaceDir, manifest);
@@ -92,15 +231,30 @@ async function resolveManifest(workspaceDir, backendUrl, offline, clientUrl, boo
             const cached = readCachedManifest(workspaceDir);
             if (!cached)
                 throw err;
+            if (cacheUse === "never")
+                throw cacheNotUsed(err, backendUrl, cached);
             return fromCachedEntry(cached);
         }
     }
     const cached = readCachedManifest(workspaceDir);
-    if (!cached) {
-        throw new Error("No cached manifest for this workspace — run once with the backend reachable before using --offline.");
-    }
+    if (!cached)
+        throw new NoCachedManifestError();
     return fromCachedEntry(cached);
 }
+function cacheNotUsed(failure, backendUrl, cached) {
+    const problem = failure instanceof cli_1.CliError
+        ? failure.problem
+        : { title: errorMessage(failure) };
+    const cache = `A manifest${(0, output_1.cachedAge)(cached.fetchedAt)} exists; a build uses it only with --offline.`;
+    return new cli_1.CliError({
+        ...problem,
+        reason: problem.reason ? `${problem.reason} ${cache}` : cache,
+        fixes: [
+            ...(problem.fixes ?? []),
+            `Or build from the cache on purpose: ajs dms build -b ${displayUrl(backendUrl)} --offline`,
+        ],
+    }, { cause: failure });
+}
 function fromCachedEntry(cached) {
     return {
         manifest: cached.manifest,
@@ -112,7 +266,9 @@ function assertCachedLayerPathsExist(modules, fetchedAt) {
     const missing = modules.filter((mod) => !(0, node_fs_1.existsSync)(mod.path));
     if (missing.length === 0)
         return;
-    throw new Error(`Cached manifest${fetchedAt ? ` (fetched ${fetchedAt})` : ""} references layer paths that no longer exist:\n` +
-        missing.map((mod) => `  - ${mod.name}: ${mod.path}`).join("\n") +
-        "\nStart the backend and re-run to refresh the cache.");
+    throw new cli_1.CliError({
+        title: `The cached manifest${fetchedAt ? ` (fetched ${(0, output_1.formatAge)(fetchedAt)})` : ""} references layer paths that no longer exist`,
+        fixes: ["Start the backend and run again to refresh the cache"],
+        details: missing.map((mod) => `${mod.name}: ${mod.path}`),
+    });
 }

package/dist/materialize.js

@@ -9,6 +9,7 @@ exports.writeFrontendModuleRegistry = writeFrontendModuleRegistry;
 exports.writeDmsMainCss = writeDmsMainCss;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const cli_1 = require("@antelopejs/core/cli");
 const config_1 = require("./config");
 const derived_outputs_1 = require("./derived-outputs");
 const layers_1 = require("./layers");
@@ -83,7 +84,7 @@ function collectAuthEstablishEndpoints(layers) {
                 endpoints.add(endpoint);
                 continue;
             }
-            console.warn(`⚠ Ignoring malformed authEstablishEndpoints entry ${JSON.stringify(endpoint)} ` +
+            (0, cli_1.getProcessUi)().message("warn", `Ignoring malformed authEstablishEndpoints entry ${JSON.stringify(endpoint)} ` +
                 `declared by ${layer.packageName ?? layer.path}: expected an absolute ` +
                 "backend API path under /api/ with no query string.");
         }

package/dist/output.d.ts

@@ -0,0 +1,43 @@
+import { type TaskHandle, type Ui } from "@antelopejs/core/cli";
+import { CancelledError } from "./cancellation";
+export declare function exitOnBrokenPipe(stream?: NodeJS.WriteStream): void;
+export declare function isTerminalFeedback(): boolean;
+export declare function isTerminalResult(): boolean;
+export declare function writeFeedback(line: string): void;
+export declare function writeInfo(line: string): void;
+export declare function writeHeader(command: string, context: string[], ui?: Ui): void;
+export declare function writeBlankLine(): void;
+export declare function showPath(target: string, home?: string): string;
+export declare function showWorkspace(dir: string, isTerminal?: boolean, home?: string, ui?: Ui): string;
+export declare function workspaceId(dir: string, isTerminal: boolean): string;
+export declare function formatSize(bytes: number): string;
+export declare function formatAge(iso: string, now?: number): string;
+export declare function cachedAge(fetchedAt: string | undefined): string;
+export declare function failureDetails(error: unknown, ui?: Ui): string[];
+export declare function endInterruptedTask(task: TaskHandle, error: unknown, stopped: string): void;
+export declare function reportStopped(stop: CancelledError, ui?: Ui): void;
+export interface ReadyLine {
+    label: string;
+    value: string;
+    isLink?: boolean;
+    isEssential?: boolean;
+}
+export interface ReadyBlock {
+    title: string;
+    lines: ReadyLine[];
+    footer: string;
+}
+export declare function formatReadyBlock(block: ReadyBlock, ui?: Ui, isQuiet?: boolean): string[];
+export declare function writeReadyBlock(block: ReadyBlock, ui?: Ui): void;
+declare const TIMED_LEVEL_COLORS: {
+    readonly success: "green";
+    readonly info: "blue";
+    readonly warn: "yellow";
+};
+type TimedLevel = keyof typeof TIMED_LEVEL_COLORS;
+export interface TimedMessageOptions {
+    details?: readonly string[];
+    fixes?: readonly string[];
+}
+export declare function formatTimedMessage(level: TimedLevel, text: string, options?: TimedMessageOptions, ui?: Ui, now?: Date): string;
+export {};

package/dist/output.js

@@ -0,0 +1,214 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exitOnBrokenPipe = exitOnBrokenPipe;
+exports.isTerminalFeedback = isTerminalFeedback;
+exports.isTerminalResult = isTerminalResult;
+exports.writeFeedback = writeFeedback;
+exports.writeInfo = writeInfo;
+exports.writeHeader = writeHeader;
+exports.writeBlankLine = writeBlankLine;
+exports.showPath = showPath;
+exports.showWorkspace = showWorkspace;
+exports.workspaceId = workspaceId;
+exports.formatSize = formatSize;
+exports.formatAge = formatAge;
+exports.cachedAge = cachedAge;
+exports.failureDetails = failureDetails;
+exports.endInterruptedTask = endInterruptedTask;
+exports.reportStopped = reportStopped;
+exports.formatReadyBlock = formatReadyBlock;
+exports.writeReadyBlock = writeReadyBlock;
+exports.formatTimedMessage = formatTimedMessage;
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const cli_1 = require("@antelopejs/core/cli");
+const cancellation_1 = require("./cancellation");
+const HOME_PREFIX = "~";
+const CURRENT_DIRECTORY = ".";
+const WORKSPACE_ID_LENGTH = 8;
+const LINE_BREAK = /\r?\n/;
+const CARRIAGE_RETURN = "\r";
+const STOPPED_SYMBOLS = { unicode: "■", ascii: "x" };
+const LINK_SYMBOLS = { unicode: "➜", ascii: ">" };
+const BLOCK_INDENT = "  ";
+const LINK_GAP = "  ";
+const LABEL_SUFFIX = ":";
+const TIME_LENGTH = 8;
+const BYTES_PER_UNIT = 1024;
+const SIZE_UNITS = ["B", "KB", "MB", "GB", "TB"];
+const DECIMAL_SIZE_LIMIT = 10;
+const MS_PER_MINUTE = 60_000;
+const MINUTES_PER_HOUR = 60;
+const HOURS_PER_DAY = 24;
+function isUnicode(ui) {
+    return ui.symbols === cli_1.SYMBOL_SETS.unicode;
+}
+function exitOnBrokenPipe(stream = process.stdout) {
+    stream.on("error", (error) => {
+        if (error.code !== "EPIPE")
+            throw error;
+        process.exit(cli_1.SUCCESS_EXIT_CODE);
+    });
+}
+function isTerminalFeedback() {
+    return (0, cli_1.detectCapabilities)((0, cli_1.processCapabilityContext)()).terminals.feedback;
+}
+function isTerminalResult() {
+    return (0, cli_1.detectCapabilities)((0, cli_1.processCapabilityContext)()).terminals.result;
+}
+function writeFeedback(line) {
+    (0, cli_1.getProcessTasks)().write(process.stderr, `${line}\n`);
+}
+function writeInfo(line) {
+    if (!(0, cli_1.isQuietRun)())
+        writeFeedback(line);
+}
+function writeHeader(command, context, ui = (0, cli_1.getProcessUi)()) {
+    const title = ui.palette().bold(`ajs dms ${command}`);
+    writeInfo(`${title}  ${context.join(ui.symbols.separator)}`);
+}
+function writeBlankLine() {
+    writeInfo("");
+}
+function showPath(target, home = (0, node_os_1.homedir)()) {
+    if ((0, node_path_1.resolve)(target) === process.cwd())
+        return CURRENT_DIRECTORY;
+    const shown = (0, cli_1.displayPath)(target);
+    if (shown !== target)
+        return shown;
+    const fromHome = (0, node_path_1.relative)(home, target);
+    const isInHome = fromHome !== "" && !(0, node_path_1.isAbsolute)(fromHome) && fromHome.split(node_path_1.sep)[0] !== "..";
+    return isInHome ? (0, node_path_1.join)(HOME_PREFIX, fromHome) : target;
+}
+function showWorkspace(dir, isTerminal = isTerminalFeedback(), home = (0, node_os_1.homedir)(), ui = (0, cli_1.getProcessUi)()) {
+    const shown = showPath(dir, home);
+    const id = (0, node_path_1.basename)(dir);
+    if (!isTerminal || id.length <= WORKSPACE_ID_LENGTH)
+        return shown;
+    return (0, node_path_1.join)((0, node_path_1.dirname)(shown), `${id.slice(0, WORKSPACE_ID_LENGTH)}${ui.symbols.ellipsis}`);
+}
+function workspaceId(dir, isTerminal) {
+    const id = (0, node_path_1.basename)(dir);
+    return isTerminal ? id.slice(0, WORKSPACE_ID_LENGTH) : id;
+}
+function formatSize(bytes) {
+    let value = bytes;
+    let unit = 0;
+    while (value >= BYTES_PER_UNIT && unit < SIZE_UNITS.length - 1) {
+        value /= BYTES_PER_UNIT;
+        unit += 1;
+    }
+    const shown = unit > 0 && value < DECIMAL_SIZE_LIMIT
+        ? String(Math.round(value * 10) / 10)
+        : String(Math.round(value));
+    return `${shown} ${SIZE_UNITS[unit]}`;
+}
+function formatAge(iso, now = Date.now()) {
+    const time = Date.parse(iso);
+    if (Number.isNaN(time))
+        return iso;
+    const minutes = Math.floor(Math.max(0, now - time) / MS_PER_MINUTE);
+    if (minutes < 1)
+        return "just now";
+    if (minutes < MINUTES_PER_HOUR)
+        return `${minutes} min ago`;
+    const hours = Math.floor(minutes / MINUTES_PER_HOUR);
+    if (hours < HOURS_PER_DAY)
+        return `${hours} h ago`;
+    const days = Math.floor(hours / HOURS_PER_DAY);
+    return `${days} ${days === 1 ? "day" : "days"} ago`;
+}
+function cachedAge(fetchedAt) {
+    return fetchedAt ? ` cached ${formatAge(fetchedAt)}` : "";
+}
+function describeProblem(error) {
+    if (error instanceof cli_1.CliError)
+        return error.problem;
+    const message = error instanceof Error ? error.message : String(error);
+    return { title: message.split(LINE_BREAK)[0] };
+}
+function failureDetails(error, ui = (0, cli_1.getProcessUi)()) {
+    const { title, reason, fixes = [], details = [] } = describeProblem(error);
+    const hint = ui.symbols.levels.hint;
+    const stack = (0, cli_1.isVerboseRun)() && error instanceof Error && !(error instanceof cli_1.CliError)
+        ? (error.stack ?? "").split(LINE_BREAK).slice(1)
+        : [];
+    return [
+        title,
+        ...(reason ? [reason] : []),
+        ...details,
+        ...stack.map((line) => line.trim()),
+        ...fixes.map((fix) => `${hint} ${fix}`),
+    ];
+}
+function lineStartAfter(signal) {
+    return signal === "SIGINT" && process.stderr.isTTY ? CARRIAGE_RETURN : "";
+}
+function endInterruptedTask(task, error, stopped) {
+    if (!(error instanceof cancellation_1.CancelledError))
+        return task.dismiss();
+    const lineStart = lineStartAfter(error.signal);
+    if (lineStart)
+        (0, cli_1.getProcessTasks)().write(process.stderr, lineStart);
+    task.skip(stopped);
+}
+function reportStopped(stop, ui = (0, cli_1.getProcessUi)()) {
+    const lineStart = lineStartAfter(stop.signal);
+    if ((0, cli_1.isQuietRun)()) {
+        if (lineStart)
+            writeFeedback("");
+        return;
+    }
+    const symbol = isUnicode(ui)
+        ? STOPPED_SYMBOLS.unicode
+        : STOPPED_SYMBOLS.ascii;
+    const text = [stop.stopped, ...stop.context].join(ui.symbols.separator);
+    writeFeedback(`${lineStart}${ui.palette().red(symbol)} ${text}`);
+}
+function formatReadyBlock(block, ui = (0, cli_1.getProcessUi)(), isQuiet = (0, cli_1.isQuietRun)()) {
+    const palette = ui.palette();
+    const arrow = isUnicode(ui) ? LINK_SYMBOLS.unicode : LINK_SYMBOLS.ascii;
+    const shown = isQuiet
+        ? block.lines.filter(({ isEssential }) => isEssential)
+        : block.lines;
+    const width = Math.max(...shown.map(({ label }) => label.length + LABEL_SUFFIX.length));
+    const lead = (isLink) => `${BLOCK_INDENT}${isLink ? palette.cyan(arrow) : " ".repeat(arrow.length)}${LINK_GAP}`;
+    const lines = shown.map(({ label, value, isLink }) => {
+        const shownLabel = `${label}${LABEL_SUFFIX}`.padEnd(width);
+        const shownValue = isLink ? palette.cyan(value) : value;
+        return `${lead(isLink)}${palette.dim(shownLabel)} ${shownValue}`;
+    });
+    if (isQuiet)
+        return lines;
+    return [
+        `${palette.green(ui.symbols.levels.success)} ${block.title}`,
+        "",
+        ...lines,
+        `${lead()}${palette.dim(block.footer)}`,
+    ];
+}
+function writeReadyBlock(block, ui = (0, cli_1.getProcessUi)()) {
+    for (const line of formatReadyBlock(block, ui))
+        writeFeedback(line);
+    writeInfo("");
+}
+const TIMED_LEVEL_COLORS = {
+    success: "green",
+    info: "blue",
+    warn: "yellow",
+};
+function clockTime(date) {
+    return date.toTimeString().slice(0, TIME_LENGTH);
+}
+function formatTimedMessage(level, text, options = {}, ui = (0, cli_1.getProcessUi)(), now = new Date()) {
+    const { details = [], fixes = [] } = options;
+    const palette = ui.palette();
+    const paint = palette[TIMED_LEVEL_COLORS[level]];
+    const hint = palette.cyan(ui.symbols.levels.hint);
+    const indent = " ".repeat(TIME_LENGTH + 1) + BLOCK_INDENT;
+    return [
+        `${palette.dim(clockTime(now))} ${paint(ui.symbols.levels[level])} ${text}`,
+        ...details.map((detail) => `${indent}${palette.dim(detail)}`),
+        ...fixes.map((fix) => `${indent}${hint} ${fix}`),
+    ].join("\n");
+}

package/dist/ports.d.ts

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