proteum 2.0.0 → 2.1.0

package/cli/compiler/server/index.ts

@@ -32,6 +32,18 @@ import type { App } from '../../app';
 
 const debug = false;
 const ssrScriptExtensions = ['.ssr.ts', '.ssr.tsx'];
+const serverReactCompatCompilePrefixes = [
+    '@floating-ui',
+    '@mantine/',
+    '@radix-ui/',
+    'aria-hidden',
+    'react-number-format',
+    'react-remove-scroll',
+    'react-remove-scroll-bar',
+    'react-style-singleton',
+    'use-callback-ref',
+    'use-sidecar',
+];
 
 const getDevGeneratedRuntimeEntries = (app: App) => ({
     __proteum_dev_routes: [app.paths.server.generated + '/routes.ts'],
@@ -108,10 +120,9 @@ export default function createCompiler(
                         // TODO: proteum.conf: compile: include
                         // Compile proteum modules
                         request.startsWith('proteum') ||
-                        // Compile 5HTP modules
-                        request.startsWith('@mantine/') ||
-                        request.startsWith('react-number-format') ||
-                        request.startsWith('@floating-ui'));
+                        // React-based UI packages must pass through the alias layer on the server,
+                        // otherwise SSR can mix real React packages with the Preact compat runtime.
+                        serverReactCompatCompilePrefixes.some((prefix) => request.startsWith(prefix)));
 
                 //console.log('isNodeModule', request, isNodeModule);
 
@@ -144,13 +155,19 @@ export default function createCompiler(
                     include: [
                         app.paths.root + '/client',
                         cli.paths.core.root + '/client',
+                        app.paths.client.generated,
 
                         app.paths.root + '/common',
                         cli.paths.core.root + '/common',
+                        app.paths.common.generated,
+
+                        // Prisma 7 generates TypeScript entrypoints under var/prisma.
+                        app.paths.root + '/var/prisma',
 
                         // Dossiers server uniquement pour le bundle server
                         app.paths.root + '/server',
                         cli.paths.core.root + '/server',
+                        app.paths.server.generated,
 
                         // Complle 5HTP modules so they can refer to the framework instance and aliases
                         // Temp disabled because compile issue on vercel

package/cli/context.ts

@@ -0,0 +1,71 @@
+import cp from 'child_process';
+import fs from 'fs-extra';
+
+import Paths from './paths';
+
+export type TArgsObject = { [key: string]: string | boolean | string[] | undefined };
+
+export class CLIContext {
+    public args: TArgsObject = { workdir: process.cwd() };
+
+    public verbose = false;
+
+    public debug = false;
+
+    public packageJson: { [key: string]: any };
+
+    public constructor(public paths = new Paths(process.cwd())) {
+        this.debug && console.log(`[cli] 5HTP CLI`, process.env.npm_package_version);
+
+        this.debug && console.log(`[cli] Apply aliases ...`);
+        this.paths.applyAliases();
+
+        this.packageJson = this.loadPkg();
+    }
+
+    public setArgs(args: TArgsObject = {}) {
+        this.args = { workdir: process.cwd(), ...args };
+        this.verbose = this.args.verbose === true;
+        this.debug = this.verbose;
+    }
+
+    private loadPkg() {
+        return fs.readJSONSync(this.paths.core.root + '/package.json');
+    }
+
+    public shell(...commands: string[]) {
+        return new Promise<void>((resolve) => {
+            const fullCommand = commands
+                .map((command) => {
+                    command = command.trim();
+
+                    if (command.endsWith(';')) command = command.substring(0, command.length - 1);
+
+                    return command;
+                })
+                .join(';');
+
+            this.verbose && console.log('$ ' + fullCommand);
+
+            const wrappedCommand = `bash -c '${fullCommand}'`;
+            this.verbose && console.log('Running command: ' + wrappedCommand);
+
+            const proc = cp.spawn(wrappedCommand, [], {
+                cwd: process.cwd(),
+                detached: false,
+                shell: true,
+            });
+
+            this.verbose && console.log(proc.exitCode);
+
+            proc.on('exit', () => {
+                this.verbose && console.log('Command finished.');
+                resolve();
+            });
+        });
+    }
+}
+
+const cli = new CLIContext();
+
+export default cli;

package/cli/index.ts

@@ -1,188 +1,46 @@
-#!/usr/bin/env -S npx ts-node
-
 process.traceDeprecation = true;
 
-/*----------------------------------
-- DEPENDANCES
-----------------------------------*/
-
-// Npm
-import fs from 'fs-extra';
-import cp from 'child_process';
-
-// Libs
-import Paths from './paths';
-
-/*----------------------------------
-- TYPES
-----------------------------------*/
-
-type TCliCommand = () => Promise<{ run: () => Promise<void> }>;
-
-type TArgsObject = { [key: string]: string | boolean | string[] };
-
-/*----------------------------------
-- CLASSE
-----------------------------------*/
-/*
-    IMPORTANT: The CLI must be independant of the app instance and libs
-*/
-export class CLI {
-    // Context
-    public args: TArgsObject = {};
-
-    public commandOptionDefaults: { [command: string]: TArgsObject } = {
-        dev: { port: '', cache: true },
-        build: { port: '', dev: false, prod: false, cache: false, analyze: false },
-        lint: { fix: false },
-    };
-
-    public debug: boolean = false;
-
-    public packageJson: { [key: string]: any };
-
-    public constructor(public paths = new Paths(process.cwd())) {
-        this.debug && console.log(`[cli] 5HTP CLI`, process.env.npm_package_version);
-
-        this.debug && console.log(`[cli] Apply aliases ...`);
-        this.paths.applyAliases();
-
-        this.packageJson = this.loadPkg();
-
-        this.start();
-    }
-
-    /*----------------------------------
-    - COMMANDS
-    ----------------------------------*/
-    // Les importations asynchrones permettent d'accéder à l'instance de cli via un import
-    // WARN: We load commands asynchonously, so the aliases are applied before the file is imported
-    public commands: { [name: string]: TCliCommand } = {
-        init: () => import('./commands/init'),
-        dev: () => import('./commands/dev'),
-        refresh: () => import('./commands/refresh'),
-        build: () => import('./commands/build'),
-        typecheck: () => import('./commands/typecheck'),
-        lint: () => import('./commands/lint'),
-        check: () => import('./commands/check'),
-    };
-
-    private loadPkg() {
-        return fs.readJSONSync(this.paths.core.root + '/package.json');
-    }
-
-    public start() {
-        const [, , commandName, ...argv] = process.argv;
-
-        if (this.commands[commandName] === undefined) throw new Error(`Command ${commandName} does not exists.`);
-
-        this.args = { ...(this.commandOptionDefaults[commandName] || {}) };
-        this.args.workdir = process.cwd();
-
-        let opt: string | null = null;
-        for (const a of argv) {
-            if (a.startsWith('-')) {
-                opt = a.replace(/^-+/, '');
-                if (opt.length === 0) throw new Error(`Unknown option: ${a}`);
-
-                if (opt.startsWith('no-')) {
-                    const booleanOpt = opt.substring(3);
-                    if (!(booleanOpt in this.args)) throw new Error(`Unknown option: ${opt}`);
-                    if (typeof this.args[booleanOpt] !== 'boolean')
-                        throw new Error(`Option ${booleanOpt} does not support --no-${booleanOpt}.`);
-
-                    this.args[booleanOpt] = false;
-                    opt = null;
-                    continue;
-                }
-
-                if (!(opt in this.args)) throw new Error(`Unknown option: ${opt}`);
-
-                // Init with default value
-                if (typeof this.args[opt] === 'boolean') {
-                    this.args[opt] = true;
-                    opt = null;
-                }
-            } else if (opt !== null) {
-                const curVal = this.args[opt];
-
-                if (Array.isArray(curVal)) curVal.push(a);
-                else this.args[opt] = a;
-
-                opt = null;
-            } else {
-                this.args[a] = true;
-            }
-        }
-
-        if (opt !== null && typeof this.args[opt] !== 'boolean') throw new Error(`Missing value for option: ${opt}`);
-
-        this.runCommand(commandName);
+import fs from 'fs';
+import { Cli } from 'clipanion';
+
+import cli from './context';
+import { proteumCommandNames } from './presentation/commands';
+import { renderCliOverview, renderCommandHelp, resolveCustomHelpRequest } from './presentation/help';
+import { normalizeHelpArgv, normalizeLegacyArgv } from './runtime/argv';
+import { createCli, registeredCommands } from './runtime/commands';
+
+const hasInitScaffold = () => fs.existsSync(`${cli.paths.core.cli}/skeleton`);
+
+export const runCli = async (argv: string[] = process.argv.slice(2)) => {
+    const normalizedArgv = normalizeHelpArgv(normalizeLegacyArgv(argv), proteumCommandNames);
+    const clipanion = createCli(String(cli.packageJson.version || ''));
+    const initAvailable = hasInitScaffold();
+    const helpRequest = resolveCustomHelpRequest(normalizedArgv);
+
+    if (helpRequest.kind === 'overview') {
+        process.stdout.write(
+            await renderCliOverview({
+                version: String(cli.packageJson.version || ''),
+                workdir: process.cwd(),
+                initAvailable,
+            }),
+        );
+        return;
     }
 
-    public async runCommand(command: string) {
-        this.debug && console.info(`Running command ${command}`, this.args);
-
-        // Check existance
-        if (this.commands[command] === undefined) throw new Error(`Command ${command} does not exists.`);
-
-        const runner = await this.commands[command]();
-        let exitCode = 0;
-
-        // Running
-        runner
-            .run()
-            .then(() => {
-                this.debug && console.info(`Command ${command} finished.`);
-            })
-            .catch((e) => {
-                exitCode = 1;
-                console.error(`Error during execution of ${command}:`, e);
-            })
-            .finally(() => {
-                process.exit(exitCode);
-            });
+    if (helpRequest.kind === 'command') {
+        process.stdout.write(
+            await renderCommandHelp({
+                commandName: helpRequest.commandName,
+                definition: clipanion.definition(registeredCommands[helpRequest.commandName]),
+                workdir: process.cwd(),
+                initAvailable,
+            }),
+        );
+        return;
     }
 
-    public shell(...commands: string[]) {
-        return new Promise<void>(async (resolve) => {
-            const fullCommand = commands
-                .map((command) => {
-                    command = command.trim();
-
-                    if (command.endsWith(';')) command = command.substring(0, command.length - 1);
-
-                    return command;
-                })
-                .join(';');
-
-            console.log('$ ' + fullCommand);
-
-            /*const tempFile = this.paths.app.root + '/.exec.sh';
-            fs.outputFileSync(tempFile, '#! /bin/bash\n' + fullCommand);
-            const wrappedCommand =  `tilix --new-process -e bash -c 'chmod +x "${tempFile}"; "${tempFile}"; echo "Entrée pour continuer"; read a;'`;*/
-            const wrappedCommand = `bash -c '${fullCommand}'`;
-            console.log('Running command: ' + wrappedCommand);
-            //await this.waitForInput('enter');
-
-            const proc = cp.spawn(wrappedCommand, [], {
-                cwd: process.cwd(),
-                detached: false,
-                // Permer de lancer les commandes via des chaines pures (autrement, il faut separer chaque arg dans un tableau)
-                // https://stackoverflow.com/questions/23487363/how-can-i-parse-a-string-into-appropriate-arguments-for-child-process-spawn
-                shell: true,
-            });
-
-            console.log(proc.exitCode);
-
-            proc.on('exit', function () {
-                //fs.removeSync(tempFile);
-
-                console.log('Command finished.');
-                resolve();
-            });
-        });
-    }
-}
+    await clipanion.runExit(normalizedArgv, Cli.defaultContext);
+};
 
-export default new CLI();
+export default cli;

package/cli/presentation/commands.ts

@@ -0,0 +1,208 @@
+import fs from 'fs';
+import path from 'path';
+
+import type { TRow } from './layout';
+
+export const proteumCommandNames = [
+    'init',
+    'dev',
+    'refresh',
+    'build',
+    'typecheck',
+    'lint',
+    'check',
+    'doctor',
+    'explain',
+] as const;
+
+export type TProteumCommandName = (typeof proteumCommandNames)[number];
+
+type TProteumCommandExample = {
+    description: string;
+    command: string;
+};
+
+type TProteumCommandStatus = 'stable' | 'experimental';
+
+export type TProteumCommandDoc = {
+    name: TProteumCommandName;
+    category: string;
+    summary: string;
+    usage: string;
+    bestFor: string;
+    examples: TProteumCommandExample[];
+    notes?: string[];
+    status?: TProteumCommandStatus;
+};
+
+export const proteumRecommendedFlow: TRow[] = [
+    { label: '1. proteum dev', value: 'Start the compiler, SSR server, and hot reload loop.' },
+    { label: '2. proteum refresh', value: 'Regenerate .proteum contracts and typings after source or framework changes.' },
+    { label: '3. proteum check', value: 'Refresh, typecheck, and lint before you commit or push.' },
+    { label: '4. proteum build --prod', value: 'Produce the production server and client bundles.' },
+];
+
+export const proteumCommandGroups: Array<{ title: string; names: TProteumCommandName[] }> = [
+    { title: 'Daily workflow', names: ['dev', 'refresh', 'build'] },
+    { title: 'Quality gates', names: ['typecheck', 'lint', 'check'] },
+    { title: 'Manifest and contracts', names: ['doctor', 'explain'] },
+    { title: 'Project scaffolding', names: ['init'] },
+];
+
+export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> = {
+    init: {
+        name: 'init',
+        category: 'Project scaffolding',
+        summary: 'Scaffold a new Proteum project.',
+        usage: 'proteum init',
+        bestFor: 'Bootstrap a new app when the Proteum scaffold assets are installed in the current package.',
+        examples: [{ description: 'Create a new app interactively', command: 'proteum init' }],
+        notes: [
+            'This command is still experimental.',
+            'In source checkouts it requires `cli/skeleton` to exist.',
+        ],
+        status: 'experimental',
+    },
+    dev: {
+        name: 'dev',
+        category: 'Daily workflow',
+        summary: 'Start the local compiler, SSR server, and hot reload loop.',
+        usage: 'proteum dev [--port <port>] [--cache|--no-cache]',
+        bestFor:
+            'Day-to-day app work. This is the main entrypoint used by the current reference apps during local development.',
+        examples: [
+            { description: 'Start the app on its configured router port', command: 'proteum dev' },
+            { description: 'Run a second Proteum app on another port', command: 'proteum dev --port 3101' },
+            {
+                description: 'Disable the filesystem cache while debugging compiler state',
+                command: 'proteum dev --no-cache',
+            },
+        ],
+        notes: ['Legacy single-dash long options remain supported, for example `proteum dev -port 3001`.'],
+        status: 'stable',
+    },
+    refresh: {
+        name: 'refresh',
+        category: 'Daily workflow',
+        summary: 'Refresh generated Proteum typings and artifacts.',
+        usage: 'proteum refresh',
+        bestFor:
+            'Force regeneration of the framework-owned `.proteum` output when routes, controllers, services, or framework generation rules changed.',
+        examples: [
+            { description: 'Refresh generated contracts after source edits', command: 'proteum refresh' },
+        ],
+        notes: ['Use this when you need deterministic regeneration without starting the full dev loop.'],
+        status: 'stable',
+    },
+    build: {
+        name: 'build',
+        category: 'Daily workflow',
+        summary: 'Build the application.',
+        usage: 'proteum build [--prod] [--strict] [--cache] [--analyze] [--port <port>]',
+        bestFor: 'CI, release builds, and local verification of the production server and client output.',
+        examples: [
+            { description: 'Run the normal production build', command: 'proteum build --prod' },
+            {
+                description: 'Refresh typings, typecheck, then build in strict mode',
+                command: 'proteum build --prod --strict',
+            },
+            { description: 'Generate bundle analysis artifacts', command: 'proteum build --prod --analyze' },
+            { description: 'Reuse the filesystem cache during builds', command: 'proteum build --prod --cache' },
+        ],
+        notes: [
+            'Legacy positional booleans remain supported, for example `proteum build prod strict analyze`.',
+            'Use `--strict` when the build must refresh generated typings and fail on any TypeScript error before compilation starts.',
+            'The production output is emitted under `bin/`.',
+        ],
+        status: 'stable',
+    },
+    typecheck: {
+        name: 'typecheck',
+        category: 'Quality gates',
+        summary: 'Run TypeScript typechecking for the application.',
+        usage: 'proteum typecheck',
+        bestFor: 'Fast verification that generated contracts and app code still satisfy the TypeScript surface.',
+        examples: [
+            { description: 'Typecheck every discovered client and server app tsconfig', command: 'proteum typecheck' },
+        ],
+        notes: ['Proteum refreshes generated typings before running TypeScript.'],
+        status: 'stable',
+    },
+    lint: {
+        name: 'lint',
+        category: 'Quality gates',
+        summary: 'Run ESLint for the application.',
+        usage: 'proteum lint [--fix]',
+        bestFor: 'Static code-quality validation across the current app root.',
+        examples: [
+            { description: 'Run ESLint in check mode', command: 'proteum lint' },
+            { description: 'Apply fixable lint changes', command: 'proteum lint --fix' },
+        ],
+        notes: ['Legacy positional usage such as `proteum lint fix` remains supported.'],
+        status: 'stable',
+    },
+    check: {
+        name: 'check',
+        category: 'Quality gates',
+        summary: 'Refresh typings, typecheck, then lint the application.',
+        usage: 'proteum check',
+        bestFor: 'One command before commits, pushes, or CI when you want the standard local validation path.',
+        examples: [{ description: 'Run the full default validation pipeline', command: 'proteum check' }],
+        notes: ['This command executes refresh, typecheck, then lint in that order.'],
+        status: 'stable',
+    },
+    doctor: {
+        name: 'doctor',
+        category: 'Manifest and contracts',
+        summary: 'Inspect the generated Proteum manifest diagnostics.',
+        usage: 'proteum doctor [--json] [--strict]',
+        bestFor:
+            'Auditing manifest warnings and errors, especially in CI or when route/controller generation behaves unexpectedly.',
+        examples: [
+            { description: 'Print a human-readable diagnostic summary', command: 'proteum doctor' },
+            { description: 'Fail if any diagnostics exist', command: 'proteum doctor --strict' },
+            { description: 'Emit machine-readable diagnostics', command: 'proteum doctor --json' },
+        ],
+        notes: ['`--strict` is intended for CI and pre-release verification.'],
+        status: 'stable',
+    },
+    explain: {
+        name: 'explain',
+        category: 'Manifest and contracts',
+        summary: 'Explain the generated Proteum manifest.',
+        usage: 'proteum explain [--all|--app|--conventions|--env|--services|--controllers|--routes|--layouts|--diagnostics] [--json]',
+        bestFor:
+            'Inspecting how source files became generated routes, controllers, layouts, services, and diagnostics without reading compiler internals.',
+        examples: [
+            { description: 'Show the default human summary', command: 'proteum explain' },
+            {
+                description: 'Inspect generated routes and controllers together',
+                command: 'proteum explain --routes --controllers',
+            },
+            { description: 'Emit the selected manifest sections as JSON', command: 'proteum explain --routes --json' },
+        ],
+        notes: ['Legacy positional section selection remains supported, for example `proteum explain routes services`.'],
+        status: 'stable',
+    },
+};
+
+export const isLikelyProteumAppRoot = (workdir: string) =>
+    fs.existsSync(path.join(workdir, 'package.json')) &&
+    fs.existsSync(path.join(workdir, 'identity.yaml')) &&
+    fs.existsSync(path.join(workdir, 'client')) &&
+    fs.existsSync(path.join(workdir, 'server'));
+
+export const getInitAvailabilityNote = (initAvailable: boolean) =>
+    initAvailable
+        ? 'Scaffold assets are installed in this checkout.'
+        : 'This checkout does not include `cli/skeleton`, so `proteum init` is unavailable until the scaffold assets are restored.';
+
+export const createClipanionUsage = (command: TProteumCommandDoc) => ({
+    category: command.category,
+    description: command.summary,
+    details: [
+        `Best for: ${command.bestFor}`,
+        ...(command.notes && command.notes.length > 0 ? [`Notes:\n${command.notes.map((note) => `- ${note}`).join('\n')}`] : []),
+    ].join('\n\n'),
+    examples: command.examples.map((example) => [example.description, example.command] as [string, string]),
+});

package/cli/presentation/compileReporter.ts

@@ -0,0 +1,65 @@
+const ansi = {
+    reset: '\u001b[0m',
+    bold: '\u001b[1m',
+    dim: '\u001b[2m',
+    red: '\u001b[31m',
+    green: '\u001b[32m',
+    cyan: '\u001b[36m',
+} as const;
+
+export type TCompileReporter = {
+    start: (compilerName: string, changedFiles: string[]) => void;
+    finish: (compilerName: string, options: { succeeded: boolean; durationMs: number }) => void;
+    stop: () => void;
+};
+
+const createNoopCompileReporter = (): TCompileReporter => ({
+    start() {},
+    finish() {},
+    stop() {},
+});
+
+const supportsColor = () => process.stdout.isTTY === true;
+
+const colorize = (value: string, ...codes: string[]) => (supportsColor() ? `${codes.join('')}${value}${ansi.reset}` : value);
+
+const formatDuration = (durationMs: number) => {
+    if (durationMs < 1000) return `${durationMs} ms`;
+    if (durationMs < 10_000) return `${(durationMs / 1000).toFixed(1)} s`;
+    return `${Math.round(durationMs / 1000)} s`;
+};
+
+const formatChangedFiles = (changedFilesCount: number) => {
+    if (changedFilesCount === 0) return 'initial build';
+    return `${changedFilesCount} changed file${changedFilesCount === 1 ? '' : 's'}`;
+};
+
+class ConsoleCompileReporter implements TCompileReporter {
+    public start(compilerName: string, changedFiles: string[]) {
+        console.info(
+            [
+                colorize('compiler:start', ansi.bold, ansi.cyan),
+                colorize(compilerName, ansi.bold),
+                colorize(formatChangedFiles(changedFiles.length), ansi.dim),
+            ].join('  '),
+        );
+    }
+
+    public finish(compilerName: string, { succeeded, durationMs }: { succeeded: boolean; durationMs: number }) {
+        console.info(
+            [
+                colorize(succeeded ? 'compiler:done' : 'compiler:fail', ansi.bold, succeeded ? ansi.green : ansi.red),
+                colorize(compilerName, ansi.bold),
+                colorize(formatDuration(durationMs), ansi.dim),
+            ].join('  '),
+        );
+    }
+
+    public stop() {}
+}
+
+export const createCompileReporter = ({ enabled }: { enabled: boolean }): TCompileReporter => {
+    if (!enabled) return createNoopCompileReporter();
+
+    return new ConsoleCompileReporter();
+};