@promptbook/cli 0.112.0 → 0.113.0-1

package/src/book-2.0/agent-source/parseAgentSource/applyMetaCommitment.ts

@@ -3,6 +3,7 @@ import { resolveAvatarVisualId } from '../../../avatars/visuals/avatarVisualRegi
 import { normalizeTo_camelCase } from '../../../utils/normalization/normalizeTo_camelCase';
 import { normalizeDomainForMatching } from '../../../utils/validators/url/normalizeDomainForMatching';
 import type { ParsedCommitment } from '../../../commitments/_base/ParsedCommitment';
+import { normalizeAgentVisibility } from '../agentSourceVisibility';
 import type { ParseAgentSourceState } from './ParseAgentSourceState';
 
 /**
@@ -25,6 +26,7 @@ const META_COMMITMENT_APPLIERS: Readonly<Record<string, MetaCommitmentApplier |
     'META COLOR': applyMetaColorContent,
     'META FONT': applyMetaFontContent,
     'META VOICE': applyMetaVoiceContent,
+    'META VISIBILITY': applyMetaVisibilityContent,
 };
 
 /**
@@ -60,6 +62,11 @@ function applyGenericMetaCommitment(state: ParseAgentSourceState, content: strin
         return;
     }
 
+    if (metaTypeRaw.toUpperCase() === 'VISIBILITY') {
+        applyMetaVisibilityContent(state, metaValue);
+        return;
+    }
+
     const metaType = normalizeTo_camelCase(metaTypeRaw);
     state.meta[metaType] = metaValue;
 }
@@ -149,6 +156,16 @@ function applyMetaVoiceContent(state: ParseAgentSourceState, content: string): v
     state.meta.voice = spaceTrim(content);
 }
 
+/**
+ * Applies META VISIBILITY content into the normalized `meta.visibility` field.
+ */
+function applyMetaVisibilityContent(state: ParseAgentSourceState, content: string): void {
+    const visibility = normalizeAgentVisibility(content);
+    if (visibility) {
+        state.meta.visibility = visibility;
+    }
+}
+
 /**
  * Normalizes the separator in the content
  *

package/src/book-2.0/book-language-documentation/createStandaloneBookLanguageMarkdown.ts

@@ -61,6 +61,7 @@ const PROFILE_COMMITMENT_TYPES = new Set([
     'META DESCRIPTION',
     'META DISCLAIMER',
     'META INPUT PLACEHOLDER',
+    'META VISIBILITY',
     'META COLOR',
     'META FONT',
     'META VOICE',

package/src/book-components/BookEditor/BookEditorMonacoTokenization.ts

@@ -21,6 +21,16 @@ const AGENT_REFERENCE_AT_PATTERN = '(?<!\\S)@[A-Za-z0-9_-]+';
  */
 const AGENT_REFERENCE_BRACED_PATTERN = '\\{[^{}\\r\\n]+\\}';
 
+/**
+ * Pattern matching plain inline `@` tokens, for example email addresses.
+ *
+ * Monaco tokenizes from the current offset, so `team@foo.bar` can otherwise reach
+ * the `@foo` suffix and look like a standalone compact reference.
+ *
+ * @private function of BookEditorMonaco
+ */
+const NON_AGENT_REFERENCE_INLINE_AT_TOKEN_REGEX = /[^\s{}]*[^\s@{}]@[^\s{}]+/;
+
 /**
  * Commitment types where compact agent references are supported.
  *
@@ -334,6 +344,7 @@ export const BookEditorMonacoTokenization = {
     AGENT_URL_REFERENCE_REGEX,
     AGENT_REFERENCE_TOKEN_REGEX,
     AGENT_REFERENCE_BRACED_REGEX,
+    NON_AGENT_REFERENCE_INLINE_AT_TOKEN_REGEX,
     AGENT_REFERENCE_HIGHLIGHT_REGEXES,
     extractAgentReferenceValue,
     resolveAgentReferenceToUrl,

package/src/book-components/BookEditor/useBookEditorMonacoLanguage.ts

@@ -312,14 +312,17 @@ export function ensureBookEditorMonacoLanguage(
         commitmentRegex,
     );
 
-    const parameterRegex = /@([a-zA-Z0-9_á-žÁ-Žč-řČ-Řš-žŠ-Žа-яА-ЯёЁ]+)/;
+    const PARAMETER_REGEX = /@([a-zA-Z0-9_á-žÁ-Žč-řČ-Řš-žŠ-Žа-яА-ЯёЁ]+)/;
+    const NON_AGENT_REFERENCE_INLINE_AT_TOKEN_REGEX =
+        BookEditorMonacoTokenization.NON_AGENT_REFERENCE_INLINE_AT_TOKEN_REGEX;
 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const defaultBodyRules: any = [
         [/^---[-]*$/, ''],
         [CODE_BLOCK_FENCE_REGEX, 'code-block', '@codeblock'],
         ...commitmentTransitionRules,
-        [parameterRegex, 'parameter'],
+        [NON_AGENT_REFERENCE_INLINE_AT_TOKEN_REGEX, ''],
+        [PARAMETER_REGEX, 'parameter'],
         [/\{[^}]+\}/, 'parameter'],
     ];
 
@@ -329,7 +332,8 @@ export function ensureBookEditorMonacoLanguage(
         [CODE_BLOCK_FENCE_REGEX, 'code-block', '@codeblock'],
         ...commitmentTransitionRules,
         ...BookEditorMonacoTokenization.AGENT_REFERENCE_HIGHLIGHT_REGEXES.map((regex) => [regex, 'agent-reference']),
-        [parameterRegex, 'parameter'],
+        [NON_AGENT_REFERENCE_INLINE_AT_TOKEN_REGEX, ''],
+        [PARAMETER_REGEX, 'parameter'],
         [/\{[^}]+\}/, 'parameter'],
     ];
 

package/src/book-components/Chat/Chat/Chat.module.css

@@ -3322,23 +3322,32 @@
     font-size: 0.9em;
 }
 
-.citationScreenshotFallback {
+.citationBrowserPreviewFallback {
     width: 100%;
     position: relative;
     display: flex;
     flex-direction: column;
 }
 
-.citationScreenshotImage {
+.citationBrowserPreviewImage {
     width: 100%;
+    aspect-ratio: 16 / 10;
     max-height: 60vh;
     min-height: 400px;
-    object-fit: cover;
+    object-fit: contain;
     object-position: top;
     display: block;
+    background: #fff;
+    cursor: crosshair;
+    outline: none;
+    touch-action: none;
+}
+
+.citationBrowserPreviewImage:focus-visible {
+    box-shadow: inset 0 0 0 3px rgba(0, 112, 243, 0.35);
 }
 
-.citationScreenshotLink {
+.citationBrowserPreviewLink {
     display: block;
     text-align: center;
     padding: 10px 16px;
@@ -3351,7 +3360,7 @@
     transition: background 0.15s;
 }
 
-.citationScreenshotLink:hover {
+.citationBrowserPreviewLink:hover {
     background: #e0e0e0;
     text-decoration: underline;
 }

package/src/book-components/Chat/Chat/CitationIframePreview.tsx

@@ -1,6 +1,8 @@
 'use client';
 
-import { useEffect, useState } from 'react';
+import { useCallback, useEffect, useId, useMemo, useState } from 'react';
+import type { KeyboardEvent, MouseEvent, WheelEvent } from 'react';
+import { LIVE_PAGE_PREVIEW_VIEWPORT_HEIGHT, LIVE_PAGE_PREVIEW_VIEWPORT_WIDTH } from '../utils/livePagePreviewConstants';
 import styles from './Chat.module.css';
 
 /**
@@ -18,12 +20,48 @@ export type CitationIframePreviewProps = {
  *
  * @private type of `<CitationIframePreview/>`
  */
-type EmbedStatus = 'loading' | 'embed' | 'screenshot';
+type EmbedStatus = 'loading' | 'embed' | 'browser';
+
+/**
+ * Browser-preview interaction sent to the Agents Server preview route.
+ *
+ * @private type of `<CitationIframePreview/>`
+ */
+type LivePagePreviewInteraction =
+    | {
+          readonly type: 'click';
+          readonly x: number;
+          readonly y: number;
+      }
+    | {
+          readonly type: 'wheel';
+          readonly deltaX: number;
+          readonly deltaY: number;
+      }
+    | {
+          readonly type: 'keyDown';
+          readonly key: string;
+      };
+
+/**
+ * Pointer position translated into the live-preview browser viewport.
+ *
+ * @private type of `<CitationIframePreview/>`
+ */
+type LivePagePreviewPointerPosition = {
+    readonly x: number;
+    readonly y: number;
+};
+
+/**
+ * Keyboard keys that should not be forwarded as standalone browser actions.
+ */
+const LIVE_PAGE_PREVIEW_IGNORED_KEYS = new Set(['Alt', 'CapsLock', 'Control', 'Meta', 'Shift']);
 
 /**
  * Renders a citation URL preview as an iframe when the target page allows embedding,
- * or falls back to a server-side screenshot with an "Open in new tab" link when it
- * does not (e.g. X-Frame-Options: DENY / SAMEORIGIN).
+ * or falls back to a live server-side browser preview with an "Open in new tab" link
+ * when it does not (e.g. X-Frame-Options: DENY / SAMEORIGIN).
  *
  * Embedding capability is determined by `GET /api/page-preview/check?url=<url>`.
  * If that endpoint is unavailable the component falls back to the iframe directly.
@@ -34,24 +72,24 @@ export function CitationIframePreview({ src, title }: CitationIframePreviewProps
     const [status, setStatus] = useState<EmbedStatus>('loading');
 
     useEffect(() => {
-        let cancelled = false;
+        let isCancelled = false;
 
         fetch(`/api/page-preview/check?url=${encodeURIComponent(src)}`)
             .then((response) => response.json())
             .then((data: { canEmbed: boolean }) => {
-                if (!cancelled) {
-                    setStatus(data.canEmbed ? 'embed' : 'screenshot');
+                if (!isCancelled) {
+                    setStatus(data.canEmbed ? 'embed' : 'browser');
                 }
             })
             .catch(() => {
                 // API not available — fall back to iframe (e.g. outside agents-server)
-                if (!cancelled) {
+                if (!isCancelled) {
                     setStatus('embed');
                 }
             });
 
         return () => {
-            cancelled = true;
+            isCancelled = true;
         };
     }, [src]);
 
@@ -59,20 +97,157 @@ export function CitationIframePreview({ src, title }: CitationIframePreviewProps
         return <div className={styles.citationIframeLoading}>Loading preview…</div>;
     }
 
-    if (status === 'screenshot') {
-        return (
-            <div className={styles.citationScreenshotFallback}>
-                <img
-                    src={`/api/page-preview/screenshot?url=${encodeURIComponent(src)}`}
-                    alt={`Screenshot of ${title}`}
-                    className={styles.citationScreenshotImage}
-                />
-                <a href={src} target="_blank" rel="noopener noreferrer" className={styles.citationScreenshotLink}>
-                    Open in new tab ↗
-                </a>
-            </div>
-        );
+    if (status === 'browser') {
+        return <LiveBrowserPreview src={src} title={title} />;
     }
 
     return <iframe src={src} className={styles.citationIframe} title={title} />;
 }
+
+/**
+ * Renders and controls a streamed browser preview for non-embeddable citation URLs.
+ *
+ * @private component of `<CitationIframePreview/>`
+ */
+function LiveBrowserPreview({ src, title }: CitationIframePreviewProps) {
+    const reactSessionId = useId();
+    const sessionId = useMemo(() => createLivePagePreviewSessionId(reactSessionId), [reactSessionId]);
+    const streamSrc = useMemo(
+        () => `/api/page-preview/live?url=${encodeURIComponent(src)}&sessionId=${encodeURIComponent(sessionId)}`,
+        [sessionId, src],
+    );
+
+    const handleClick = useCallback(
+        (event: MouseEvent<HTMLImageElement>) => {
+            event.currentTarget.focus();
+            const position = resolveLivePagePreviewPointerPosition(event);
+            if (!position) {
+                return;
+            }
+
+            void postLivePagePreviewInteraction(sessionId, {
+                type: 'click',
+                x: position.x,
+                y: position.y,
+            });
+        },
+        [sessionId],
+    );
+
+    const handleWheel = useCallback(
+        (event: WheelEvent<HTMLImageElement>) => {
+            event.preventDefault();
+            void postLivePagePreviewInteraction(sessionId, {
+                type: 'wheel',
+                deltaX: event.deltaX,
+                deltaY: event.deltaY,
+            });
+        },
+        [sessionId],
+    );
+
+    const handleKeyDown = useCallback(
+        (event: KeyboardEvent<HTMLImageElement>) => {
+            if (event.altKey || event.ctrlKey || event.metaKey) {
+                return;
+            }
+
+            const key = normalizeLivePagePreviewKey(event.key);
+            if (!key) {
+                return;
+            }
+
+            event.preventDefault();
+            void postLivePagePreviewInteraction(sessionId, {
+                type: 'keyDown',
+                key,
+            });
+        },
+        [sessionId],
+    );
+
+    return (
+        <div className={styles.citationBrowserPreviewFallback}>
+            <img
+                src={streamSrc}
+                alt={`Live browser preview of ${title}`}
+                className={styles.citationBrowserPreviewImage}
+                onClick={handleClick}
+                onWheel={handleWheel}
+                onKeyDown={handleKeyDown}
+                tabIndex={0}
+            />
+            <a href={src} target="_blank" rel="noopener noreferrer" className={styles.citationBrowserPreviewLink}>
+                Open in new tab ↗
+            </a>
+        </div>
+    );
+}
+
+/**
+ * Creates one browser-preview session id from React's hydration-stable id.
+ *
+ * @param reactSessionId - React-generated id for the component instance.
+ * @returns Session id shared by the stream and interaction endpoints.
+ */
+function createLivePagePreviewSessionId(reactSessionId: string): string {
+    return `preview-${reactSessionId.replace(/[^a-zA-Z0-9_-]/g, '_')}`;
+}
+
+/**
+ * Converts one pointer event over the stream image to browser viewport coordinates.
+ *
+ * @param event - Pointer event from the stream image.
+ * @returns Browser viewport position or null when the image has no layout box.
+ */
+function resolveLivePagePreviewPointerPosition(
+    event: MouseEvent<HTMLImageElement>,
+): LivePagePreviewPointerPosition | null {
+    const rect = event.currentTarget.getBoundingClientRect();
+    if (rect.width <= 0 || rect.height <= 0) {
+        return null;
+    }
+
+    return {
+        x: ((event.clientX - rect.left) / rect.width) * LIVE_PAGE_PREVIEW_VIEWPORT_WIDTH,
+        y: ((event.clientY - rect.top) / rect.height) * LIVE_PAGE_PREVIEW_VIEWPORT_HEIGHT,
+    };
+}
+
+/**
+ * Normalizes one browser keyboard key before forwarding it to Playwright.
+ *
+ * @param key - Browser KeyboardEvent key.
+ * @returns Playwright-compatible key name or null when the key should be ignored.
+ */
+function normalizeLivePagePreviewKey(key: string): string | null {
+    if (!key || LIVE_PAGE_PREVIEW_IGNORED_KEYS.has(key)) {
+        return null;
+    }
+
+    if (key === ' ') {
+        return 'Space';
+    }
+
+    return key;
+}
+
+/**
+ * Sends one live-preview interaction to the Agents Server.
+ *
+ * @param sessionId - Active live-preview session id.
+ * @param interaction - Interaction to apply to the browser page.
+ */
+async function postLivePagePreviewInteraction(
+    sessionId: string,
+    interaction: LivePagePreviewInteraction,
+): Promise<void> {
+    await fetch('/api/page-preview/interact', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            sessionId,
+            ...interaction,
+        }),
+    }).catch(() => undefined);
+}

package/src/book-components/Chat/utils/livePagePreviewConstants.ts

@@ -0,0 +1,17 @@
+/* eslint-disable no-magic-numbers */
+
+// Note: [💞] Ignore a discrepancy between file name and exported helper names
+
+/**
+ * Width of the browser viewport used for live knowledge previews.
+ *
+ * @private shared constant of Agents Server knowledge previews
+ */
+export const LIVE_PAGE_PREVIEW_VIEWPORT_WIDTH = 1280;
+
+/**
+ * Height of the browser viewport used for live knowledge previews.
+ *
+ * @private shared constant of Agents Server knowledge previews
+ */
+export const LIVE_PAGE_PREVIEW_VIEWPORT_HEIGHT = 800;

package/src/cli/cli-commands/agents-server/buildAgentsServer.ts

@@ -45,6 +45,31 @@ const DEFAULT_AGENTS_SERVER_NEXT_DIST_DIRECTORY_NAME = '.next';
  */
 const AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB = 4096;
 
+/**
+ * Conservative Next.js build worker count used by CLI-owned Agents Server production builds.
+ *
+ * Standalone VPS self-updates build the replacement server while the current pm2 process is
+ * still serving traffic. Keeping Next's static workers serial avoids CPU-count-based memory
+ * spikes that can make the OS kill the build child with no normal exit code.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const AGENTS_SERVER_BUILD_WORKER_COUNT = 1;
+
+/**
+ * Maximum attempts for a Next.js build that was killed by the operating system.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const AGENTS_SERVER_BUILD_MAX_ATTEMPTS = 2;
+
+/**
+ * Signals that indicate the Next.js build may have been terminated by resource pressure.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const RETRYABLE_NEXT_BUILD_SIGNALS = new Set<NodeJS.Signals | null>(['SIGKILL', null]);
+
 /**
  * Environment variable passed to the bundled Next app so webpack can resolve dependencies
  * installed beside `ptbk` even when the app sources are materialized into a project cache.
@@ -53,6 +78,13 @@ const AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB = 4096;
  */
 export const PTBK_AGENTS_SERVER_NODE_MODULES_PATH_ENV = 'PTBK_AGENTS_SERVER_NODE_MODULES_PATH';
 
+/**
+ * Environment variable consumed by `apps/agents-server/next.config.ts` to throttle build workers.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+export const PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT_ENV = 'PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT';
+
 /**
  * Environment variable used only by the CLI-owned production build.
  *
@@ -206,6 +238,16 @@ type AgentsServerBuildCacheOptions = {
     readonly environment?: NodeJS.ProcessEnv;
 };
 
+/**
+ * Exit status reported by one spawned Next.js build child process.
+ *
+ * @private internal type of `ptbk agents-server`
+ */
+type NextBuildExitStatus = {
+    readonly code: number | null;
+    readonly signal: NodeJS.Signals | null;
+};
+
 /**
  * Ensures that the local Agents Server production build exists and matches its source fingerprint.
  *
@@ -358,6 +400,8 @@ export function createAgentsServerRuntimeEnvironment(
         ...environment,
         NODE_PATH: mergeNodePath(nodeModulesPath, environment.NODE_PATH),
         [PTBK_AGENTS_SERVER_NODE_MODULES_PATH_ENV]: nodeModulesPath,
+        [PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT_ENV]:
+            environment[PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT_ENV] || String(AGENTS_SERVER_BUILD_WORKER_COUNT),
         ...(options.isNextValidationIgnored
             ? {
                   [PTBK_AGENTS_SERVER_IGNORE_NEXT_VALIDATION_ENV]: 'true',
@@ -626,16 +670,35 @@ async function runNextBuild(options: {
     readonly nextCliPath: string;
     readonly onBuildOutput?: (chunk: string) => void;
 }): Promise<void> {
-    await new Promise<void>((resolveBuild, rejectBuild) => {
+    for (let attempt = 1; attempt <= AGENTS_SERVER_BUILD_MAX_ATTEMPTS; attempt++) {
+        const exitStatus = await runNextBuildAttempt(options);
+
+        if (exitStatus.code === 0) {
+            return;
+        }
+
+        if (attempt < AGENTS_SERVER_BUILD_MAX_ATTEMPTS && isNextBuildTerminationRetryable(exitStatus)) {
+            forwardBuildOutput(createNextBuildRetryMessage(exitStatus, attempt + 1), options.onBuildOutput);
+            continue;
+        }
+
+        throw createNextBuildExitError(exitStatus, attempt);
+    }
+}
+
+/**
+ * Runs one Next.js production build attempt and returns its exit status.
+ */
+async function runNextBuildAttempt(options: {
+    readonly appPath: string;
+    readonly environment: NodeJS.ProcessEnv;
+    readonly nextCliPath: string;
+    readonly onBuildOutput?: (chunk: string) => void;
+}): Promise<NextBuildExitStatus> {
+    return await new Promise<NextBuildExitStatus>((resolveBuild, rejectBuild) => {
         const buildProcess = spawn(process.execPath, [options.nextCliPath, 'build'], {
             cwd: options.appPath,
-            env: {
-                ...options.environment,
-                NODE_OPTIONS: mergeNodeOptionsWithHeapSize(
-                    options.environment.NODE_OPTIONS,
-                    AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB,
-                ),
-            },
+            env: createNextBuildProcessEnvironment(options.environment),
             stdio: ['ignore', 'pipe', 'pipe'],
         });
 
@@ -646,18 +709,83 @@ async function runNextBuild(options: {
             forwardBuildOutput(chunk.toString(), options.onBuildOutput);
         });
 
-        buildProcess.once('error', rejectBuild);
-        buildProcess.once('exit', (code) => {
-            if (code === 0) {
-                resolveBuild();
-                return;
-            }
-
-            rejectBuild(new Error(`next-build exited with code ${String(code)}.`));
+        buildProcess.once('error', (error) => {
+            rejectBuild(createNextBuildSpawnError(error));
+        });
+        buildProcess.once('close', (code, signal) => {
+            resolveBuild({ code, signal });
         });
     });
 }
 
+/**
+ * Creates the environment passed to the spawned Next.js build process.
+ */
+function createNextBuildProcessEnvironment(environment: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+    return {
+        ...environment,
+        NODE_OPTIONS: mergeNodeOptionsWithHeapSize(environment.NODE_OPTIONS, AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB),
+    };
+}
+
+/**
+ * Returns true when one failed build attempt is worth retrying.
+ */
+function isNextBuildTerminationRetryable(exitStatus: NextBuildExitStatus): boolean {
+    return exitStatus.code === null && RETRYABLE_NEXT_BUILD_SIGNALS.has(exitStatus.signal);
+}
+
+/**
+ * Creates one visible retry message for a killed Next.js build attempt.
+ */
+function createNextBuildRetryMessage(exitStatus: NextBuildExitStatus, nextAttempt: number): string {
+    return `\nAgents Server Next build was terminated by ${describeNextBuildExitStatus(exitStatus)}. Retrying attempt ${nextAttempt}/${AGENTS_SERVER_BUILD_MAX_ATTEMPTS}.\n`;
+}
+
+/**
+ * Creates a branded error for a failed Next.js build child process.
+ */
+function createNextBuildExitError(exitStatus: NextBuildExitStatus, attemptCount: number): NotAllowed {
+    const lowMemoryHint = isNextBuildTerminationRetryable(exitStatus)
+        ? '\n\nThe build process was terminated by the operating system. On standalone VPS self-updates this usually means the host ran out of memory while Next.js was compiling or prerendering the app.'
+        : '';
+
+    return new NotAllowed(
+        spaceTrim(`
+            Agents Server Next production build failed.
+
+            - Exit code: \`${String(exitStatus.code)}\`
+            - Signal: \`${String(exitStatus.signal)}\`
+            - Attempts: \`${String(attemptCount)}\`
+            ${lowMemoryHint}
+        `),
+    );
+}
+
+/**
+ * Creates a branded error for failures to start the Next.js build child process.
+ */
+function createNextBuildSpawnError(error: Error): NotAllowed {
+    return new NotAllowed(
+        spaceTrim(`
+            Cannot start the Agents Server Next production build.
+
+            ${error.message}
+        `),
+    );
+}
+
+/**
+ * Formats one Next.js build exit status for foreground logs.
+ */
+function describeNextBuildExitStatus(exitStatus: NextBuildExitStatus): string {
+    if (exitStatus.signal) {
+        return `signal \`${exitStatus.signal}\``;
+    }
+
+    return `exit code \`${String(exitStatus.code)}\``;
+}
+
 /**
  * Prepends `--max-old-space-size=<mib>` to `NODE_OPTIONS` unless the caller already set one.
  */