@promptbook/cli 0.114.0-3 → 0.114.0-31

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

@@ -9,6 +9,7 @@ import {
     resolveAgentProjectDomainRegistryFilePath,
     resolveAgentProjectDomainsFilePath,
 } from './agentProjectRuntimePaths';
+import { runAgentProjectStateMutation } from './agentProjectStateMutationQueue';
 
 /**
  * Current on-disk domain registry schema version.
@@ -139,23 +140,6 @@ type PersistedAgentProjectDomainRegistry = {
     readonly domains: ReadonlyArray<AgentProjectDomainRecord>;
 };
 
-/**
- * Process-wide domain registry state.
- */
-type AgentProjectDomainRegistryState = {
-    /**
-     * Promise chain used as a lightweight mutation queue.
-     */
-    domainMutationQueue: Promise<void>;
-};
-
-/**
- * Global object shape used for process-wide domain registry state.
- */
-type AgentProjectDomainRegistryGlobal = typeof globalThis & {
-    [AGENT_PROJECT_DOMAIN_REGISTRY_GLOBAL_KEY]?: AgentProjectDomainRegistryState;
-};
-
 /**
  * Assigns or refreshes the stable public domain for one agent project.
  *
@@ -483,21 +467,7 @@ async function writeAgentProjectDomainRecords(records: ReadonlyArray<AgentProjec
  * Runs one domain-registry mutation after previous mutations have finished.
  */
 async function runAgentProjectDomainRegistryMutation<TValue>(operation: () => Promise<TValue>): Promise<TValue> {
-    const registryState = getAgentProjectDomainRegistryState();
-    const previousMutation = registryState.domainMutationQueue;
-    let releaseMutation!: () => void;
-
-    registryState.domainMutationQueue = new Promise<void>((resolve) => {
-        releaseMutation = resolve;
-    });
-
-    await previousMutation.catch(() => undefined);
-
-    try {
-        return await operation();
-    } finally {
-        releaseMutation();
-    }
+    return await runAgentProjectStateMutation(AGENT_PROJECT_DOMAIN_REGISTRY_GLOBAL_KEY, operation);
 }
 
 /**
@@ -719,15 +689,3 @@ async function writeTextFile(filePath: string, content: string): Promise<void> {
     await mkdir(dirname(filePath), { recursive: true });
     await writeFile(filePath, content, 'utf-8');
 }
-
-/**
- * Returns process-wide project-domain registry state.
- */
-function getAgentProjectDomainRegistryState(): AgentProjectDomainRegistryState {
-    const registryGlobal = globalThis as AgentProjectDomainRegistryGlobal;
-    registryGlobal[AGENT_PROJECT_DOMAIN_REGISTRY_GLOBAL_KEY] ??= {
-        domainMutationQueue: Promise.resolve(),
-    };
-
-    return registryGlobal[AGENT_PROJECT_DOMAIN_REGISTRY_GLOBAL_KEY]!;
-}

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

@@ -15,6 +15,11 @@ export const PTBK_AGENT_PROJECT_DOMAIN_REGISTRY_FILE_ENV = 'PTBK_AGENT_PROJECT_D
  */
 export const PTBK_AGENT_PROJECT_DOMAINS_FILE_ENV = 'PTBK_AGENT_PROJECT_DOMAINS_FILE';
 
+/**
+ * Environment variable overriding the persisted project desired-state file.
+ */
+export const PTBK_AGENT_PROJECT_RUNTIME_DESIRED_STATE_FILE_ENV = 'PTBK_AGENT_PROJECT_RUNTIME_DESIRED_STATE_FILE';
+
 /**
  * Directory under the Agents Server data root used for project runtime state.
  */
@@ -35,6 +40,11 @@ const AGENT_PROJECT_DOMAIN_REGISTRY_FILE_NAME = 'domains.json';
  */
 const AGENT_PROJECT_DOMAINS_FILE_NAME = 'domains.txt';
 
+/**
+ * Persisted desired-state filename.
+ */
+const AGENT_PROJECT_RUNTIME_DESIRED_STATE_FILE_NAME = 'desired-states.json';
+
 /**
  * Resolves the durable state root used by agent project runtime managers.
  *
@@ -86,6 +96,21 @@ export function resolveAgentProjectDomainRegistryFilePath(): string {
     return join(resolveAgentProjectRuntimeStateRoot(), AGENT_PROJECT_DOMAIN_REGISTRY_FILE_NAME);
 }
 
+/**
+ * Resolves the JSON file remembering which projects were explicitly started or stopped.
+ *
+ * @returns Absolute file path.
+ */
+export function resolveAgentProjectRuntimeDesiredStateFilePath(): string {
+    const configuredFilePath = process.env[PTBK_AGENT_PROJECT_RUNTIME_DESIRED_STATE_FILE_ENV]?.trim();
+
+    if (configuredFilePath) {
+        return resolve(configuredFilePath);
+    }
+
+    return join(resolveAgentProjectRuntimeStateRoot(), AGENT_PROJECT_RUNTIME_DESIRED_STATE_FILE_NAME);
+}
+
 /**
  * Resolves the newline-separated domain file consumed by the VPS installer.
  *

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

@@ -1,8 +1,11 @@
 import { execFile } from 'child_process';
 import { createHash } from 'crypto';
 import { promisify } from 'util';
+import { UnexpectedError } from '../../../../../src/errors/UnexpectedError';
+import { spaceTrim } from '../../../../../src/utils/organization/spaceTrim';
 import { AGENT_PROJECT_RUNTIME_HOST } from './agentProjectRuntimeConstants';
 import type { AgentProjectRuntimeMode } from './AgentProjectRuntimeInfo';
+import { resolveAgentProjectRuntimeEnvironmentFlag } from './resolveAgentProjectRuntimeEnvironmentFlag';
 
 const execFileAsync = promisify(execFile);
 
@@ -43,8 +46,18 @@ const AGENT_PROJECT_PM2_PROCESS_LABEL_LENGTH = 36;
 
 /**
  * Max output retained from pm2 commands.
+ *
+ * Note: `pm2 jlist` embeds a full environment snapshot into every listed process, so the list grows by tens of
+ *       kilobytes with each started project. A budget of one megabyte was exhausted by roughly a dozen projects,
+ *       after which `execFile` killed every `pm2 jlist` call with `ERR_CHILD_PROCESS_STDIO_MAXBUFFER` and pm2
+ *       appeared to know no process at all.
+ */
+const PM2_COMMAND_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+
+/**
+ * pm2 error reported when no process of the requested name is registered.
  */
-const PM2_COMMAND_MAX_BUFFER_BYTES = 1024 * 1024;
+const PM2_MISSING_PROCESS_ERROR_PATTERN = /Process or Namespace .* not found/u;
 
 /**
  * Status snapshot for one pm2 process.
@@ -137,10 +150,10 @@ export type StartAgentProjectRuntimePm2ProcessOptions = {
  * @returns `true` on production Linux unless explicitly disabled.
  */
 export function isAgentProjectRuntimePm2Enabled(): boolean {
-    const configuredValue = process.env[PTBK_AGENT_PROJECT_RUNTIME_PM2_ENABLED_ENV]?.trim().toLowerCase();
+    const configuredFlag = resolveAgentProjectRuntimeEnvironmentFlag(PTBK_AGENT_PROJECT_RUNTIME_PM2_ENABLED_ENV);
 
-    if (configuredValue) {
-        return ['1', 'true', 'yes', 'y'].includes(configuredValue);
+    if (configuredFlag !== null) {
+        return configuredFlag;
     }
 
     return process.platform === 'linux' && process.env.NODE_ENV === 'production';
@@ -188,25 +201,46 @@ export async function startAgentProjectRuntimePm2Process(
 }
 
 /**
- * Stops one pm2 project process when it exists.
+ * Deletes every pm2 process registered under one name.
+ *
+ * Note: The delete is never skipped because pm2 could not be asked for its current process list. `pm2 start`
+ *       appends another process instead of replacing the existing one when a process of the same name is already
+ *       registered, so a delete which silently does nothing turns every later start of the same project into one
+ *       more duplicate. Only pm2 itself reporting an unknown name counts as "already gone", every other failure
+ *       is reported to the caller, which then must not start the project again.
  *
  * @param processName - pm2 process name.
  */
 export async function stopAgentProjectRuntimePm2Process(processName: string | null | undefined): Promise<void> {
-    if (!processName) {
+    if (!processName || !isAgentProjectRuntimePm2Enabled()) {
         return;
     }
 
-    const status = await resolveAgentProjectRuntimePm2Status(processName);
+    try {
+        await execFileAsync(PM2_COMMAND, ['delete', processName], {
+            maxBuffer: PM2_COMMAND_MAX_BUFFER_BYTES,
+            windowsHide: true,
+        });
+    } catch (error) {
+        if (isPm2MissingProcessError(error)) {
+            return;
+        }
 
-    if (!status.isKnown) {
-        return;
+        throw new UnexpectedError(
+            spaceTrim(
+                (block) => `
+                    Failed to delete the pm2 process \`${processName}\` of an agent project.
+
+                    Starting the project again would register one more pm2 process of the same name instead of
+                    replacing the existing one, so the project was left alone.
+
+                    **Cause:**
+                    ${block(error instanceof Error ? error.message : String(error))}
+                `,
+            ),
+        );
     }
 
-    await execFileAsync(PM2_COMMAND, ['delete', processName], {
-        maxBuffer: PM2_COMMAND_MAX_BUFFER_BYTES,
-        windowsHide: true,
-    });
     await savePm2ProcessList();
 }
 
@@ -365,6 +399,19 @@ async function savePm2ProcessList(): Promise<void> {
     });
 }
 
+/**
+ * Returns whether one failed pm2 command failed only because pm2 knows no process of the requested name.
+ */
+function isPm2MissingProcessError(error: unknown): boolean {
+    if (!error || typeof error !== 'object') {
+        return false;
+    }
+
+    const { stderr } = error as { readonly stderr?: unknown };
+
+    return typeof stderr === 'string' && PM2_MISSING_PROCESS_ERROR_PATTERN.test(stderr);
+}
+
 /**
  * Creates the fallback status for missing or unavailable pm2 processes.
  */

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

@@ -13,6 +13,7 @@ import type {
     AgentProjectRuntimeMode,
     AgentProjectRuntimeStatus,
 } from './AgentProjectRuntimeInfo';
+import { isSameAgentProjectIdentity } from './agentProjectIdentity';
 import {
     AGENT_PROJECT_RUNTIME_DEFAULT_DEV_COMMAND,
     AGENT_PROJECT_RUNTIME_HOST,
@@ -21,6 +22,7 @@ import {
     AGENT_PROJECT_RUNTIME_STOP_POLL_INTERVAL_MS,
     AGENT_PROJECT_RUNTIME_STOP_TIMEOUT_MS,
 } from './agentProjectRuntimeConstants';
+import { setAgentProjectRuntimeDesiredState } from './agentProjectRuntimeDesiredState';
 import {
     assignAgentProjectDomain,
     resolveAgentProjectDomainRecord,
@@ -207,6 +209,9 @@ export async function assignAgentProjectPort(
 /**
  * Starts one project using its npm `dev` script when available, otherwise a static file server.
  *
+ * Starting a project also makes it expected to be running, so a project which was stopped earlier
+ * is started again by itself after the next server restart.
+ *
  * @param options - Agent and project identification.
  * @returns Runtime info for the started project.
  */
@@ -216,6 +221,15 @@ export async function startAgentProjectRuntime(
     await hydrateAgentProjectRuntimeRegistryState();
 
     const project = await resolveExistingAgentProject(options);
+
+    // Note: The intent is remembered before the project is started so that a project which fails to
+    //       start now is still tried again by the next automatic pass.
+    await setAgentProjectRuntimeDesiredState({
+        agentPermanentId: options.agentPermanentId,
+        projectName: project.projectName,
+        desiredState: 'running',
+    });
+
     const isDevRuntime = await hasAgentProjectDevScript(project.absolutePath);
     const preparedStart = await prepareAgentProjectRuntimeStart(options, project);
 
@@ -375,7 +389,9 @@ export async function listAgentProjectRuntimes(): Promise<ReadonlyArray<AgentPro
 }
 
 /**
- * Terminates one runtime by runtime id.
+ * Terminates one runtime by runtime id on explicit request.
+ *
+ * The project is remembered as stopped, so it stays down until it is started again.
  *
  * @param runtimeId - Runtime id.
  * @returns Terminated runtime info or `null` when it no longer exists.
@@ -389,14 +405,19 @@ export async function terminateAgentProjectRuntimeById(runtimeId: string): Promi
         return null;
     }
 
-    await terminateAgentProjectRuntimeRecord(runtimeRecord);
-    getAgentProjectRuntimeRegistryState().runtimesById.delete(runtimeId);
-    await persistAgentProjectRuntimeRegistryState();
-    return toAgentProjectRuntimeInfo(runtimeRecord);
+    await setAgentProjectRuntimeDesiredState({
+        agentPermanentId: runtimeRecord.agentPermanentId,
+        projectName: runtimeRecord.projectName,
+        desiredState: 'stopped',
+    });
+
+    return await removeAgentProjectRuntimeById(runtimeId);
 }
 
 /**
- * Terminates any runtime assigned to one project.
+ * Terminates any runtime assigned to one project on explicit request.
+ *
+ * The project is remembered as stopped, so it stays down until it is started again.
  *
  * @param options - Agent and project identification.
  * @returns Terminated runtime info or `null` when no runtime exists.
@@ -405,30 +426,64 @@ export async function terminateAgentProjectRuntimeForProject(
     options: AgentProjectRuntimeProjectOptions,
 ): Promise<AgentProjectRuntimeInfo | null> {
     await hydrateAgentProjectRuntimeRegistryState();
+    await setAgentProjectRuntimeDesiredState({
+        agentPermanentId: options.agentPermanentId,
+        projectName: options.projectName,
+        desiredState: 'stopped',
+    });
 
-    const runtimeRecord = findAgentProjectRuntimeRecord(options.agentPermanentId, options.projectName);
+    return await removeAgentProjectRuntimeForProject(options);
+}
+
+/**
+ * Terminates all project runtimes in the current process.
+ *
+ * This is used by tests and process-level cleanup, so it says nothing about which projects should
+ * be running — every project keeps the state it is expected to be in.
+ */
+export async function terminateAllAgentProjectRuntimes(): Promise<void> {
+    await hydrateAgentProjectRuntimeRegistryState();
+
+    const runtimeIds = [...getAgentProjectRuntimeRegistryState().runtimesById.keys()];
+
+    await Promise.all(runtimeIds.map((runtimeId) => removeAgentProjectRuntimeById(runtimeId)));
+}
+
+/**
+ * Terminates one runtime by runtime id without changing which state the project is expected to be in.
+ *
+ * @param runtimeId - Runtime id.
+ * @returns Terminated runtime info or `null` when it no longer exists.
+ */
+async function removeAgentProjectRuntimeById(runtimeId: string): Promise<AgentProjectRuntimeInfo | null> {
+    const runtimeRecord = getAgentProjectRuntimeRegistryState().runtimesById.get(runtimeId);
 
     if (!runtimeRecord) {
         return null;
     }
 
     await terminateAgentProjectRuntimeRecord(runtimeRecord);
-    getAgentProjectRuntimeRegistryState().runtimesById.delete(runtimeRecord.id);
+    getAgentProjectRuntimeRegistryState().runtimesById.delete(runtimeId);
     await persistAgentProjectRuntimeRegistryState();
     return toAgentProjectRuntimeInfo(runtimeRecord);
 }
 
 /**
- * Terminates all project runtimes in the current process.
+ * Terminates the runtime of one project without changing which state the project is expected to be in.
  *
- * This is used by tests and process-level cleanup.
+ * @param options - Agent and project identification.
+ * @returns Terminated runtime info or `null` when no runtime exists.
  */
-export async function terminateAllAgentProjectRuntimes(): Promise<void> {
-    await hydrateAgentProjectRuntimeRegistryState();
+async function removeAgentProjectRuntimeForProject(
+    options: AgentProjectRuntimeProjectOptions,
+): Promise<AgentProjectRuntimeInfo | null> {
+    const runtimeRecord = findAgentProjectRuntimeRecord(options.agentPermanentId, options.projectName);
 
-    const runtimeIds = [...getAgentProjectRuntimeRegistryState().runtimesById.keys()];
+    if (!runtimeRecord) {
+        return null;
+    }
 
-    await Promise.all(runtimeIds.map((runtimeId) => terminateAgentProjectRuntimeById(runtimeId)));
+    return await removeAgentProjectRuntimeById(runtimeRecord.id);
 }
 
 /**
@@ -438,7 +493,7 @@ async function prepareAgentProjectRuntimeStart(
     options: AgentProjectRuntimeProjectOptions,
     project: NonNullable<Awaited<ReturnType<typeof resolveAgentProjectInfo>>>,
 ): Promise<PreparedAgentProjectRuntimeStart> {
-    await terminateAgentProjectRuntimeForProject({
+    await removeAgentProjectRuntimeForProject({
         agentPermanentId: options.agentPermanentId,
         projectName: project.projectName,
     });
@@ -595,12 +650,16 @@ function startChildProcessAgentProjectDevRuntime(runtimeRecord: MutableAgentProj
 }
 
 /**
- * Applies installer-managed nginx and SSL configuration when a public domain exists.
+ * Applies installer-managed nginx and SSL configuration when a project domain was added or changed.
+ *
+ * The generated nginx configuration resolves the runtime port of a project per request, so it only
+ * has to be regenerated when the set of project domains itself changes — never when an unchanged
+ * project is merely started again on a new port.
  */
 async function applyAgentProjectRuntimePublicConfiguration(
     domainAssignment: AgentProjectDomainAssignment,
 ): Promise<void> {
-    if (!domainAssignment.record) {
+    if (!domainAssignment.record || !domainAssignment.isChanged) {
         return;
     }
 
@@ -642,14 +701,8 @@ function findAgentProjectRuntimeRecord(
     agentPermanentId: string,
     projectName: string,
 ): MutableAgentProjectRuntimeRecord | null {
-    const normalizedAgentPermanentId = agentPermanentId.toLowerCase();
-    const normalizedProjectName = projectName.toLowerCase();
-
     for (const runtimeRecord of getAgentProjectRuntimeRegistryState().runtimesById.values()) {
-        if (
-            runtimeRecord.agentPermanentId.toLowerCase() === normalizedAgentPermanentId &&
-            runtimeRecord.projectName.toLowerCase() === normalizedProjectName
-        ) {
+        if (isSameAgentProjectIdentity(runtimeRecord, { agentPermanentId, projectName })) {
             return runtimeRecord;
         }
     }

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

@@ -0,0 +1,58 @@
+/**
+ * Global key used to keep one mutation queue per agent-project state file across module reloads.
+ */
+const AGENT_PROJECT_STATE_MUTATION_QUEUES_GLOBAL_KEY = '__PROMPTBOOK_AGENT_PROJECT_STATE_MUTATION_QUEUES__';
+
+/**
+ * Global object shape used for process-wide state-file mutation queues.
+ */
+type AgentProjectStateMutationQueuesGlobal = typeof globalThis & {
+    [AGENT_PROJECT_STATE_MUTATION_QUEUES_GLOBAL_KEY]?: Map<string, Promise<void>>;
+};
+
+/**
+ * Runs one agent-project state mutation after all previously queued mutations of the same state file finished.
+ *
+ * The project state files are read-modify-write JSON documents, so two concurrent mutations would
+ * silently drop one of the two changes. Every mutation of one file goes through its own queue, while
+ * mutations of unrelated files still run in parallel.
+ *
+ * @param queueName - Stable name of the mutated state file.
+ * @param operation - Mutation to run exclusively for that state file.
+ * @returns Whatever the mutation returns.
+ */
+export async function runAgentProjectStateMutation<TValue>(
+    queueName: string,
+    operation: () => Promise<TValue>,
+): Promise<TValue> {
+    const mutationQueues = getAgentProjectStateMutationQueues();
+    const previousMutation = mutationQueues.get(queueName) ?? Promise.resolve();
+    let releaseMutation!: () => void;
+
+    mutationQueues.set(
+        queueName,
+        new Promise<void>((resolve) => {
+            releaseMutation = resolve;
+        }),
+    );
+
+    await previousMutation.catch(() => undefined);
+
+    try {
+        return await operation();
+    } finally {
+        releaseMutation();
+    }
+}
+
+/**
+ * Returns the process-wide mutation queues of all agent-project state files.
+ *
+ * @returns Mutable map of pending mutations keyed by state file name.
+ */
+function getAgentProjectStateMutationQueues(): Map<string, Promise<void>> {
+    const mutationQueuesGlobal = globalThis as AgentProjectStateMutationQueuesGlobal;
+    mutationQueuesGlobal[AGENT_PROJECT_STATE_MUTATION_QUEUES_GLOBAL_KEY] ??= new Map();
+
+    return mutationQueuesGlobal[AGENT_PROJECT_STATE_MUTATION_QUEUES_GLOBAL_KEY]!;
+}

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

@@ -61,18 +61,28 @@ export function parseAgentPermanentIdFromDirectoryName(agentDirectoryName: strin
 }
 
 /**
- * Asserts that one path segment coming from a URL cannot escape its parent directory.
+ * Returns whether one path segment stays inside 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.
+ * @returns `true` when the segment is non-empty and cannot escape its parent directory.
  */
-export function assertSafeAgentProjectPathSegment(pathSegment: string, segmentPurpose: string): void {
+export function isSafeAgentProjectPathSegment(pathSegment: string): boolean {
     const isTraversalSegment = pathSegment === '.' || pathSegment === '..';
     const hasPathSeparator = pathSegment.includes('/') || pathSegment.includes('\\');
     const hasNullByte = pathSegment.includes('\0');
 
-    if (pathSegment.length === 0 || isTraversalSegment || hasPathSeparator || hasNullByte) {
+    return pathSegment.length > 0 && !isTraversalSegment && !hasPathSeparator && !hasNullByte;
+}
+
+/**
+ * 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 {
+    if (!isSafeAgentProjectPathSegment(pathSegment)) {
         throw new NotAllowed(
             spaceTrim(`
                 Invalid ${segmentPurpose} \`${pathSegment}\`.

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

@@ -0,0 +1,36 @@
+import { humanizeAgentProjectName } from './humanizeAgentProjectName';
+
+/**
+ * Maximum count of letters shown in one project initials icon.
+ */
+const AGENT_PROJECT_INITIALS_MAX_LENGTH = 3;
+
+/**
+ * Matches the first letter or digit of one word of a project name.
+ */
+const PROJECT_NAME_WORD_INITIAL_REGEX = /[\p{L}\p{N}]/u;
+
+/**
+ * Initials used for a project whose name has no letters and no digits at all.
+ */
+const AGENT_PROJECT_FALLBACK_INITIALS = '#';
+
+/**
+ * Creates the initials shown for one project which has no favicon.
+ *
+ * For example `prague-murders-map` becomes `PMM`.
+ *
+ * @param projectName - Project directory name.
+ * @returns Up to three uppercase initials of the project name.
+ */
+export function createAgentProjectInitials(projectName: string): string {
+    const projectInitials = humanizeAgentProjectName(projectName)
+        .split(/\s+/u)
+        .map((projectNameWord) => PROJECT_NAME_WORD_INITIAL_REGEX.exec(projectNameWord)?.[0] || '')
+        .filter((projectNameInitial) => projectNameInitial !== '')
+        .slice(0, AGENT_PROJECT_INITIALS_MAX_LENGTH)
+        .join('')
+        .toUpperCase();
+
+    return projectInitials || AGENT_PROJECT_FALLBACK_INITIALS;
+}