@promptbook/cli 0.113.0-8 → 0.114.0-0

package/apps/agents-server/src/utils/agentProjects/agentProjectsPaths.ts

@@ -0,0 +1,129 @@
+import { join } from 'path';
+import { AGENT_PROJECTS_DIRECTORY_PATH } from '../../../../../src/book-3.0/agentFolderPaths';
+import { NotAllowed } from '../../../../../src/errors/NotAllowed';
+import { spaceTrim } from '../../../../../src/utils/organization/spaceTrim';
+import { createLocalAgentDirectoryName, resolveLocalAgentRootPath } from '../localChatRunner/ensureLocalAgentFolder';
+
+/**
+ * Directory-name prefix shared by all local agent runner folders.
+ */
+const AGENT_DIRECTORY_NAME_PREFIX = 'agent-';
+
+/**
+ * Resolves the absolute path of the local agent folder for one agent permanent id.
+ *
+ * @param agentPermanentId - Permanent id of the agent.
+ * @returns Absolute agent folder path inside the local agent root.
+ */
+export function resolveAgentFolderPath(agentPermanentId: string): string {
+    return join(resolveLocalAgentRootPath(), createLocalAgentDirectoryName(agentPermanentId));
+}
+
+/**
+ * Resolves the absolute path of the `projects/` root of one agent.
+ *
+ * @param agentPermanentId - Permanent id of the agent.
+ * @returns Absolute projects root path of the agent.
+ */
+export function resolveAgentProjectsRootPath(agentPermanentId: string): string {
+    return join(resolveAgentFolderPath(agentPermanentId), AGENT_PROJECTS_DIRECTORY_PATH);
+}
+
+/**
+ * Resolves the absolute path of one project directory while preventing path traversal.
+ *
+ * @param options - Agent permanent id and project directory name.
+ * @returns Absolute project path.
+ * @throws {NotAllowed} When the project name is unsafe.
+ */
+export function resolveSafeAgentProjectPath(options: {
+    readonly agentPermanentId: string;
+    readonly projectName: string;
+}): string {
+    assertSafeAgentProjectPathSegment(options.projectName, 'project name');
+
+    return join(resolveAgentProjectsRootPath(options.agentPermanentId), options.projectName);
+}
+
+/**
+ * Extracts the agent permanent id from one local agent runner directory name.
+ *
+ * @param agentDirectoryName - Directory name, for example `agent-1dkmraaikkd8yp`.
+ * @returns Permanent id part of the directory name, or `null` when the name does not follow the convention.
+ */
+export function parseAgentPermanentIdFromDirectoryName(agentDirectoryName: string): string | null {
+    if (!agentDirectoryName.toLowerCase().startsWith(AGENT_DIRECTORY_NAME_PREFIX)) {
+        return null;
+    }
+
+    const agentPermanentId = agentDirectoryName.slice(AGENT_DIRECTORY_NAME_PREFIX.length);
+    return agentPermanentId.length > 0 ? agentPermanentId : null;
+}
+
+/**
+ * Asserts that one path segment coming from a URL cannot escape its parent directory.
+ *
+ * @param pathSegment - Single decoded path segment (project name or one file path part).
+ * @param segmentPurpose - Human-readable description used in the error message.
+ * @throws {NotAllowed} When the segment is empty or attempts path traversal.
+ */
+export function assertSafeAgentProjectPathSegment(pathSegment: string, segmentPurpose: string): void {
+    const isTraversalSegment = pathSegment === '.' || pathSegment === '..';
+    const hasPathSeparator = pathSegment.includes('/') || pathSegment.includes('\\');
+    const hasNullByte = pathSegment.includes('\0');
+
+    if (pathSegment.length === 0 || isTraversalSegment || hasPathSeparator || hasNullByte) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Invalid ${segmentPurpose} \`${pathSegment}\`.
+
+                **Path segments must:**
+                - be non-empty
+                - not be \`.\` or \`..\`
+                - not contain path separators or control characters
+            `),
+        );
+    }
+}
+
+/**
+ * Resolves one file path inside one agent project while preventing path traversal.
+ *
+ * @param options - Agent permanent id, project name, and file path segments from the URL.
+ * @returns Absolute file path inside the project directory.
+ * @throws {NotAllowed} When the project name or any file path segment is unsafe.
+ */
+export function resolveSafeAgentProjectFilePath(options: {
+    readonly agentPermanentId: string;
+    readonly projectName: string;
+    readonly filePathSegments: ReadonlyArray<string>;
+}): string {
+    const { agentPermanentId, projectName, filePathSegments } = options;
+
+    for (const filePathSegment of filePathSegments) {
+        assertSafeAgentProjectPathSegment(filePathSegment, 'project file path segment');
+    }
+
+    return join(resolveSafeAgentProjectPath({ agentPermanentId, projectName }), ...filePathSegments);
+}
+
+/**
+ * Resolves one directory path inside one agent project while preventing path traversal.
+ *
+ * @param options - Agent permanent id, project name, and directory path segments from the UI.
+ * @returns Absolute directory path inside the project.
+ * @throws {NotAllowed} When the project name or any directory path segment is unsafe.
+ */
+export function resolveSafeAgentProjectDirectoryPath(options: {
+    readonly agentPermanentId: string;
+    readonly projectName: string;
+    readonly directoryPathSegments: ReadonlyArray<string>;
+}): string {
+    const { agentPermanentId, projectName, directoryPathSegments } = options;
+
+    for (const directoryPathSegment of directoryPathSegments) {
+        assertSafeAgentProjectPathSegment(directoryPathSegment, 'project directory path segment');
+    }
+
+    return join(resolveSafeAgentProjectPath({ agentPermanentId, projectName }), ...directoryPathSegments);
+}

package/apps/agents-server/src/utils/agentProjects/createAgentProjectDnsRecords.ts

@@ -0,0 +1,67 @@
+/**
+ * DNS record types supported by generated agent project domains.
+ *
+ * @private helper for the Agents Server project DNS instructions
+ */
+export type AgentProjectDnsRecordType = 'A' | 'CNAME';
+
+/**
+ * One generated agent project DNS record instruction.
+ *
+ * @private helper for the Agents Server project DNS instructions
+ */
+export type AgentProjectDnsRecord = {
+    /**
+     * DNS record type.
+     */
+    readonly type: AgentProjectDnsRecordType;
+
+    /**
+     * Full hostname to enter as the DNS record name.
+     */
+    readonly name: string;
+
+    /**
+     * DNS record target value.
+     */
+    readonly value: string;
+
+    /**
+     * Explanation of the selected record.
+     */
+    readonly note: string;
+};
+
+/**
+ * Creates the one DNS record shown for a selected project-domain setup.
+ *
+ * @param options - Project domain, server domain, and selected DNS variants.
+ * @returns One DNS record instruction.
+ */
+export function createAgentProjectDnsRecord(options: {
+    readonly isCnameRecord: boolean;
+    readonly isWildcardDomain: boolean;
+    readonly projectDomain: string;
+    readonly publicIpAddress: string | null | undefined;
+    readonly serverDomain: string;
+}): AgentProjectDnsRecord {
+    const name = options.isWildcardDomain ? `*.${options.serverDomain}` : options.projectDomain;
+
+    if (options.isCnameRecord) {
+        return {
+            type: 'CNAME',
+            name,
+            value: options.serverDomain,
+            note: `Use this only when \`${options.serverDomain}\` already resolves to this server.`,
+        };
+    }
+
+    return {
+        type: 'A',
+        name,
+        value: options.publicIpAddress || '<VPS_PUBLIC_IP>',
+        note: options.publicIpAddress
+            ? 'Point this hostname directly to the VPS public IP address.'
+            : 'Replace <VPS_PUBLIC_IP> with the public IP address of this VPS.',
+    };
+}

package/apps/agents-server/src/utils/agentProjects/createAgentProjectMarkdownReferences.ts

@@ -0,0 +1,69 @@
+import type { MarkdownInlineReference } from '@promptbook-local/types';
+import type { AgentProjectReferenceInfo } from './AgentProjectReferenceInfo';
+import { buildAgentProjectProfileHref } from './agentProjectHrefs';
+
+/**
+ * Markdown inline reference data consumed by chat markdown rendering.
+ */
+export type AgentProjectMarkdownReference = MarkdownInlineReference;
+
+/**
+ * Options for creating project markdown references.
+ */
+type CreateAgentProjectMarkdownReferencesOptions = {
+    /**
+     * Permanent id of the agent owning the projects.
+     */
+    readonly agentPermanentId: string;
+
+    /**
+     * Project references available to this agent chat.
+     */
+    readonly projects: ReadonlyArray<AgentProjectMarkdownReferenceInfo>;
+};
+
+/**
+ * Project fields required to create a chat markdown reference.
+ */
+type AgentProjectMarkdownReferenceInfo = Pick<
+    AgentProjectReferenceInfo,
+    'projectName' | 'displayName' | 'description' | 'isRunning' | 'projectUrl'
+>;
+
+/**
+ * Creates markdown references that render known `[[project-name]]` tokens as project profile chips.
+ *
+ * @param options - Agent and project metadata.
+ * @returns Inline markdown references for the shared chat renderer.
+ */
+export function createAgentProjectMarkdownReferences(
+    options: CreateAgentProjectMarkdownReferencesOptions,
+): ReadonlyArray<AgentProjectMarkdownReference> {
+    return options.projects.map((project) => ({
+        reference: project.projectName,
+        label: project.displayName || project.projectName,
+        href: buildAgentProjectProfileHref(options.agentPermanentId, project.projectName),
+        title: project.description || project.displayName || project.projectName,
+        menu: {
+            status: {
+                label: project.isRunning ? 'Project is running' : 'Project is not running',
+                isActive: project.isRunning ?? false,
+            },
+            options: [
+                {
+                    label: 'Open the project in a new tab',
+                    href: project.isRunning ? project.projectUrl ?? null : null,
+                    title:
+                        project.isRunning && project.projectUrl
+                            ? 'Open the project in a new tab'
+                            : 'The project must run before it can be opened.',
+                },
+                {
+                    label: 'Open the project page in a new tab',
+                    href: buildAgentProjectProfileHref(options.agentPermanentId, project.projectName),
+                    title: 'Open the project page in a new tab',
+                },
+            ],
+        },
+    }));
+}

package/apps/agents-server/src/utils/agentProjects/createStaticAgentProjectServer.ts

@@ -0,0 +1,275 @@
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'http';
+import { readdir, readFile, stat } from 'fs/promises';
+import { basename, isAbsolute, join, relative, resolve } from 'path';
+import { NotAllowed } from '../../../../../src/errors/NotAllowed';
+import { spaceTrim } from '../../../../../src/utils/organization/spaceTrim';
+import { assertSafeAgentProjectPathSegment } from './agentProjectsPaths';
+import { isMissingPathError } from './isMissingPathError';
+import { resolveAgentProjectFileContentType } from './resolveAgentProjectFileContentType';
+
+/**
+ * Filenames served automatically when a request targets a project directory.
+ */
+const STATIC_DIRECTORY_INDEX_FILENAMES = ['index.html', 'index.htm'] as const;
+
+/**
+ * HTML content type used for generated static directory listings.
+ */
+const STATIC_DIRECTORY_LIST_CONTENT_TYPE = 'text/html; charset=utf-8';
+
+/**
+ * Base URL used only for parsing relative request URLs.
+ */
+const STATIC_REQUEST_PARSE_BASE_URL = 'http://localhost';
+
+/**
+ * Creates an HTTP static-file server for one agent project directory.
+ *
+ * @param projectPath - Absolute project directory path.
+ * @returns Unbound HTTP server.
+ */
+export function createStaticAgentProjectServer(projectPath: string): Server {
+    const projectRootPath = resolve(projectPath);
+
+    return createServer((request, response) => {
+        handleStaticAgentProjectRequest({ projectRootPath, request, response }).catch((error) => {
+            writeStaticErrorResponse({
+                response,
+                statusCode: error instanceof NotAllowed ? 400 : 500,
+                message: error instanceof Error ? error.message : 'Failed to serve project file.',
+            });
+        });
+    });
+}
+
+/**
+ * Handles one static-file request.
+ */
+async function handleStaticAgentProjectRequest(options: {
+    readonly projectRootPath: string;
+    readonly request: IncomingMessage;
+    readonly response: ServerResponse;
+}): Promise<void> {
+    const requestTarget = resolveStaticRequestTarget(options.projectRootPath, options.request.url || '/');
+
+    if (!requestTarget) {
+        writeStaticErrorResponse({
+            response: options.response,
+            statusCode: 400,
+            message: 'Invalid project file path.',
+        });
+        return;
+    }
+
+    const targetStats = await stat(requestTarget.absolutePath).catch((error) => {
+        if (isMissingPathError(error)) {
+            return null;
+        }
+
+        throw error;
+    });
+
+    if (!targetStats) {
+        writeStaticErrorResponse({
+            response: options.response,
+            statusCode: 404,
+            message: 'Project file not found.',
+        });
+        return;
+    }
+
+    if (targetStats.isDirectory()) {
+        await serveStaticProjectDirectory({
+            projectRootPath: options.projectRootPath,
+            requestPathname: requestTarget.requestPathname,
+            directoryPath: requestTarget.absolutePath,
+            response: options.response,
+        });
+        return;
+    }
+
+    if (!targetStats.isFile()) {
+        writeStaticErrorResponse({
+            response: options.response,
+            statusCode: 404,
+            message: 'Project file not found.',
+        });
+        return;
+    }
+
+    await serveStaticProjectFile(requestTarget.absolutePath, options.response);
+}
+
+/**
+ * Resolves and validates one static request path.
+ */
+function resolveStaticRequestTarget(
+    projectRootPath: string,
+    requestUrl: string,
+): { readonly absolutePath: string; readonly requestPathname: string } | null {
+    let requestPathname: string;
+
+    try {
+        requestPathname = new URL(requestUrl, STATIC_REQUEST_PARSE_BASE_URL).pathname;
+    } catch {
+        return null;
+    }
+
+    let pathSegments: ReadonlyArray<string>;
+
+    try {
+        pathSegments = requestPathname
+            .split('/')
+            .filter((pathSegment) => pathSegment.length > 0)
+            .map((pathSegment) => decodeURIComponent(pathSegment));
+    } catch {
+        return null;
+    }
+
+    for (const pathSegment of pathSegments) {
+        assertSafeAgentProjectPathSegment(pathSegment, 'static project path segment');
+    }
+
+    const absolutePath = resolve(projectRootPath, ...pathSegments);
+    const relativePath = relative(projectRootPath, absolutePath);
+    const isInsideProjectRoot = relativePath === '' || (!relativePath.startsWith('..') && !isAbsolute(relativePath));
+
+    if (!isInsideProjectRoot) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Static project request escaped the project root.
+
+                **Requested path:** \`${requestPathname}\`
+            `),
+        );
+    }
+
+    return { absolutePath, requestPathname };
+}
+
+/**
+ * Serves a file response.
+ */
+async function serveStaticProjectFile(filePath: string, response: ServerResponse): Promise<void> {
+    const content = await readFile(filePath);
+
+    response.writeHead(200, {
+        'Cache-Control': 'no-store',
+        'Content-Type': resolveAgentProjectFileContentType(basename(filePath)),
+        'X-Content-Type-Options': 'nosniff',
+    });
+    response.end(content);
+}
+
+/**
+ * Serves a directory by preferring an index file and falling back to a listing.
+ */
+async function serveStaticProjectDirectory(options: {
+    readonly projectRootPath: string;
+    readonly requestPathname: string;
+    readonly directoryPath: string;
+    readonly response: ServerResponse;
+}): Promise<void> {
+    for (const indexFileName of STATIC_DIRECTORY_INDEX_FILENAMES) {
+        const indexFilePath = join(options.directoryPath, indexFileName);
+        const indexFileStats = await stat(indexFilePath).catch((error) => {
+            if (isMissingPathError(error)) {
+                return null;
+            }
+
+            throw error;
+        });
+
+        if (indexFileStats?.isFile()) {
+            await serveStaticProjectFile(indexFilePath, options.response);
+            return;
+        }
+    }
+
+    const listing = await createStaticProjectDirectoryListingHtml({
+        projectRootPath: options.projectRootPath,
+        requestPathname: options.requestPathname,
+        directoryPath: options.directoryPath,
+    });
+
+    options.response.writeHead(200, {
+        'Cache-Control': 'no-store',
+        'Content-Type': STATIC_DIRECTORY_LIST_CONTENT_TYPE,
+        'X-Content-Type-Options': 'nosniff',
+    });
+    options.response.end(listing);
+}
+
+/**
+ * Creates an HTML listing for one project directory.
+ */
+async function createStaticProjectDirectoryListingHtml(options: {
+    readonly projectRootPath: string;
+    readonly requestPathname: string;
+    readonly directoryPath: string;
+}): Promise<string> {
+    const entries = await readdir(options.directoryPath, { withFileTypes: true });
+    const normalizedRequestPathname = options.requestPathname.endsWith('/')
+        ? options.requestPathname
+        : `${options.requestPathname}/`;
+    const title = `Index of /${relative(options.projectRootPath, options.directoryPath).replace(/\\/gu, '/')}`;
+    const items = entries
+        .filter((entry) => entry.isDirectory() || entry.isFile())
+        .sort((firstEntry, secondEntry) => firstEntry.name.localeCompare(secondEntry.name))
+        .map((entry) => {
+            const href = `${normalizedRequestPathname}${encodeURIComponent(entry.name)}${entry.isDirectory() ? '/' : ''}`;
+            const label = `${entry.name}${entry.isDirectory() ? '/' : ''}`;
+
+            return `<li><a href="${escapeHtml(href)}">${escapeHtml(label)}</a></li>`;
+        })
+        .join('');
+
+    return spaceTrim(`
+        <!doctype html>
+        <html>
+            <head>
+                <meta charset="utf-8">
+                <meta name="viewport" content="width=device-width, initial-scale=1">
+                <title>${escapeHtml(title)}</title>
+            </head>
+            <body>
+                <h1>${escapeHtml(title)}</h1>
+                <ul>${items}</ul>
+            </body>
+        </html>
+    `);
+}
+
+/**
+ * Writes a plain-text error response.
+ */
+function writeStaticErrorResponse(options: {
+    readonly response: ServerResponse;
+    readonly statusCode: number;
+    readonly message: string;
+}): void {
+    if (options.response.headersSent) {
+        options.response.end();
+        return;
+    }
+
+    options.response.writeHead(options.statusCode, {
+        'Cache-Control': 'no-store',
+        'Content-Type': 'text/plain; charset=utf-8',
+        'X-Content-Type-Options': 'nosniff',
+    });
+    options.response.end(options.message);
+}
+
+/**
+ * Escapes text for a small generated HTML document.
+ */
+function escapeHtml(value: string): string {
+    return value
+        .replace(/&/gu, '&amp;')
+        .replace(/</gu, '&lt;')
+        .replace(/>/gu, '&gt;')
+        .replace(/"/gu, '&quot;')
+        .replace(/'/gu, '&#39;');
+}
+

package/apps/agents-server/src/utils/agentProjects/findFreeTcpPort.ts

@@ -0,0 +1,48 @@
+import { createServer } from 'net';
+import { UnexpectedError } from '../../../../../src/errors/UnexpectedError';
+import { spaceTrim } from '../../../../../src/utils/organization/spaceTrim';
+import { AGENT_PROJECT_RUNTIME_HOST } from './agentProjectRuntimeConstants';
+
+/**
+ * Asks the operating system for one currently free TCP port.
+ *
+ * The returned port is free at the time of probing. Callers that need an owned listener
+ * should bind immediately after receiving it.
+ *
+ * @param host - Host address used for the temporary probe listener.
+ * @returns Free local TCP port.
+ */
+export async function findFreeTcpPort(host: string = AGENT_PROJECT_RUNTIME_HOST): Promise<number> {
+    return await new Promise<number>((resolve, reject) => {
+        const probeServer = createServer();
+
+        probeServer.unref();
+        probeServer.once('error', reject);
+        probeServer.listen(0, host, () => {
+            const address = probeServer.address();
+
+            probeServer.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+
+                if (address && typeof address === 'object' && typeof address.port === 'number') {
+                    resolve(address.port);
+                    return;
+                }
+
+                reject(
+                    new UnexpectedError(
+                        spaceTrim(`
+                            Failed to resolve a free local TCP port.
+
+                            The operating system did not report a numeric port for the temporary listener.
+                        `),
+                    ),
+                );
+            });
+        });
+    });
+}
+

package/apps/agents-server/src/utils/agentProjects/hasAgentProjectDevScript.ts

@@ -0,0 +1,68 @@
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+import { UnexpectedError } from '../../../../../src/errors/UnexpectedError';
+import { spaceTrim } from '../../../../../src/utils/organization/spaceTrim';
+import { isMissingPathError } from './isMissingPathError';
+
+/**
+ * File name of the npm manifest that can declare a project dev script.
+ */
+const AGENT_PROJECT_PACKAGE_JSON_FILENAME = 'package.json';
+
+/**
+ * Returns whether an agent project declares a non-empty npm `dev` script.
+ *
+ * Missing or malformed manifests deliberately resolve to `false`, allowing the
+ * project runtime to use the static-server fallback.
+ *
+ * @param projectPath - Absolute path of the project directory.
+ * @returns Whether the project should be started as a dev server.
+ */
+export async function hasAgentProjectDevScript(projectPath: string): Promise<boolean> {
+    const packageJsonPath = join(projectPath, AGENT_PROJECT_PACKAGE_JSON_FILENAME);
+    let packageJsonContent: string;
+
+    try {
+        packageJsonContent = await readFile(packageJsonPath, 'utf-8');
+    } catch (error) {
+        if (isMissingPathError(error)) {
+            return false;
+        }
+
+        throw new UnexpectedError(
+            spaceTrim(`
+                Failed to read project package manifest.
+
+                **Package manifest:** \`${packageJsonPath}\`
+                **Cause:** \`${error instanceof Error ? error.message : String(error)}\`
+            `),
+        );
+    }
+
+    try {
+        return hasDevScript(JSON.parse(packageJsonContent));
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Checks whether parsed package metadata contains a non-empty `scripts.dev` value.
+ *
+ * @param packageJson - Parsed package manifest value.
+ * @returns Whether the package declares a dev script.
+ */
+function hasDevScript(packageJson: unknown): boolean {
+    if (!packageJson || typeof packageJson !== 'object' || Array.isArray(packageJson)) {
+        return false;
+    }
+
+    const scripts = (packageJson as { readonly scripts?: unknown }).scripts;
+
+    if (!scripts || typeof scripts !== 'object' || Array.isArray(scripts)) {
+        return false;
+    }
+
+    const devScript = (scripts as { readonly dev?: unknown }).dev;
+    return typeof devScript === 'string' && Boolean(devScript.trim());
+}

package/apps/agents-server/src/utils/agentProjects/hasAgentProjects.ts

@@ -0,0 +1,24 @@
+import { readdir } from 'fs/promises';
+import { resolveAgentProjectsRootPath } from './agentProjectsPaths';
+import { isMissingPathError } from './isMissingPathError';
+
+/**
+ * Returns whether one agent has at least one local project directory.
+ *
+ * @param agentPermanentId - Permanent id of the agent.
+ * @returns `true` when the agent has at least one project directory.
+ */
+export async function hasAgentProjects(agentPermanentId: string): Promise<boolean> {
+    const projectsRootPath = resolveAgentProjectsRootPath(agentPermanentId);
+
+    try {
+        const projectsRootEntries = await readdir(projectsRootPath, { withFileTypes: true });
+        return projectsRootEntries.some((projectsRootEntry) => projectsRootEntry.isDirectory());
+    } catch (error) {
+        if (isMissingPathError(error)) {
+            return false;
+        }
+
+        throw error;
+    }
+}