proteum 1.0.3 → 2.0.0

package/cli/commands/dev.ts

@@ -9,116 +9,226 @@ import { spawn, ChildProcess } from 'child_process';
 // Cor elibs
 import cli from '..';
 import Keyboard from '../utils/keyboard';
+import {
+    isServerHotReloadResult,
+    serverHotReloadMessageType,
+    TServerHotReloadRequest,
+} from '../../common/dev/serverHotReload';
 
 // Configs
 import Compiler from '../compiler';
+import { createDevEventServer } from './devEvents';
+import { ensureProjectAgentSymlinks } from '../utils/agents';
 
 // Core
 import { app, App } from '../app';
 
+/*----------------------------------
+- CONSTANTS
+----------------------------------*/
+
+// Watch rules shared by the dev compiler and hot reload gate.
 const ignoredWatchPathPatterns = /(node_modules\/(?!proteum\/))|(\.generated\/)|(\.cache\/)/;
+const hotReloadableServerPathPatterns = [
+    /^client\/pages\//,
+    /^client\/components\//,
+    /^client\/islands\//,
+    /^server\/routes\//,
+    /^server\/services\/.+\.controller\.[jt]sx?$/,
+];
+const hotReloadableRoots = [() => app.paths.root, () => cli.paths.core.root];
 
 /*----------------------------------
-- COMMANDE
+- MAIN PROCESS
 ----------------------------------*/
-export const run = () => new Promise<void>(async () => {
-
-    const compiler = new Compiler('dev', {
-        before: (compiler) => {
+export const run = () =>
+    new Promise<void>(async () => {
+        ensureProjectAgentSymlinks({ appRoot: app.paths.root, coreRoot: cli.paths.core.root });
+
+        const devEventServer = await createDevEventServer(app.env.router.port + 1);
+        app.devEventPort = devEventServer.port;
+        console.info(`Proteum dev event server ready on http://localhost:${devEventServer.port}/__proteum_hmr`);
+
+        const compiler = new Compiler('dev', {
+            before: (compiler) => {
+                if (compiler.name !== 'server') return;
+
+                const changedFilesList = compiler.modifiedFiles ? [...compiler.modifiedFiles] : [];
+
+                if (changedFilesList.length === 0) {
+                    console.info('Server compilation started. App restart will wait for a successful server build.');
+                } else {
+                    console.info('Need to recompile server because files changed:\n' + changedFilesList.join('\n'));
+                }
+            },
+            after: () => {},
+        });
+
+        const multiCompiler = await compiler.create();
+        const ignoredOutputPaths = [app.paths.bin, app.paths.dev].map(normalizeWatchPath);
+
+        multiCompiler.watch(
+            {
+                // Watching may not work with NFS and machines in VirtualBox
+                // Uncomment next line if it is your case (use true or interval in milliseconds)
+                //poll: 1000,
+
+                // Decrease CPU or memory usage in some file systems
+                // Ignore updated from:
+                // - Node modules except 5HTP core (framework dev mode)
+                // - Generated files during runtime (cause infinite loop. Ex: models.d.ts)
+                // - Webpack output folders (`./dev`, legacy `./bin`)
+                ignored: (watchPath: string) => {
+                    const normalizedPath = normalizeWatchPath(watchPath);
+                    return (
+                        ignoredWatchPathPatterns.test(normalizedPath) ||
+                        ignoredOutputPaths.some(
+                            (outputPath) =>
+                                normalizedPath === outputPath || normalizedPath.startsWith(outputPath + '/'),
+                        )
+                    );
+                },
+
+                //aggregateTimeout: 1000,
+            },
+            async (error, stats) => {
+                if (error) {
+                    compiler.consumeRecentCompilationResults();
+                    console.error('Error in milticompiler.watch', error, stats?.toString());
+                    return;
+                }
+
+                const recentCompilationResults = compiler.consumeRecentCompilationResults();
+                const serverResult = recentCompilationResults.server;
+                const clientResult = recentCompilationResults.client;
+
+                let restartedServer = false;
+
+                if (serverResult?.succeeded === true) {
+                    const changedFilesList = serverResult.modifiedFiles || [];
+                    const canHotReloadServer = isServerHotReloadEligible(changedFilesList);
+
+                    if (canHotReloadServer && requestServerHotReload(changedFilesList)) {
+                        console.log(
+                            'Watch callback. Server route bundle changed; hot-swapping generated routes without restarting app.',
+                        );
+                    } else {
+                        console.log('Watch callback. Reloading app because server bundle changed ...');
+                        startApp(app);
+                        restartedServer = true;
+                        devEventServer.broadcast({ type: 'reload', reason: 'server' });
+                    }
+                }
+
+                if (serverResult?.succeeded === false) {
+                    console.log('Watch callback. Server compilation failed; keeping current app instance.');
+                }
+
+                if (!restartedServer && clientResult?.succeeded === true) {
+                    console.log('Watch callback. Client assets updated; server restart skipped.');
+                    devEventServer.broadcast({ type: 'reload', reason: 'client' });
+                    return;
+                }
+
+                if (!restartedServer && clientResult?.succeeded === false) {
+                    console.log('Watch callback. Client compilation failed; server restart skipped.');
+                    return;
+                }
+
+                if (restartedServer || serverResult?.succeeded === true || serverResult?.succeeded === false) {
+                    return;
+                }
+
+                console.log('Watch callback. No compiler changes were tracked.');
+            },
+        );
+
+        Keyboard.input('ctrl+r', async () => {
+            console.log('Waiting for compilers to be ready ...', Object.keys(compiler.compiling));
+            await Promise.all(Object.values(compiler.compiling));
+
+            console.log('Reloading app ...');
+            startApp(app);
+            devEventServer.broadcast({ type: 'reload', reason: 'manual' });
+        });
+
+        Keyboard.input('ctrl+c', () => {
+            stopApp('CTRL+C Pressed');
+            void devEventServer.close();
+        });
+    });
 
-            const changedFilesList = compiler.modifiedFiles ? [...compiler.modifiedFiles] : [];
+/*----------------------------------
+- STATE
+----------------------------------*/
 
-            if (changedFilesList.length === 0)
-                stopApp("Starting a new compilation");
-            else
-                stopApp("Need to recompile because files changed:\n" + changedFilesList.join('\n'));
+// Current server child process used by the dev loop.
+let cp: ChildProcess | undefined = undefined;
 
-        }, 
-        after: () => {
+/*----------------------------------
+- HELPERS
+----------------------------------*/
 
+async function startApp(app: App) {
+    stopApp('Restart asked');
 
-        }
+    console.info('Launching new server ...');
+    cp = spawn('node', ['--preserve-symlinks', app.outputPath('dev') + '/server.js'], {
+        // sdin, sdout, sderr
+        stdio: ['inherit', 'inherit', 'inherit', 'ipc'],
     });
 
-    const multiCompiler = await compiler.create();
-    const ignoredOutputPaths = [app.paths.bin, app.paths.dev].map(normalizeWatchPath);
-
-    multiCompiler.watch({
-
-        // https://webpack.js.org/configuration/watch/#watchoptions
-        // Watching may not work with NFS and machines in VirtualBox
-        // Uncomment next line if it is your case (use true or interval in milliseconds)
-        //poll: 1000,
-
-        // Decrease CPU or memory usage in some file systems
-        // Ignore updated from:
-        // - Node modules except 5HTP core (framework dev mode)
-        // - Generated files during runtime (cause infinite loop. Ex: models.d.ts)
-        // - Webpack output folders (`./dev`, legacy `./bin`)
-        ignored: (watchPath: string) => {
-            const normalizedPath = normalizeWatchPath(watchPath);
-            return ignoredWatchPathPatterns.test(normalizedPath)
-                || ignoredOutputPaths.some(outputPath =>
-                    normalizedPath === outputPath
-                    || normalizedPath.startsWith(outputPath + '/')
-                );
-        }
+    cp.on('message', (message: unknown) => {
+        if (!isServerHotReloadResult(message)) return;
 
-        //aggregateTimeout: 1000,
-    }, async (error, stats) => {
-
-        if (error) {
-            console.error(`Error in milticompiler.watch`, error, stats?.toString());
+        if (message.type === serverHotReloadMessageType.succeeded) {
+            console.log('Server hot reload applied without restarting app.');
             return;
         }
 
-        console.log("Watch callback. Reloading app ...");
-        startApp(app);
-
-    });
-
-    Keyboard.input('ctrl+r', async () => {
-
-        console.log(`Waiting for compilers to be ready ...`, Object.keys(compiler.compiling));
-        await Promise.all(Object.values(compiler.compiling));
-
-        console.log(`Reloading app ...`);
+        console.error('Server hot reload failed. Restarting app with a fresh process.', message.error || '');
         startApp(app);
-
     });
+}
 
-    Keyboard.input('ctrl+c', () => {
-        stopApp("CTRL+C Pressed");
-    });
-});
+function stopApp(reason: string) {
+    if (cp !== undefined) {
+        console.info(`Killing current server instance (ID: ${cp.pid}) for the following reason:`, reason);
+        cp.kill();
+        cp = undefined;
+    }
+}
 
+function requestServerHotReload(changedFiles: string[]) {
+    if (!cp || !cp.connected) return false;
 
-/*----------------------------------
-- APP RUN
-----------------------------------*/
-let cp: ChildProcess | undefined = undefined;
+    const message: TServerHotReloadRequest = { type: serverHotReloadMessageType.request, changedFiles };
 
-async function startApp( app: App ) {
+    cp.send(message);
+    return true;
+}
 
-    stopApp('Restart asked');
+function isServerHotReloadEligible(changedFiles: string[]) {
+    if (changedFiles.length === 0) return false;
 
-    console.info(`Launching new server ...`);
-    cp = spawn('node', ['' + app.outputPath('dev') + '/server.js', '--preserve-symlinks'], {
+    return changedFiles.every((changedFile) => {
+        const normalizedChangedFile = normalizeWatchPath(changedFile);
 
-        // sdin, sdout, sderr
-        stdio: ['inherit', 'inherit', 'inherit']
+        return hotReloadableRoots.some((getRootPath) => {
+            const normalizedRootPath = normalizeWatchPath(getRootPath());
+            if (
+                normalizedChangedFile !== normalizedRootPath &&
+                !normalizedChangedFile.startsWith(normalizedRootPath + '/')
+            ) {
+                return false;
+            }
 
+            const relativePath = normalizedChangedFile.substring(normalizedRootPath.length + 1);
+            return hotReloadableServerPathPatterns.some((pattern) => pattern.test(relativePath));
+        });
     });
 }
 
-function stopApp( reason: string ) {
-    if (cp !== undefined) {
-        console.info(`Killing current server instance (ID: ${cp.pid}) for the following reason:`, reason);
-        cp.kill();
-    }
-
-}
-
 function normalizeWatchPath(watchPath: string) {
     return path.resolve(watchPath).replace(/\\/g, '/').replace(/\/$/, '');
 }

package/cli/commands/devEvents.ts

@@ -0,0 +1,106 @@
+import http, { type IncomingMessage, type ServerResponse } from 'http';
+
+export type TDevEvent = { type: 'reload'; reason: 'server' | 'manual' | 'client' };
+
+const devEventsPath = '/__proteum_hmr';
+
+export class DevEventServer {
+    private readonly clients = new Set<ServerResponse<IncomingMessage>>();
+    private readonly server = http.createServer(this.handleRequest.bind(this));
+
+    public constructor(public port: number) {}
+
+    public broadcast(event: TDevEvent) {
+        const payload = `data: ${JSON.stringify(event)}\n\n`;
+
+        for (const client of this.clients) {
+            client.write(payload);
+        }
+    }
+
+    public async close() {
+        for (const client of this.clients) {
+            client.end();
+        }
+        this.clients.clear();
+
+        await new Promise<void>((resolve, reject) => {
+            this.server.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+
+                resolve();
+            });
+        });
+    }
+
+    private handleRequest(request: IncomingMessage, response: ServerResponse<IncomingMessage>) {
+        if (request.url !== devEventsPath) {
+            response.statusCode = 404;
+            response.end();
+            return;
+        }
+
+        response.writeHead(200, {
+            'Access-Control-Allow-Origin': '*',
+            'Cache-Control': 'no-store',
+            Connection: 'keep-alive',
+            'Content-Type': 'text/event-stream',
+            'X-Accel-Buffering': 'no',
+        });
+        response.write(': connected\n\n');
+        response.socket?.setKeepAlive(true);
+        this.clients.add(response);
+
+        request.on('close', () => {
+            this.clients.delete(response);
+            response.end();
+        });
+    }
+
+    public static async create(preferredPort: number) {
+        const server = new DevEventServer(preferredPort);
+        server.port = await server.listen(preferredPort);
+        return server;
+    }
+
+    private async listen(preferredPort: number) {
+        const initialPort = Number.isInteger(preferredPort) ? preferredPort : 0;
+
+        return await new Promise<number>((resolve, reject) => {
+            const tryListen = (port: number) => {
+                const onError = (error: NodeJS.ErrnoException) => {
+                    this.server.off('listening', onListening);
+
+                    if (error.code === 'EADDRINUSE' && port !== 0) {
+                        tryListen(port + 1);
+                        return;
+                    }
+
+                    reject(error);
+                };
+
+                const onListening = () => {
+                    this.server.off('error', onError);
+                    const address = this.server.address();
+                    if (!address || typeof address === 'string') {
+                        reject(new Error('Unable to resolve the dev event server port.'));
+                        return;
+                    }
+
+                    resolve(address.port);
+                };
+
+                this.server.once('error', onError);
+                this.server.once('listening', onListening);
+                this.server.listen(port, '0.0.0.0');
+            };
+
+            tryListen(initialPort);
+        });
+    }
+}
+
+export const createDevEventServer = async (preferredPort: number) => DevEventServer.create(preferredPort);

package/cli/commands/init.ts

@@ -11,75 +11,81 @@ import replaceOnce from 'replace-once';
 
 // Cor elibs
 import cli from '..';
+import { ensureProjectAgentSymlinks } from '../utils/agents';
 
 // Configs
-const filesToConfig = [
-    'package.json',
-    'identity.yaml'
-]
+const filesToConfig = ['package.json', 'identity.yaml'];
 
 /*----------------------------------
 - COMMANDE
 ----------------------------------*/
-export const run = () => new Promise<void>(async () => {
-    
-    const config = await prompts([{
-        type: 'text', name: 'name',
-        message: 'Project name ?',
-        initial: "MyProject",
-        validate: value => /[a-z0-9\-\.]/i.test(value) || "Must only include alphanumeric characters, and - . "
-    },{
-        type: 'text', name: 'dirname',
-        message: 'Folder name ?',
-        initial: value => value.toLowerCase(),
-        validate: value => /[a-z0-9\-\.]/.test(value) || "Must only include lowercase alphanumeric characters, and - . "
-    },{
-        type: 'text', name: 'description',
-        message: 'Briefly describe your project to your mom:',
-        initial: "It will revolutionnize the world",
-        validate: value => /[a-z0-9\-\. ]/i.test(value) || "Must only include alphanumeric characters, and - . "
-    },{
-        type: 'toggle', name: 'microservice',
-        message: 'Separate API from the UI servers ?'
-    }]);
+export const run = () =>
+    new Promise<void>(async () => {
+        const config = await prompts([
+            {
+                type: 'text',
+                name: 'name',
+                message: 'Project name ?',
+                initial: 'MyProject',
+                validate: (value) =>
+                    /[a-z0-9\-\.]/i.test(value) || 'Must only include alphanumeric characters, and - . ',
+            },
+            {
+                type: 'text',
+                name: 'dirname',
+                message: 'Folder name ?',
+                initial: (value) => value.toLowerCase(),
+                validate: (value) =>
+                    /[a-z0-9\-\.]/.test(value) || 'Must only include lowercase alphanumeric characters, and - . ',
+            },
+            {
+                type: 'text',
+                name: 'description',
+                message: 'Briefly describe your project to your mom:',
+                initial: 'It will revolutionnize the world',
+                validate: (value) =>
+                    /[a-z0-9\-\. ]/i.test(value) || 'Must only include alphanumeric characters, and - . ',
+            },
+            { type: 'toggle', name: 'microservice', message: 'Separate API from the UI servers ?' },
+        ]);
 
-    const placeholders = {
-        PROJECT_NAME: config.name,
-        PACKAGE_NAME: config.name.toLowerCase(),
-        PROJECT_DESCRIPTION: config.description
-    }
+        const placeholders = {
+            PROJECT_NAME: config.name,
+            PACKAGE_NAME: config.name.toLowerCase(),
+            PROJECT_DESCRIPTION: config.description,
+        };
 
-    const paths = {
-        skeleton: path.join( cli.paths.core.cli, 'skeleton'),
-        project: path.join( process.cwd(), config.dirname)
-    }
+        const paths = {
+            skeleton: path.join(cli.paths.core.cli, 'skeleton'),
+            project: path.join(process.cwd(), config.dirname),
+        };
 
-    // Copy skeleton to cwd/<project-name>
-    console.info("Creating project skeleton ...");
-    fs.copySync( paths.skeleton, paths.project );
-    
-    // Replace placeholders
-    console.info("Configuring project ...");
-    for (const file of filesToConfig) {
-        console.log('- ' + file);
+        // Copy skeleton to cwd/<project-name>
+        console.info('Creating project skeleton ...');
+        fs.copySync(paths.skeleton, paths.project);
 
-        const filepath = path.join( paths.project, file )
-        const content = fs.readFileSync(filepath, 'utf-8');
+        // Sync framework-owned Codex assets into the new project.
+        ensureProjectAgentSymlinks({ appRoot: paths.project, coreRoot: cli.paths.core.root });
 
-        const placeholders_keys = Object.keys(placeholders).map(k => '{{ ' + k + ' }}')
-        const values = Object.values(placeholders);
+        // Replace placeholders
+        console.info('Configuring project ...');
+        for (const file of filesToConfig) {
+            console.log('- ' + file);
 
-        fs.writeFileSync(filepath, 
-            replaceOnce(content, placeholders_keys, values)    
-        );
-    }
+            const filepath = path.join(paths.project, file);
+            const content = fs.readFileSync(filepath, 'utf-8');
 
-    // Npm install
-    console.info("Installing packages ...");
-    cmd.runSync(`cd "${paths.project}" && npm i`);
+            const placeholders_keys = Object.keys(placeholders).map((k) => '{{ ' + k + ' }}');
+            const values = Object.values(placeholders);
 
-    // Run demo app
-    /*console.info("Run demo ...");
-    await cli.shell('5htp dev');*/
+            fs.writeFileSync(filepath, replaceOnce(content, placeholders_keys, values));
+        }
+
+        // Npm install
+        console.info('Installing packages ...');
+        cmd.runSync(`cd "${paths.project}" && npm i`);
 
-});
+        // Run demo app
+        /*console.info("Run demo ...");
+    await cli.shell('5htp dev');*/
+    });

package/cli/commands/lint.ts

@@ -0,0 +1,21 @@
+import cli from '..';
+import { runAppLint } from '../utils/check';
+
+const allowedLintArgs = new Set(['fix']);
+
+const validateLintArgs = () => {
+    const enabledArgs = Object.entries(cli.args)
+        .filter(([name, value]) => name !== 'workdir' && value === true)
+        .map(([name]) => name);
+
+    const invalidArgs = enabledArgs.filter((arg) => !allowedLintArgs.has(arg));
+
+    if (invalidArgs.length > 0)
+        throw new Error(`Unknown lint argument(s): ${invalidArgs.join(', ')}. Allowed values: fix.`);
+};
+
+export const run = async (): Promise<void> => {
+    validateLintArgs();
+
+    await runAppLint({ fix: cli.args.fix === true });
+};

package/cli/commands/refresh.ts

@@ -8,11 +8,11 @@ import Compiler from '../compiler';
 /*----------------------------------
 - COMMAND
 ----------------------------------*/
-export const run = (): Promise<void> => new Promise(async (resolve) => {
+export const run = (): Promise<void> =>
+    new Promise(async (resolve) => {
+        const compiler = new Compiler('dev');
 
-    const compiler = new Compiler('dev');
+        await compiler.refreshGeneratedTypings();
 
-    await compiler.refreshGeneratedTypings();
-
-    resolve();
-});
+        resolve();
+    });

package/cli/commands/typecheck.ts

@@ -0,0 +1,18 @@
+import cli from '..';
+import { refreshGeneratedTypings, runAppTypecheck } from '../utils/check';
+
+const validateTypecheckArgs = () => {
+    const enabledArgs = Object.entries(cli.args).filter(([name, value]) => name !== 'workdir' && value === true);
+
+    if (enabledArgs.length > 0)
+        throw new Error(
+            `Unknown typecheck argument(s): ${enabledArgs.map(([name]) => name).join(', ')}. This command does not accept options.`,
+        );
+};
+
+export const run = async (): Promise<void> => {
+    validateTypecheckArgs();
+
+    await refreshGeneratedTypings();
+    await runAppTypecheck();
+};