@promptbook/cli 0.112.0-99 → 0.113.0-0

package/apps/agents-server/src/utils/defaultAgents/loadDefaultAgentBooks.ts

@@ -0,0 +1,145 @@
+import { access, readFile, readdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import type { string_book } from '../../../../../src/book-2.0/agent-source/string_book';
+import { DatabaseError } from '../../../../../src/errors/DatabaseError';
+import { spaceTrim } from 'spacetrim';
+
+/**
+ * Folder name on disk that contains the bundled `.core` agent books.
+ *
+ * @private utility of Agents Server default-agent seeding
+ */
+export const CORE_AGENT_DIRECTORY_NAME = '.core';
+
+/**
+ * Options for loading bundled default agent books.
+ *
+ * @private utility of Agents Server default-agent seeding
+ */
+export type LoadDefaultAgentBooksOptions = {
+    /**
+     * Optional explicit directory containing `*.book` files.
+     */
+    readonly defaultAgentDirectory?: string | null;
+};
+
+/**
+ * Candidate directories where bundled default agent books can be located.
+ *
+ * The app test suite runs from `apps/agents-server`, local development usually runs from the repository root, and
+ * installer scripts can pass an explicit directory through `LoadDefaultAgentBooksOptions`.
+ *
+ * @private utility of Agents Server default-agent seeding
+ */
+const DEFAULT_AGENT_DIRECTORY_CANDIDATES = [
+    resolve(process.cwd(), 'agents', 'default'),
+    resolve(process.cwd(), '..', '..', 'agents', 'default'),
+    resolve(__dirname, '../../../../../agents/default'),
+] as const;
+
+/**
+ * Loads all default agent books in deterministic filename order.
+ *
+ * @param options - Optional explicit default-agent directory.
+ * @returns Sorted default agent sources.
+ *
+ * @private utility of Agents Server default-agent seeding
+ */
+export async function loadDefaultAgentBooks(
+    options: LoadDefaultAgentBooksOptions = {},
+): Promise<ReadonlyArray<string_book>> {
+    const defaultAgentDirectory = await resolveDefaultAgentDirectory(options);
+    return loadAgentBooksFromDirectory(defaultAgentDirectory);
+}
+
+/**
+ * Loads all bundled `.core` agent books in deterministic filename order.
+ *
+ * @param options - Optional explicit default-agent directory.
+ * @returns Sorted core agent sources, or an empty list when the `.core` subfolder is absent.
+ *
+ * @private utility of Agents Server default-agent seeding
+ */
+export async function loadCoreAgentBooks(
+    options: LoadDefaultAgentBooksOptions = {},
+): Promise<ReadonlyArray<string_book>> {
+    const defaultAgentDirectory = await resolveDefaultAgentDirectory(options);
+    const coreAgentDirectory = resolve(defaultAgentDirectory, CORE_AGENT_DIRECTORY_NAME);
+
+    try {
+        await access(coreAgentDirectory);
+    } catch {
+        return [];
+    }
+
+    return loadAgentBooksFromDirectory(coreAgentDirectory);
+}
+
+/**
+ * Reads `.book` files from one directory in deterministic filename order.
+ *
+ * @param agentDirectory - Absolute path to the directory containing `.book` files.
+ * @returns Sorted agent sources.
+ *
+ * @private utility of Agents Server default-agent seeding
+ */
+async function loadAgentBooksFromDirectory(agentDirectory: string): Promise<ReadonlyArray<string_book>> {
+    const directoryEntries = await readdir(agentDirectory);
+    const agentFilenames = directoryEntries
+        .filter((entry) => entry.toLowerCase().endsWith('.book'))
+        .sort((leftFilename, rightFilename) => leftFilename.localeCompare(rightFilename));
+
+    return Promise.all(
+        agentFilenames.map(async (filename) => {
+            const filePath = resolve(agentDirectory, filename);
+            return (await readFile(filePath, 'utf-8')) as string_book;
+        }),
+    );
+}
+
+/**
+ * Resolves the repository directory that stores default agent books.
+ *
+ * @param options - Optional explicit default-agent directory.
+ * @returns Absolute path to `agents/default`.
+ *
+ * @private utility of Agents Server default-agent seeding
+ */
+export async function resolveDefaultAgentDirectory(options: LoadDefaultAgentBooksOptions = {}): Promise<string> {
+    const directoryCandidates = [
+        ...(options.defaultAgentDirectory ? [resolve(options.defaultAgentDirectory)] : []),
+        ...DEFAULT_AGENT_DIRECTORY_CANDIDATES,
+    ];
+
+    for (const directoryCandidate of directoryCandidates) {
+        try {
+            await access(directoryCandidate);
+            return directoryCandidate;
+        } catch {
+            // Continue to the next candidate directory.
+        }
+    }
+
+    throw new DatabaseError(
+        spaceTrim(
+            (block) => `
+                Failed to locate the default Agents Server books directory.
+
+                Checked:
+                ${block(directoryCandidates.map((candidate) => `- \`${normalizePathForLogs(candidate)}\``).join('\n'))}
+            `,
+        ),
+    );
+}
+
+/**
+ * Normalizes path separators for diagnostics.
+ *
+ * @param value - Raw filesystem path.
+ * @returns Slash-normalized path.
+ *
+ * @private utility of Agents Server default-agent seeding
+ */
+function normalizePathForLogs(value: string): string {
+    return value.split('\\').join('/');
+}

package/apps/agents-server/src/utils/errorReporting/agentsServerSentryContext.ts

@@ -0,0 +1,203 @@
+import { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION } from '../../../../../src/version';
+import {
+    createSentrySdkTags,
+    resolveSentrySdkCommitHash,
+    resolveSentrySdkEnvironment,
+    resolveSentrySdkRelease,
+    resolveSentrySdkRepositoryBranch,
+} from './sentrySdkConfig';
+import type { SentryStorePayload } from './sentryStore';
+
+/**
+ * Shared deployment and runtime context added to every Agents Server Sentry event.
+ */
+type AgentsServerSentryContext = {
+    /**
+     * Sentry release identifier.
+     */
+    readonly release: string;
+
+    /**
+     * Sentry environment identifier.
+     */
+    readonly environment: string;
+
+    /**
+     * Filterable Sentry tags.
+     */
+    readonly tags: Record<string, string>;
+
+    /**
+     * Full non-secret diagnostic context.
+     */
+    readonly extra: Record<string, unknown>;
+};
+
+/**
+ * Adds shared Agents Server release, environment, version, deployment, git, and runtime details.
+ *
+ * @param payload - Event-specific Sentry payload.
+ * @returns Payload enriched with common Agents Server diagnostics.
+ *
+ * @private internal helper for Agents Server Sentry reporting
+ */
+export function enrichSentryStorePayloadWithAgentsServerContext(payload: SentryStorePayload): SentryStorePayload {
+    const context = createAgentsServerSentryContext();
+
+    return {
+        ...payload,
+        release: context.release,
+        environment: context.environment,
+        tags: {
+            ...context.tags,
+            ...payload.tags,
+        },
+        extra: {
+            ...context.extra,
+            ...payload.extra,
+        },
+    };
+}
+
+/**
+ * Creates a current Agents Server diagnostic context matching the admin About page metadata.
+ *
+ * @returns Common Sentry context for one event.
+ *
+ * @private internal helper for Agents Server Sentry reporting
+ */
+export function createAgentsServerSentryContext(): AgentsServerSentryContext {
+    const deploymentEnvironment = resolveSentrySdkEnvironment();
+    const appPackageVersion = normalizeOptionalString(process.env.npm_package_version) ?? PROMPTBOOK_ENGINE_VERSION;
+    const commitHash = resolveSentrySdkCommitHash();
+    const repositoryBranch = resolveSentrySdkRepositoryBranch();
+    const memoryUsage = process.memoryUsage();
+
+    return {
+        release: resolveSentrySdkRelease(),
+        environment: deploymentEnvironment,
+        tags: createSentrySdkTags(),
+        extra: {
+            agentsServer: {
+                versions: {
+                    promptbookEngineVersion: PROMPTBOOK_ENGINE_VERSION,
+                    bookLanguageVersion: BOOK_LANGUAGE_VERSION,
+                    appPackageVersion,
+                    appPackageName: normalizeOptionalString(process.env.npm_package_name),
+                    nextBuildId: normalizeOptionalString(process.env.NEXT_BUILD_ID),
+                    nextDistDirectory: normalizeOptionalString(process.env.NEXT_DIST_DIR),
+                    npmLifecycleEvent: normalizeOptionalString(process.env.npm_lifecycle_event),
+                    npmUserAgent: normalizeOptionalString(process.env.npm_config_user_agent),
+                },
+                deployment: {
+                    environment: deploymentEnvironment,
+                    vercelEnvironment: getFirstNonEmptyString(process.env.NEXT_PUBLIC_VERCEL_ENV, process.env.VERCEL_ENV),
+                    targetEnvironment: getFirstNonEmptyString(
+                        process.env.NEXT_PUBLIC_VERCEL_TARGET_ENV,
+                        process.env.VERCEL_TARGET_ENV,
+                    ),
+                    siteUrl: normalizeOptionalString(process.env.NEXT_PUBLIC_SITE_URL),
+                    vercelUrl: getFirstNonEmptyString(process.env.NEXT_PUBLIC_VERCEL_URL, process.env.VERCEL_URL),
+                    vercelBranchUrl: normalizeOptionalString(process.env.NEXT_PUBLIC_VERCEL_BRANCH_URL),
+                    vercelProductionUrl: normalizeOptionalString(process.env.NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL),
+                    vercelRegion: normalizeOptionalString(process.env.VERCEL_REGION),
+                    repositoryRef: normalizeOptionalString(process.env.PROMPTBOOK_REPOSITORY_REF),
+                    supabaseTablePrefix: normalizeOptionalString(process.env.SUPABASE_TABLE_PREFIX),
+                    currentWorkingDirectory: process.cwd(),
+                },
+                git: {
+                    provider: getFirstNonEmptyString(
+                        process.env.NEXT_PUBLIC_VERCEL_GIT_PROVIDER,
+                        process.env.VERCEL_GIT_PROVIDER,
+                    ),
+                    repositoryOwner: getFirstNonEmptyString(
+                        process.env.NEXT_PUBLIC_VERCEL_GIT_REPO_OWNER,
+                        process.env.VERCEL_GIT_REPO_OWNER,
+                    ),
+                    repositorySlug: getFirstNonEmptyString(
+                        process.env.NEXT_PUBLIC_VERCEL_GIT_REPO_SLUG,
+                        process.env.VERCEL_GIT_REPO_SLUG,
+                    ),
+                    repositoryId: getFirstNonEmptyString(
+                        process.env.NEXT_PUBLIC_VERCEL_GIT_REPO_ID,
+                        process.env.VERCEL_GIT_REPO_ID,
+                    ),
+                    commitHash,
+                    previousCommitHash: getFirstNonEmptyString(
+                        process.env.NEXT_PUBLIC_VERCEL_GIT_PREVIOUS_SHA,
+                        process.env.VERCEL_GIT_PREVIOUS_SHA,
+                    ),
+                    branch: repositoryBranch,
+                    commitMessage: getFirstNonEmptyString(
+                        process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_MESSAGE,
+                        process.env.VERCEL_GIT_COMMIT_MESSAGE,
+                    ),
+                    authorName: getFirstNonEmptyString(
+                        process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_AUTHOR_NAME,
+                        process.env.VERCEL_GIT_COMMIT_AUTHOR_NAME,
+                    ),
+                    authorLogin: getFirstNonEmptyString(
+                        process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_AUTHOR_LOGIN,
+                        process.env.VERCEL_GIT_COMMIT_AUTHOR_LOGIN,
+                    ),
+                    pullRequestId: getFirstNonEmptyString(
+                        process.env.NEXT_PUBLIC_VERCEL_GIT_PULL_REQUEST_ID,
+                        process.env.VERCEL_GIT_PULL_REQUEST_ID,
+                    ),
+                },
+                runtime: {
+                    nodeVersion: process.version,
+                    nodeEnvironment: normalizeOptionalString(process.env.NODE_ENV),
+                    nextRuntime: normalizeOptionalString(process.env.NEXT_RUNTIME),
+                    processId: process.pid,
+                    processUptimeSeconds: process.uptime(),
+                    hostname: getFirstNonEmptyString(process.env.HOSTNAME, process.env.COMPUTERNAME),
+                    platform: process.platform,
+                    architecture: process.arch,
+                    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC',
+                },
+                memory: {
+                    rssBytes: memoryUsage.rss,
+                    heapUsedBytes: memoryUsage.heapUsed,
+                    heapTotalBytes: memoryUsage.heapTotal,
+                    externalBytes: memoryUsage.external,
+                    arrayBuffersBytes: memoryUsage.arrayBuffers ?? 0,
+                },
+            },
+        },
+    };
+}
+
+/**
+ * Returns the first non-empty string from a list.
+ *
+ * @param values - Candidate values in priority order.
+ * @returns First trimmed string or null.
+ */
+function getFirstNonEmptyString(...values: Array<string | null | undefined>): string | null {
+    for (const value of values) {
+        const normalizedValue = normalizeOptionalString(value);
+
+        if (normalizedValue) {
+            return normalizedValue;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Trims one optional environment value.
+ *
+ * @param value - Raw optional value.
+ * @returns Trimmed string or null.
+ */
+function normalizeOptionalString(value: string | null | undefined): string | null {
+    if (typeof value !== 'string') {
+        return null;
+    }
+
+    const normalizedValue = value.trim();
+
+    return normalizedValue || null;
+}

package/apps/agents-server/src/utils/errorReporting/applicationErrorHandling.ts

@@ -80,6 +80,21 @@ const EDGE_DASH_PATTERN = /^-+|-+$/g;
  */
 const CODE_FENCE_PATTERN = /```/g;
 
+/**
+ * Regex matching webpack/Next.js chunk-load failures caused by stale or missing build assets.
+ */
+const CHUNK_LOAD_ERROR_MESSAGE_PATTERN = /loading (css )?chunk .* failed/i;
+
+/**
+ * Regex matching browsers that fail while fetching one dynamically imported module.
+ */
+const DYNAMIC_IMPORT_FETCH_ERROR_MESSAGE_PATTERN = /failed to fetch dynamically imported module/i;
+
+/**
+ * Regex matching Next.js-managed build asset URLs.
+ */
+const NEXT_BUILD_ASSET_PATH_PATTERN = /\/_next\/static\/(?:chunks|css)\//i;
+
 /**
  * Shape sent from the app error boundary to server-side Sentry forwarding.
  */
@@ -162,6 +177,32 @@ export function createApplicationErrorDigest(error: ApplicationBoundaryError | n
     return (hash >>> 0).toString(DECIMAL_BASE).padStart(DIGEST_LENGTH, '0');
 }
 
+/**
+ * Detects client-side build-asset errors that are commonly fixed by reloading the document once.
+ *
+ * @param error - Captured boundary exception.
+ * @returns True when the current document should be hard-refreshed instead of only retrying React navigation.
+ */
+export function isApplicationErrorRecoverableByHardRefresh(error: ApplicationBoundaryError | null): boolean {
+    const errorName = error?.name?.trim() || '';
+    const errorMessage = error?.message?.trim() || '';
+    const errorStack = error?.stack?.trim() || '';
+    const errorDetails = `${errorName}\n${errorMessage}\n${errorStack}`;
+
+    if (errorName === 'ChunkLoadError') {
+        return true;
+    }
+
+    if (CHUNK_LOAD_ERROR_MESSAGE_PATTERN.test(errorDetails)) {
+        return true;
+    }
+
+    return (
+        DYNAMIC_IMPORT_FETCH_ERROR_MESSAGE_PATTERN.test(errorDetails) &&
+        NEXT_BUILD_ASSET_PATH_PATTERN.test(errorDetails)
+    );
+}
+
 /**
  * Formats descriptive text shown beneath the application error headline.
  *
@@ -170,6 +211,10 @@ export function createApplicationErrorDigest(error: ApplicationBoundaryError | n
  * @returns Friendly summary of what happened.
  */
 export function describeApplicationError(error: ApplicationBoundaryError | null, serverName: string): string {
+    if (isApplicationErrorRecoverableByHardRefresh(error)) {
+        return `The browser could not load the latest application files for ${serverName}. Refreshing the page usually resolves this after a deployment or stale cached shell.`;
+    }
+
     if (error?.message) {
         return `${error.message.trim()} - the server for ${serverName} logged this failure.`;
     }

package/apps/agents-server/src/utils/errorReporting/refreshApplicationDocument.ts

@@ -0,0 +1,10 @@
+/**
+ * Reloads the current browser document so stale build assets can be fetched again.
+ */
+export function refreshApplicationDocument(): void {
+    if (typeof window === 'undefined') {
+        return;
+    }
+
+    window.location.reload();
+}