proteum 1.0.0 → 1.0.3

package/AGENTS.md

@@ -0,0 +1,9 @@
+# Workflow
+
+- Everytime I input error messages without any instructions, don't implement fixes.
+Instead, ivestigate the potential causes of the errors, and for each: 
+  1. Evaluate / quantify the probabiliies 
+  2. Give why and 
+  3. Suggest how to fix it
+- When you have finished your work, summarize in one top-level short sentence ALL the changes you made since the beginning of the WHOLE conversation. Output as "Commit message". Max 90 characters.
+

package/cli/app/config.ts

@@ -0,0 +1,61 @@
+/*----------------------------------
+- 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';
+
+/*----------------------------------
+- LOADE
+----------------------------------*/
+export default class ConfigParser {
+
+    public constructor(
+        public appDir: string,
+        public envName?: string,
+        public routerPortOverride?: number
+    ) {
+
+    }
+
+    private loadYaml( filepath: string ) {
+        console.info(`Loading config ${filepath}`);
+        const rawConfig = fs.readFileSync(filepath, 'utf-8');
+        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)
+        console.log("[app] Using environment:", process.env.NODE_ENV);
+        const envFileName = this.appDir + '/env.yaml';
+        const envFile = this.loadYaml( envFileName );
+        return {
+            ...envFile,
+            router: this.routerPortOverride === undefined
+                ? envFile.router
+                : {
+                    ...envFile.router,
+                    port: this.routerPortOverride
+                },
+            version: 'CLI'
+        }
+    }
+
+    public identity() {
+        const identityFile = this.appDir + '/identity.yaml';
+        return this.loadYaml( identityFile );
+    }
+}

package/cli/app/index.ts

@@ -0,0 +1,227 @@
+/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+// npm
+import path from 'path';
+import TsAlias from 'ts-alias';
+import fs from 'fs-extra';
+
+// Cre
+import cli from '..';
+
+// Specific
+import ConfigParser from './config';
+import type { TEnvConfig } from '../../server/app/container/config';
+
+/*----------------------------------
+- TYPES
+----------------------------------*/
+
+export type TAppSide = 'server' | 'client'
+
+type TServiceSetup = {
+    id: string,
+    name: string,
+    config: {},
+    subservices: TServiceSubservices,
+    type: 'service.setup'
+}
+
+type TServiceRef = {
+    refTo: string,
+    type: 'service.ref'
+}
+
+type TServiceSubservices = {
+    [key: string]: TServiceSetup | TServiceRef
+}
+
+const parseRouterPortOverride = (
+    rawPort: string | boolean | string[] | undefined
+): number | undefined => {
+
+    if (rawPort === undefined || rawPort === '')
+        return undefined;
+
+    if (typeof rawPort !== 'string')
+        throw new Error(`Invalid value for -port: expected a numeric value.`);
+
+    const port = Number(rawPort);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new Error(`Invalid value for -port: "${rawPort}". Expected an integer between 1 and 65535.`);
+
+    return port;
+}
+
+/*----------------------------------
+- SERVICE
+----------------------------------*/
+export class App {
+
+    // config
+    // WARNING: High level config files (env and services) shouldn't be loaded from the CLI
+    //  The CLI will be run on CircleCI, and no env file should be sent to this service
+    public identity: Config.Identity;
+
+    public env: TEnvConfig;
+
+    public routerPortOverride?: number;
+
+    public packageJson: {[key: string]: any};
+
+    public buildId: number = Date.now();
+
+    public paths = {
+
+        root: cli.paths.appRoot,
+        bin: path.join( cli.paths.appRoot, 'bin'),
+        dev: path.join( cli.paths.appRoot, 'dev'),
+        data: path.join( cli.paths.appRoot, 'var', 'data'),
+        public: path.join( cli.paths.appRoot, 'public'),
+        pages: path.join( cli.paths.appRoot, 'client', 'pages'),
+        cache: path.join( cli.paths.appRoot, '.cache'),
+
+        client: {
+            generated: path.join( cli.paths.appRoot, 'client', '.generated')
+        },
+        server: {
+            generated: path.join( cli.paths.appRoot, 'server', '.generated'),
+            configs: path.join( cli.paths.appRoot, 'server', 'app')
+        },
+        common: {
+            generated: path.join( cli.paths.appRoot, 'common', '.generated')
+        },
+        
+        withAlias: (filename: string, side: TAppSide) => 
+            this.aliases[side].apply(filename),
+
+        withoutAlias: (filename: string, side: TAppSide) => 
+            this.aliases[side].realpath(filename),
+    }
+
+    public containerServices = [
+        //'Services',
+        'Environment',
+        'Identity',
+        /*'Application',
+        'Path',
+        'Event'*/
+    ]
+
+    public constructor() {
+        
+        cli.debug && console.log(`[cli] Loading app config ...`);
+        this.routerPortOverride = parseRouterPortOverride( cli.args.port );
+
+        const configParser = new ConfigParser(
+            cli.paths.appRoot,
+            undefined,
+            this.routerPortOverride
+        );
+        this.identity = configParser.identity();
+        this.env = configParser.env();
+        this.packageJson = this.loadPkg();
+        
+    }
+
+    public outputPath(target: 'dev' | 'bin') {
+        return target === 'dev'
+            ? this.paths.dev
+            : this.paths.bin;
+    }
+
+    /*----------------------------------
+    - ALIAS
+    ----------------------------------*/
+
+    public aliases = {
+        client: new TsAlias({
+            rootDir: this.paths.root + '/client',
+            modulesDir: [ 
+                cli.paths.appRoot + '/node_modules',  
+                cli.paths.coreRoot + '/node_modules'
+            ],
+            debug: false
+        }),
+        server: new TsAlias({
+            rootDir: this.paths.root + '/server',
+            modulesDir: [ 
+                cli.paths.appRoot + '/node_modules',  
+                cli.paths.coreRoot + '/node_modules'
+            ],
+            debug: false
+        }),
+    }
+
+    private loadPkg() {
+        return fs.readJSONSync(this.paths.root + '/package.json');
+    }
+
+    /*----------------------------------
+    - WARMUP (Services awareness)
+    ----------------------------------*/
+
+    public registered = {}
+
+    public use( referenceName: string ): TServiceRef {
+
+        // We don't check because all service are not regstered when we register subservices
+        /*if (this.registered[referenceName] === undefined) {
+            throw new Error(`Service ${referenceName} is not registered`);
+        }*/
+
+        return {
+            refTo: referenceName,
+            type: 'service.ref'
+        }
+    }
+
+    public setup(...args: [
+        // { user: app.setup('Core/User') }
+        servicePath: string,
+        serviceConfig?: {},
+    ] | [
+        // app.setup('User', 'Core/User')
+        serviceName: string, 
+        servicePath: string,
+        serviceConfig?: {},
+    ]): TServiceSetup {
+
+        // Registration to app root
+        if (typeof args[1] === 'string') {
+            
+            const [name, id, config] = args;
+
+            const service = { id, name, config, type: 'service.setup' } as TServiceSetup
+
+            this.registered[name] = service;
+
+            return service;
+
+        // Scoped to a parent service
+        } else {
+
+            const [id, config] = args;
+
+            const service = { id, config, type: 'service.setup' } as TServiceSetup
+
+            return service;
+        }
+    }
+
+    public async warmup() {
+
+        // Require all config files in @/server/config
+        const configDir = path.resolve(cli.paths.appRoot, 'server', 'config');
+        const configFiles = fs.readdirSync(configDir);
+        for (const configFile of configFiles) {
+            console.log("Loading config file:", configFile);
+            require( path.resolve(configDir, configFile) );
+        }
+    }
+}
+
+export const app = new App
+
+export default app

package/cli/bin.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+const path = require('path');
+
+/*
+    Why this exists (npm i vs npm link difference)
+
+    Proteum's CLI is written in TypeScript and is executed via ts-node at runtime.
+    When Proteum is installed from npm, `cli/tsconfig.json` lives inside `node_modules/proteum/cli`.
+
+    ts-node's default ignore pattern (`/(?:^|\\/)node_modules\\//`) is applied to *paths relative to the tsconfig folder*.
+    For hoisted deps (ex: `node_modules/tailwindcss/...`), the relative path becomes `../../tailwindcss/...` (no `node_modules/` segment),
+    so ts-node mistakenly transpiles those sibling dependencies.
+
+    Tailwind v4 contains `class ... extends Map` and downleveling that to ES5 turns `super()` into `Map.call(this)`,
+    which throws: "TypeError: Constructor Map requires 'new'".
+
+    Fix: extend ts-node ignore patterns so it also ignores `../../<pkg>/...` (hoisted siblings), while still allowing the CLI
+    to `require()` the user's app config (ex: `../../../server/config/*.ts`).
+*/
+if (!process.env.TS_NODE_IGNORE) {
+    process.env.TS_NODE_IGNORE = [
+        // Default ts-node ignore rule (works when deps are nested under `../node_modules/...`)
+        '(node_modules\/(?!proteum\/))|(\.generated\/)|(\.cache\/)',
+        // Extra rule for deps hoisted next to Proteum (ex: `../../tailwindcss/...`)
+        '^\\.\\./\\.\\./(?!\\./|\\.\\./)[^/]+/'
+    ].join(',');
+}
+
+process.env.TS_NODE_PROJECT = path.join(__dirname, 'tsconfig.json');
+process.env.TS_NODE_TRANSPILE_ONLY = '1';
+
+require('ts-node/register/transpile-only');
+
+require('./index.ts');

package/cli/commands/build.ts

@@ -0,0 +1,60 @@
+/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+// Core
+import cli from '..';
+
+// Configs
+import Compiler from '../compiler';
+import type { TCompileMode } from '../compiler/common';
+
+const allowedBuildArgs = new Set(['dev', 'prod', 'analyze', 'cache']);
+
+/*----------------------------------
+- COMMAND
+----------------------------------*/
+function resolveBuildMode(): TCompileMode {
+
+    const enabledArgs = Object.entries(cli.args)
+        .filter(([name, value]) => name !== 'workdir' && value === true)
+        .map(([name]) => name);
+
+    const invalidArgs = enabledArgs.filter(arg => !allowedBuildArgs.has(arg));
+    if (invalidArgs.length > 0)
+        throw new Error(`Unknown build argument(s): ${invalidArgs.join(', ')}. Allowed values: dev, prod, analyze, cache.`);
+
+    const requestedModes = enabledArgs.filter((arg): arg is TCompileMode =>
+        arg === 'dev' || arg === 'prod'
+    );
+    if (requestedModes.length > 1)
+        throw new Error(`Please specify only one build mode. Received: ${requestedModes.join(', ')}.`);
+
+    return requestedModes[0] ?? 'dev';
+}
+
+export const run = async (): Promise<void> => {
+
+    const mode = resolveBuildMode();
+    const compiler = new Compiler(mode, {}, false, 'bin');
+    const multiCompiler = await compiler.create();
+
+    await new Promise<void>((resolve, reject) => {
+        multiCompiler.run((error, stats) => {
+
+            if (error) {
+                console.error("An error occurred during the compilation:", error);
+                reject(error);
+                return;
+            }
+
+            if (stats?.hasErrors()) {
+                reject(new Error(`Compilation failed for build mode "${mode}".`));
+                return;
+            }
+
+            resolve();
+        });
+
+    });
+};

package/cli/commands/deploy/app.ts

@@ -0,0 +1,29 @@
+/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+// Npm
+import fs from 'fs-extra';
+
+// Core
+import cli from '../..';
+import { api } from '../../utils';
+
+/*----------------------------------
+- COMMAND
+----------------------------------*/
+export async function run() {
+
+    const { project, local } = cli.args;
+
+    const versionfile = fs.readFileSync( project + '/version.txt', 'utf-8' );
+
+    const [platform, version, build] = versionfile.split('\n');
+
+    console.log({ project, platform, version, build });
+    
+    await cli.shell(
+        api('POST', '/app/release', { platform, version, build }, local)
+    );
+    
+}

package/cli/commands/deploy/web.ts

@@ -0,0 +1,60 @@
+/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+// Npm
+import fs from 'fs-extra';
+import prompts from 'prompts';
+
+// Core
+import cli from '../..';
+import { api } from '../../utils';
+
+0/*----------------------------------
+- HELPERS
+----------------------------------*/
+
+const mergeDeps = ({ dependencies: coreDeps }, { dependencies: appDeps }) => {
+    for (const dep in appDeps)
+        if (dep in coreDeps) {
+
+            if (coreDeps[dep] !== appDeps[dep])
+                throw new Error(`Duplicate dependency "${dep}" with different version in core (${coreDeps[dep]}) and app (${appDeps[dep]})`);
+            else
+                console.warn(`Duplicate dependency "${dep}" in core and app`);
+
+        } else
+            coreDeps[dep] = appDeps[dep];
+    return coreDeps;
+}
+
+const toast = (type: string, title: string, content: string) =>
+    api('POST', '/admin/api/notification', { type, title, content }, true)
+
+/*----------------------------------
+- COMMAND
+----------------------------------*/
+export async function run() {
+
+    const { simulate } = cli.args;
+
+    const temp = app.paths.root + '/.deployment';
+    fs.emptyDirSync(temp);
+
+    // Merge package.json: framework + app
+    fs.outputJSONSync(temp + '/package.json', {
+        ...appPkg,
+        dependencies: mergeDeps(cli.packageJson, appPkg),
+        devDependencies: {}
+    }, { spaces: 4 });
+
+    // Copy config file
+    fs.copyFileSync( app.paths.root + (simulate ? '/env.yaml' : '/env.server.yaml'), temp + '/env.yaml' );
+
+    // Compile & Run Docker
+    await cli.shell(`docker compose up --build`);
+    toast("info", "Server update", "A server update will start. You might experience some temporary slowdowns.")
+
+    fs.removeSync(temp);
+
+}

package/cli/commands/dev.ts

@@ -0,0 +1,124 @@
+/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+// Npm
+import path from 'path';
+import { spawn, ChildProcess } from 'child_process';
+
+// Cor elibs
+import cli from '..';
+import Keyboard from '../utils/keyboard';
+
+// Configs
+import Compiler from '../compiler';
+
+// Core
+import { app, App } from '../app';
+
+const ignoredWatchPathPatterns = /(node_modules\/(?!proteum\/))|(\.generated\/)|(\.cache\/)/;
+
+/*----------------------------------
+- COMMANDE
+----------------------------------*/
+export const run = () => new Promise<void>(async () => {
+
+    const compiler = new Compiler('dev', {
+        before: (compiler) => {
+
+            const changedFilesList = compiler.modifiedFiles ? [...compiler.modifiedFiles] : [];
+
+            if (changedFilesList.length === 0)
+                stopApp("Starting a new compilation");
+            else
+                stopApp("Need to recompile 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({
+
+        // 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 + '/')
+                );
+        }
+
+        //aggregateTimeout: 1000,
+    }, async (error, stats) => {
+
+        if (error) {
+            console.error(`Error in milticompiler.watch`, error, stats?.toString());
+            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 ...`);
+        startApp(app);
+
+    });
+
+    Keyboard.input('ctrl+c', () => {
+        stopApp("CTRL+C Pressed");
+    });
+});
+
+
+/*----------------------------------
+- APP RUN
+----------------------------------*/
+let cp: ChildProcess | undefined = undefined;
+
+async function startApp( app: App ) {
+
+    stopApp('Restart asked');
+
+    console.info(`Launching new server ...`);
+    cp = spawn('node', ['' + app.outputPath('dev') + '/server.js', '--preserve-symlinks'], {
+
+        // sdin, sdout, sderr
+        stdio: ['inherit', 'inherit', 'inherit']
+
+    });
+}
+
+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/init.ts

@@ -0,0 +1,85 @@
+/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+// Npm
+import fs from 'fs-extra';
+import path from 'path';
+import prompts from 'prompts';
+import cmd from 'node-cmd';
+import replaceOnce from 'replace-once';
+
+// Cor elibs
+import cli from '..';
+
+// Configs
+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 ?'
+    }]);
+
+    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)
+    }
+
+    // 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);
+
+        const filepath = path.join( paths.project, file )
+        const content = fs.readFileSync(filepath, 'utf-8');
+
+        const placeholders_keys = Object.keys(placeholders).map(k => '{{ ' + k + ' }}')
+        const values = Object.values(placeholders);
+
+        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');*/
+
+});