proteum 2.1.0 → 2.1.2

package/cli/app/config.ts

@@ -2,20 +2,12 @@
 - DEPENDANCES
 ----------------------------------*/
 
-/*
-    NOTE: This is a copy of core/sever/app/config
-    We can't import core deps here because it will cause the following error:
-        "Can't use import when not a module"
-    It will be possible to import core files when the CLI will be compiled as one output file with tsc
-    And for that, we need to fix the TS errors for the CLI
-*/
-
 // Npm
 import fs from 'fs-extra';
 import yaml from 'yaml';
 
 // Types
-import type { TEnvConfig } from '../../server/app/container/config';
+import { parseProteumEnvConfig, type TProteumLoadedEnvConfig } from '../../common/env/proteumEnv';
 import { logVerbose } from '../runtime/verbose';
 
 /*----------------------------------
@@ -34,18 +26,13 @@ export default class ConfigParser {
         return yaml.parse(rawConfig);
     }
 
-    public env(): TEnvConfig {
-        // We assume that when we run 5htp dev, we're in local
-        // Otherwise, we're in production environment (docker)
-        logVerbose('[app] Using environment:', process.env.NODE_ENV);
-        const envFileName = this.appDir + '/env.yaml';
-        const envFile = this.loadYaml(envFileName);
+    public env(): TProteumLoadedEnvConfig {
+        logVerbose('[app] Loading Proteum env vars from process.env');
         return {
-            ...envFile,
-            router:
-                this.routerPortOverride === undefined
-                    ? envFile.router
-                    : { ...envFile.router, port: this.routerPortOverride },
+            ...parseProteumEnvConfig({
+                appDir: this.appDir,
+                routerPortOverride: this.routerPortOverride,
+            }),
             version: 'CLI',
         };
     }

package/cli/bin.js

@@ -2,6 +2,12 @@
 
 const path = require('path');
 
+const clearInteractiveConsole = () => {
+    if (process.stdout.isTTY !== true || process.env.TERM === 'dumb') return;
+
+    process.stdout.write('\x1B[2J\x1B[3J\x1B[H');
+};
+
 /*
     Why this exists (npm i vs npm link difference)
 
@@ -30,6 +36,8 @@ if (!process.env.TS_NODE_IGNORE) {
 process.env.TS_NODE_PROJECT = path.join(__dirname, 'tsconfig.json');
 process.env.TS_NODE_TRANSPILE_ONLY = '1';
 
+clearInteractiveConsole();
+
 require('ts-node/register/transpile-only');
 
 const { runCli } = require('./index.ts');

package/cli/commands/command.ts

@@ -0,0 +1,243 @@
+import got from 'got';
+import path from 'path';
+import { spawn } from 'child_process';
+import { UsageError } from 'clipanion';
+
+import cli from '..';
+import app from '../app';
+import {
+    normalizeDevCommandPath,
+    type TDevCommandErrorResponse,
+    type TDevCommandExecution,
+    type TDevCommandRunResponse,
+} from '../../common/dev/commands';
+
+const localCommandResultMarker = '__PROTEUM_COMMAND_RESULT__';
+
+const normalizeBaseUrl = (value: string) => value.replace(/\/+$/, '');
+
+const getRouterPortFromManifest = () => {
+    const manifestFilepath = path.join(cli.args.workdir as string, '.proteum', 'manifest.json');
+    if (!require('fs-extra').existsSync(manifestFilepath)) return undefined;
+
+    const manifest = require('fs-extra').readJsonSync(manifestFilepath, { throws: false }) as
+        | { env?: { resolved?: { routerPort?: number } } }
+        | undefined;
+    const port = manifest?.env?.resolved?.routerPort;
+
+    if (typeof port !== 'number' || port <= 0) return undefined;
+
+    return String(port);
+};
+
+const getRouterPort = () => {
+    const overridePort = typeof cli.args.port === 'string' && cli.args.port ? cli.args.port : '';
+    if (overridePort) return overridePort;
+
+    const envPort = process.env.PORT?.trim();
+    if (envPort) return envPort;
+
+    const manifestPort = getRouterPortFromManifest();
+    if (manifestPort) return manifestPort;
+
+    throw new UsageError(
+        `Could not determine the router port from PORT or .proteum/manifest.json in ${cli.args.workdir as string}. Pass --port or --url explicitly.`,
+    );
+};
+
+const getRouterBaseUrls = () => {
+    const explicitUrl = typeof cli.args.url === 'string' && cli.args.url ? cli.args.url.trim() : '';
+    if (explicitUrl) return [normalizeBaseUrl(explicitUrl)];
+
+    const port = getRouterPort();
+    return [...new Set([`http://127.0.0.1:${port}`, `http://localhost:${port}`, `http://[::1]:${port}`])];
+};
+
+const getCommandErrorMessage = (body: TDevCommandErrorResponse | object | string | undefined, statusCode: number) => {
+    if (typeof body === 'object' && body !== null && 'error' in body && typeof body.error === 'string') {
+        return body.error;
+    }
+
+    return `Command request failed with status ${statusCode}.`;
+};
+
+const requestJson = async <TResponse>(pathname: string, options?: { method?: 'GET' | 'POST'; json?: object }) => {
+    const attempts: string[] = [];
+
+    for (const baseUrl of getRouterBaseUrls()) {
+        try {
+            const response = await got(`${baseUrl}${pathname}`, {
+                method: options?.method || 'GET',
+                json: options?.json,
+                responseType: 'json',
+                throwHttpErrors: false,
+                retry: { limit: 0 },
+            });
+
+            if (response.statusCode >= 400) {
+                throw new UsageError(
+                    getCommandErrorMessage(response.body as TDevCommandErrorResponse | object | string | undefined, response.statusCode),
+                );
+            }
+
+            return response.body as TResponse;
+        } catch (error) {
+            if (error instanceof UsageError) throw error;
+
+            const message = error instanceof Error ? error.message : String(error);
+            attempts.push(`${baseUrl}${pathname}: ${message}`);
+        }
+    }
+
+    throw new UsageError(
+        [
+            'Could not reach the Proteum command server.',
+            ...attempts.map((attempt) => `- ${attempt}`),
+            'Make sure the app is running with `proteum dev`, or omit --port/--url to run the command locally.',
+        ].join('\n'),
+    );
+};
+
+const printJson = (value: object) => {
+    console.log(JSON.stringify(value, null, 2));
+};
+
+const renderExecution = (execution: TDevCommandExecution) => {
+    const lines = [
+        `Command ${execution.command.path}`,
+        `- status=${execution.status} durationMs=${execution.durationMs}`,
+        `- source=${execution.command.filepath}:${execution.command.sourceLocation.line}:${execution.command.sourceLocation.column}`,
+    ];
+
+    if (execution.errorMessage) {
+        lines.push(`- error=${execution.errorMessage}`);
+    } else if (execution.result?.json !== undefined) {
+        lines.push('Result');
+        lines.push(JSON.stringify(execution.result.json, null, 2));
+    } else if (execution.result?.summary !== undefined) {
+        lines.push('Result');
+        lines.push(JSON.stringify(execution.result.summary, null, 2));
+    } else {
+        lines.push('- result=undefined');
+    }
+
+    return lines.join('\n');
+};
+
+const runLocalCommand = async (commandPath: string) => {
+    if (app.env.profile !== 'dev') {
+        throw new UsageError(`Proteum commands are only available when ENV_PROFILE=dev. Current profile: ${app.env.profile}.`);
+    }
+
+    const runnerFilepath = path.join(cli.paths.core.root, 'cli', 'commands', 'commandLocalRunner.js');
+
+    return await new Promise<TDevCommandExecution>((resolve, reject) => {
+        const stdoutChunks: Buffer[] = [];
+        const stderrChunks: Buffer[] = [];
+        const child = spawn(process.execPath, [runnerFilepath, app.paths.root, commandPath], {
+            cwd: app.paths.root,
+            env: { ...process.env },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+
+        child.stdout.on('data', (chunk: Buffer | string) => {
+            stdoutChunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        });
+
+        child.stderr.on('data', (chunk: Buffer | string) => {
+            stderrChunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        });
+
+        child.on('error', (error) => reject(error));
+        child.on('close', (exitCode) => {
+            const stdout = Buffer.concat(stdoutChunks).toString('utf8');
+            const stderr = Buffer.concat(stderrChunks).toString('utf8');
+            const markerLine = stdout
+                .split(/\r?\n/)
+                .find((line) => line.startsWith(localCommandResultMarker));
+
+            if (stderr.trim()) {
+                process.stderr.write(stderr.endsWith('\n') ? stderr : `${stderr}\n`);
+            }
+
+            if (!markerLine) {
+                reject(
+                    new Error(
+                        [
+                            `Local command runner exited without returning a structured result (exit code ${exitCode ?? 'unknown'}).`,
+                            stdout.trim() ? `stdout:\n${stdout.trim()}` : undefined,
+                        ]
+                            .filter(Boolean)
+                            .join('\n\n'),
+                    ),
+                );
+                return;
+            }
+
+            const payload = JSON.parse(markerLine.slice(localCommandResultMarker.length)) as
+                | { execution: TDevCommandExecution }
+                | { error: string };
+
+            if ('execution' in payload) {
+                if (exitCode && exitCode !== 0) {
+                    const error = new Error(payload.execution.errorMessage || `Command "${commandPath}" failed.`) as Error & {
+                        execution?: TDevCommandExecution;
+                    };
+
+                    error.execution = payload.execution;
+                    reject(error);
+                    return;
+                }
+
+                resolve(payload.execution);
+                return;
+            }
+
+            reject(new Error(payload.error || `Command "${commandPath}" failed.`));
+        });
+    });
+};
+
+export const run = async () => {
+    const rawPath = typeof cli.args.path === 'string' ? cli.args.path : '';
+    const commandPath = normalizeDevCommandPath(rawPath);
+    const shouldPrintJson = cli.args.json === true;
+    const shouldUseRemoteServer =
+        (typeof cli.args.port === 'string' && cli.args.port.length > 0) ||
+        (typeof cli.args.url === 'string' && cli.args.url.length > 0);
+
+    if (!commandPath) {
+        throw new UsageError('A command path is required. Example: proteum command diagnostics/ping');
+    }
+
+    try {
+        const execution = shouldUseRemoteServer
+            ? (await requestJson<TDevCommandRunResponse>('/__proteum/commands/run', {
+                  method: 'POST',
+                  json: { path: commandPath },
+              })).execution
+            : await runLocalCommand(commandPath);
+
+        if (shouldPrintJson) {
+            printJson({ execution });
+            return;
+        }
+
+        console.log(renderExecution(execution));
+    } catch (error) {
+        if (error instanceof Error && 'execution' in error && typeof error.execution === 'object' && error.execution) {
+            const execution = error.execution as TDevCommandExecution;
+
+            if (shouldPrintJson) {
+                printJson({ execution });
+            } else {
+                console.log(renderExecution(execution));
+            }
+
+            process.exitCode = 1;
+            return;
+        }
+
+        throw error;
+    }
+};

package/cli/commands/commandLocalRunner.js

@@ -0,0 +1,198 @@
+const path = require('path');
+const net = require('net');
+const { spawn } = require('child_process');
+const tsNode = require('ts-node');
+
+const resultMarker = '__PROTEUM_COMMAND_RESULT__';
+
+const printPayload = (payload) => {
+    process.stdout.write(`${resultMarker}${JSON.stringify(payload)}\n`);
+};
+
+const fail = (error, execution) => {
+    if (execution) {
+        printPayload({ execution });
+        process.exitCode = 1;
+        return;
+    }
+
+    printPayload({ error: error instanceof Error ? error.message : String(error) });
+    process.exitCode = 1;
+};
+
+const getAvailablePort = async () =>
+    await new Promise((resolve, reject) => {
+        const server = net.createServer();
+
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+
+            if (!address || typeof address === 'string') {
+                server.close(() => reject(new Error('Could not determine a local port for the command runner.')));
+                return;
+            }
+
+            server.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+
+                resolve(address.port);
+            });
+        });
+    });
+
+const closeMultiCompiler = async (multiCompiler) =>
+    await new Promise((resolve, reject) => {
+        multiCompiler.close((error) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+
+            resolve();
+        });
+    });
+
+const runCompiler = async (compiler) => {
+    const multiCompiler = await compiler.create();
+
+    try {
+        await new Promise((resolve, reject) => {
+            multiCompiler.run((error, stats) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+
+                if (stats && stats.hasErrors()) {
+                    reject(new Error('Compilation failed for the local dev command runner.'));
+                    return;
+                }
+
+                resolve();
+            });
+        });
+    } finally {
+        compiler.dispose();
+        await closeMultiCompiler(multiCompiler);
+    }
+};
+
+const waitForServerReady = async (child) =>
+    await new Promise((resolve, reject) => {
+        let settled = false;
+
+        const finish = (callback, value) => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timeout);
+            child.off('message', onMessage);
+            child.off('error', onError);
+            child.off('exit', onExit);
+            callback(value);
+        };
+
+        const onMessage = (message) => {
+            if (!message || message.type !== 'proteum:server-ready' || typeof message.publicUrl !== 'string') return;
+            finish(resolve, message.publicUrl);
+        };
+
+        const onError = (error) => finish(reject, error);
+        const onExit = (code, signal) =>
+            finish(reject, new Error(`Local command server exited before becoming ready (code=${code}, signal=${signal}).`));
+        const timeout = setTimeout(
+            () => finish(reject, new Error('Timed out while waiting for the local command server to become ready.')),
+            30000,
+        );
+
+        child.on('message', onMessage);
+        child.once('error', onError);
+        child.once('exit', onExit);
+    });
+
+const stopServerProcess = async (child) => {
+    if (!child || child.exitCode !== null || child.signalCode !== null) return;
+
+    child.kill('SIGTERM');
+
+    await new Promise((resolve) => {
+        const timeout = setTimeout(() => {
+            if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
+        }, 5000);
+
+        child.once('exit', () => {
+            clearTimeout(timeout);
+            resolve();
+        });
+    });
+};
+
+const requestCommand = async (baseUrl, commandPath) => {
+    const response = await fetch(`${baseUrl}/__proteum/commands/run`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ path: commandPath }),
+    });
+    const body = await response.json();
+
+    if (body && typeof body === 'object' && body.execution) {
+        return { statusCode: response.status, execution: body.execution };
+    }
+
+    throw new Error((body && body.error) || `Command request failed with status ${response.status}.`);
+};
+
+(async () => {
+    const [, , appRootArg = '', commandPath = ''] = process.argv;
+    const appRoot = path.resolve(appRootArg);
+
+    if (!appRootArg || !commandPath) {
+        fail(new Error('commandLocalRunner requires <appRoot> and <commandPath>.'));
+        return;
+    }
+
+    process.chdir(appRoot);
+
+    tsNode.register({
+        transpileOnly: true,
+        project: path.join(__dirname, '..', 'tsconfig.json'),
+        files: true,
+    });
+
+    const port = await getAvailablePort();
+    const cli = require('../context.ts').default;
+    cli.setArgs({ workdir: appRoot, path: commandPath, port: String(port), url: '', json: true });
+
+    const app = require('../app/index.ts').default;
+    const Compiler = require('../compiler/index.ts').default;
+
+    if (app.env.profile !== 'dev') {
+        fail(new Error(`Proteum commands are only available when ENV_PROFILE=dev. Current profile: ${app.env.profile}.`));
+        return;
+    }
+
+    const compiler = new Compiler('dev');
+    await runCompiler(compiler);
+
+    const serverProcess = spawn(process.execPath, ['--preserve-symlinks', path.join(app.outputPath('dev'), 'server.js')], {
+        cwd: app.paths.root,
+        stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+    });
+
+    try {
+        const publicUrl = await waitForServerReady(serverProcess);
+        const { statusCode, execution } = await requestCommand(publicUrl, commandPath);
+
+        printPayload({ execution });
+        if (statusCode >= 400 || execution.status === 'error') {
+            process.exitCode = 1;
+        }
+    } finally {
+        await stopServerProcess(serverProcess);
+    }
+})().catch((error) => {
+    fail(error);
+});

package/cli/commands/create.ts

@@ -0,0 +1,5 @@
+import { runCreateScaffold } from '../scaffold';
+
+export const run = async (): Promise<void> => {
+    await runCreateScaffold();
+};

package/cli/commands/deploy/web.ts

@@ -45,8 +45,7 @@ export async function run() {
         { spaces: 4 },
     );
 
-    // Copy config file
-    fs.copyFileSync(app.paths.root + (simulate ? '/env.yaml' : '/env.server.yaml'), temp + '/env.yaml');
+    // Deployment now relies on exported ENV_*, URL, TRACE_*, and PORT variables instead of copied env config files.
 
     // Compile & Run Docker
     await cli.shell(`docker compose up --build`);

package/cli/commands/dev.ts

@@ -5,6 +5,8 @@
 // Npm
 import path from 'path';
 import { spawn, ChildProcess } from 'child_process';
+import fs from 'fs-extra';
+import type { FSWatcher } from 'fs';
 
 // Cor elibs
 import cli from '..';
@@ -20,7 +22,7 @@ import {
 import Compiler from '../compiler';
 import { createDevEventServer } from './devEvents';
 import { ensureProjectAgentSymlinks } from '../utils/agents';
-import { renderDevSession, renderServerReadyBanner } from '../presentation/devSession';
+import { renderDevSession, renderServerReadyBanner, renderDevShutdownBanner } from '../presentation/devSession';
 import { logVerbose } from '../runtime/verbose';
 
 // Core
@@ -31,7 +33,7 @@ import { app, App } from '../app';
 ----------------------------------*/
 
 // Watch rules shared by the dev compiler and hot reload gate.
-const ignoredWatchPathPatterns = /(node_modules\/(?!proteum\/))|(\.generated\/)|(\.cache\/)|(\.proteum\/)/;
+const ignoredWatchPathPatterns = /(node_modules\/(?!proteum\/))|(\.generated\/)|(\.cache\/)|(\.proteum\/)|(\/var\/traces\/)/;
 const hotReloadableServerPathPatterns = [
     /^client\/pages\//,
     /^client\/components\//,
@@ -50,6 +52,7 @@ let cp: ChildProcess | undefined = undefined;
 let devSessionStopping = false;
 let appProcessOperation: Promise<void> = Promise.resolve();
 type TDevWatching = ReturnType<Awaited<ReturnType<Compiler['create']>>['watch']>;
+type TIndexedSourceWatching = { close: () => Promise<void> };
 
 /*----------------------------------
 - HELPERS
@@ -110,6 +113,22 @@ const createIgnoredWatchPattern = (outputPaths: string[]) =>
 const getDevAppName = (app: App) =>
     app.identity.web?.fullTitle || app.identity.web?.title || app.identity.name || app.packageJson.name || app.paths.root;
 
+const cleanupPersistedDevTraces = async (app: App) => {
+    const tracesRoot = path.join(app.paths.root, 'var', 'traces');
+    if (!(await fs.pathExists(tracesRoot))) return;
+
+    const entries = await fs.readdir(tracesRoot);
+    const removableEntries = entries.filter((entry) => entry !== 'exports');
+    if (removableEntries.length === 0) return;
+
+    await Promise.all(removableEntries.map((entry) => fs.remove(path.join(tracesRoot, entry))));
+
+    const remainingEntries = await fs.readdir(tracesRoot).catch(() => []);
+    if (remainingEntries.length === 0) {
+        await fs.remove(tracesRoot);
+    }
+};
+
 const signalAppProcess = (child: ChildProcess, signal: NodeJS.Signals) => {
     try {
         if (process.platform !== 'win32' && child.pid !== undefined) {
@@ -155,6 +174,7 @@ async function startApp(app: App) {
                         await renderServerReadyBanner({
                             appName: getDevAppName(app),
                             publicUrl: message.publicUrl,
+                            routerPort: app.env.router.port,
                         }),
                     );
                 })();
@@ -237,6 +257,78 @@ function normalizeWatchPath(watchPath: string) {
     return path.resolve(watchPath).replace(/\\/g, '/').replace(/\/$/, '');
 }
 
+const indexedSourceWatchRules: { compilerName: 'server'; root: () => string; relativePathPattern: RegExp }[] = [
+    { compilerName: 'server', root: () => app.paths.root, relativePathPattern: /^commands(?:\/|$)/ },
+    { compilerName: 'server', root: () => cli.paths.core.root, relativePathPattern: /^commands(?:\/|$)/ },
+];
+
+const closeFsWatcher = async (watcher: FSWatcher) => {
+    await new Promise<void>((resolve) => {
+        watcher.once('close', () => resolve());
+        watcher.close();
+    });
+};
+
+const createIndexedSourceWatching = ({
+    compiler,
+    watching,
+}: {
+    compiler: Compiler;
+    watching: TDevWatching;
+}): TIndexedSourceWatching => {
+    const watchers: FSWatcher[] = [];
+    const pendingChanges = new Map<'server', Set<string>>();
+    let invalidateTimer: NodeJS.Timeout | undefined;
+
+    const flushInvalidate = () => {
+        invalidateTimer = undefined;
+
+        for (const [compilerName, changedFiles] of pendingChanges) {
+            compiler.noteManualModifiedFiles(compilerName, [...changedFiles]);
+        }
+
+        pendingChanges.clear();
+        logVerbose('Indexed source files changed. Invalidating the dev compiler to refresh generated artifacts.');
+        watching.invalidate();
+    };
+
+    const queueInvalidate = (compilerName: 'server', filepath: string) => {
+        const normalizedFilepath = normalizeWatchPath(filepath);
+        const changedFiles = pendingChanges.get(compilerName) || new Set<string>();
+
+        changedFiles.add(normalizedFilepath);
+        pendingChanges.set(compilerName, changedFiles);
+
+        if (invalidateTimer) return;
+        invalidateTimer = setTimeout(flushInvalidate, 40);
+    };
+
+    for (const watchRule of indexedSourceWatchRules) {
+        const rootPath = watchRule.root();
+
+        watchers.push(
+            fs.watch(rootPath, { recursive: true }, (eventType, filename) => {
+                const relativePath = typeof filename === 'string' ? filename.replace(/\\/g, '/').replace(/^\.\//, '') : '';
+                if (relativePath && !watchRule.relativePathPattern.test(relativePath)) return;
+                if (eventType !== 'rename' && relativePath) return;
+
+                queueInvalidate(watchRule.compilerName, relativePath ? path.join(rootPath, relativePath) : rootPath);
+            }),
+        );
+    }
+
+    return {
+        close: async () => {
+            if (invalidateTimer) {
+                clearTimeout(invalidateTimer);
+                invalidateTimer = undefined;
+            }
+
+            await Promise.all(watchers.map((watcher) => closeFsWatcher(watcher)));
+        },
+    };
+};
+
 /*----------------------------------
 - MAIN PROCESS
 ----------------------------------*/
@@ -340,6 +432,7 @@ export const run = async () => {
             logVerbose('Watch callback. No compiler changes were tracked.');
         },
     );
+    const indexedSourceWatching = createIndexedSourceWatching({ compiler, watching });
 
     let shuttingDownPromise: Promise<void> | undefined;
 
@@ -349,10 +442,13 @@ export const run = async () => {
         devSessionStopping = true;
         shuttingDownPromise = (async () => {
             logVerbose('Stopping the Proteum dev session ...', reason);
+            await indexedSourceWatching.close();
             await closeWatching(watching);
             compiler.dispose();
             await stopApp(reason);
+            await cleanupPersistedDevTraces(app);
             await devEventServer.close();
+            console.info(await renderDevShutdownBanner());
         })();
 
         return shuttingDownPromise;