proteum 2.0.0 → 2.1.0

package/cli/runtime/commands.ts

@@ -0,0 +1,221 @@
+import { Builtins, Cli, Option } from 'clipanion';
+
+import type { TArgsObject } from '../context';
+import { applyLegacyBooleanArgs, assertNoLegacyArgs } from './argv';
+import { buildUsage, ProteumCommand, runCommandModule } from './command';
+
+class InitCommand extends ProteumCommand {
+    public static paths = [['init']];
+
+    public static usage = buildUsage('init');
+
+    public legacyArgs = Option.Rest();
+
+    public async execute() {
+        assertNoLegacyArgs('init', this.legacyArgs);
+        this.setCliArgs();
+        await runCommandModule(() => import('../commands/init'));
+    }
+}
+
+class DevCommand extends ProteumCommand {
+    public static paths = [['dev']];
+
+    public static usage = buildUsage('dev');
+
+    public port = Option.String('--port', { description: 'Override the router port.' });
+    public cache = Option.Boolean('--cache', true, { description: 'Enable filesystem caching.' });
+    public legacyArgs = Option.Rest();
+
+    public async execute() {
+        assertNoLegacyArgs('dev', this.legacyArgs);
+        this.setCliArgs({ port: this.port ?? '', cache: this.cache });
+        await runCommandModule(() => import('../commands/dev'));
+    }
+}
+
+class RefreshCommand extends ProteumCommand {
+    public static paths = [['refresh']];
+
+    public static usage = buildUsage('refresh');
+
+    public legacyArgs = Option.Rest();
+
+    public async execute() {
+        assertNoLegacyArgs('refresh', this.legacyArgs);
+        this.setCliArgs();
+        await runCommandModule(() => import('../commands/refresh'));
+    }
+}
+
+class BuildCommand extends ProteumCommand {
+    public static paths = [['build']];
+
+    public static usage = buildUsage('build');
+
+    public port = Option.String('--port', { description: 'Override the router port.' });
+    public prod = Option.Boolean('--prod', false, { description: 'Build in production mode.' });
+    public cache = Option.Boolean('--cache', false, { description: 'Enable filesystem caching during the build.' });
+    public analyze = Option.Boolean('--analyze', false, { description: 'Emit the client bundle analysis report.' });
+    public strict = Option.Boolean('--strict', false, {
+        description: 'Refresh generated typings and fail the build if TypeScript reports any error.',
+    });
+    public legacyArgs = Option.Rest();
+
+    public async execute() {
+        const args = {
+            port: this.port ?? '',
+            dev: false,
+            prod: this.prod,
+            cache: this.cache,
+            analyze: this.analyze,
+            strict: this.strict,
+        } satisfies TArgsObject;
+
+        applyLegacyBooleanArgs('build', this.legacyArgs, ['prod', 'cache', 'analyze', 'strict'], args);
+        this.setCliArgs(args);
+        await runCommandModule(() => import('../commands/build'));
+    }
+}
+
+class TypecheckCommand extends ProteumCommand {
+    public static paths = [['typecheck']];
+
+    public static usage = buildUsage('typecheck');
+
+    public legacyArgs = Option.Rest();
+
+    public async execute() {
+        assertNoLegacyArgs('typecheck', this.legacyArgs);
+        this.setCliArgs();
+        await runCommandModule(() => import('../commands/typecheck'));
+    }
+}
+
+class LintCommand extends ProteumCommand {
+    public static paths = [['lint']];
+
+    public static usage = buildUsage('lint');
+
+    public fix = Option.Boolean('--fix', false, { description: 'Apply fixable lint changes.' });
+    public legacyArgs = Option.Rest();
+
+    public async execute() {
+        const args = { fix: this.fix } satisfies TArgsObject;
+
+        applyLegacyBooleanArgs('lint', this.legacyArgs, ['fix'], args);
+        this.setCliArgs(args);
+        await runCommandModule(() => import('../commands/lint'));
+    }
+}
+
+class CheckCommand extends ProteumCommand {
+    public static paths = [['check']];
+
+    public static usage = buildUsage('check');
+
+    public legacyArgs = Option.Rest();
+
+    public async execute() {
+        assertNoLegacyArgs('check', this.legacyArgs);
+        this.setCliArgs();
+        await runCommandModule(() => import('../commands/check'));
+    }
+}
+
+class DoctorCommand extends ProteumCommand {
+    public static paths = [['doctor']];
+
+    public static usage = buildUsage('doctor');
+
+    public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    public strict = Option.Boolean('--strict', false, { description: 'Exit with failure if any diagnostics exist.' });
+    public legacyArgs = Option.Rest();
+
+    public async execute() {
+        const args = { json: this.json, strict: this.strict } satisfies TArgsObject;
+
+        applyLegacyBooleanArgs('doctor', this.legacyArgs, ['json', 'strict'], args);
+        this.setCliArgs(args);
+        await runCommandModule(() => import('../commands/doctor'));
+    }
+}
+
+class ExplainCommand extends ProteumCommand {
+    public static paths = [['explain']];
+
+    public static usage = buildUsage('explain');
+
+    public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    public all = Option.Boolean('--all', false, { description: 'Include every explain section.' });
+    public app = Option.Boolean('--app', false, { description: 'Include the app section.' });
+    public conventions = Option.Boolean('--conventions', false, { description: 'Include the conventions section.' });
+    public env = Option.Boolean('--env', false, { description: 'Include the env section.' });
+    public services = Option.Boolean('--services', false, { description: 'Include the services section.' });
+    public controllers = Option.Boolean('--controllers', false, { description: 'Include the controllers section.' });
+    public routes = Option.Boolean('--routes', false, { description: 'Include the routes section.' });
+    public layouts = Option.Boolean('--layouts', false, { description: 'Include the layouts section.' });
+    public diagnostics = Option.Boolean('--diagnostics', false, {
+        description: 'Include the diagnostics section.',
+    });
+    public legacyArgs = Option.Rest();
+
+    public async execute() {
+        const args = {
+            json: this.json,
+            all: this.all,
+            app: this.app,
+            conventions: this.conventions,
+            env: this.env,
+            services: this.services,
+            controllers: this.controllers,
+            routes: this.routes,
+            layouts: this.layouts,
+            diagnostics: this.diagnostics,
+        } satisfies TArgsObject;
+
+        applyLegacyBooleanArgs(
+            'explain',
+            this.legacyArgs,
+            ['json', 'all', 'app', 'conventions', 'env', 'services', 'controllers', 'routes', 'layouts', 'diagnostics'],
+            args,
+        );
+        this.setCliArgs(args);
+        await runCommandModule(() => import('../commands/explain'));
+    }
+}
+
+export const registeredCommands = {
+    init: InitCommand,
+    dev: DevCommand,
+    refresh: RefreshCommand,
+    build: BuildCommand,
+    typecheck: TypecheckCommand,
+    lint: LintCommand,
+    check: CheckCommand,
+    doctor: DoctorCommand,
+    explain: ExplainCommand,
+} as const;
+
+export const createCli = (version: string) => {
+    const clipanion = new Cli({
+        binaryLabel: 'Proteum',
+        binaryName: 'proteum',
+        binaryVersion: version,
+    });
+
+    clipanion.register(Builtins.HelpCommand);
+    clipanion.register(Builtins.VersionCommand);
+    clipanion.register(Builtins.DefinitionsCommand);
+    clipanion.register(InitCommand);
+    clipanion.register(DevCommand);
+    clipanion.register(RefreshCommand);
+    clipanion.register(BuildCommand);
+    clipanion.register(TypecheckCommand);
+    clipanion.register(LintCommand);
+    clipanion.register(CheckCommand);
+    clipanion.register(DoctorCommand);
+    clipanion.register(ExplainCommand);
+
+    return clipanion;
+};

package/cli/runtime/importEsm.ts

@@ -0,0 +1,7 @@
+// The CLI still boots through ts-node in CommonJS mode, but Ink ships as ESM-only.
+// Use Node's native dynamic import so presentation code can depend on Ink safely.
+const nativeDynamicImport = new Function('specifier', 'return import(specifier)') as <T = unknown>(
+    specifier: string,
+) => Promise<T>;
+
+export const importEsm = <T = unknown>(specifier: string) => nativeDynamicImport(specifier) as Promise<T>;

package/cli/runtime/verbose.ts

@@ -0,0 +1,15 @@
+import cli from '../context';
+
+export const isVerbose = () => cli.verbose === true;
+
+export const logVerbose = (...args: unknown[]) => {
+    if (!isVerbose()) return;
+
+    console.info(...args);
+};
+
+export const logVerboseWarn = (...args: unknown[]) => {
+    if (!isVerbose()) return;
+
+    console.warn(...args);
+};

package/cli/utils/agents.ts

@@ -5,6 +5,7 @@
 // Npm
 import fs from 'fs-extra';
 import path from 'path';
+import { logVerbose } from '../runtime/verbose';
 
 /*----------------------------------
 - TYPES
@@ -19,7 +20,7 @@ type TAgentLinkDefinition = { projectPath: string; sourcePath: string; ensurePar
 ----------------------------------*/
 
 // Project-local AGENTS entrypoints mapped to their framework-owned source files.
-const codexAgentLinkDefinitions: TAgentLinkDefinition[] = [
+const projectAgentLinkDefinitions: TAgentLinkDefinition[] = [
     { projectPath: 'AGENTS.md', sourcePath: 'AGENTS.md' },
     { projectPath: 'CODING_STYLE.md', sourcePath: 'CODING_STYLE.md' },
     { projectPath: path.join('client', 'AGENTS.md'), sourcePath: path.join('client', 'AGENTS.md') },
@@ -37,8 +38,8 @@ const codexAgentLinkDefinitions: TAgentLinkDefinition[] = [
 ----------------------------------*/
 
 export function ensureProjectAgentSymlinks({ appRoot, coreRoot }: TEnsureProjectAgentSymlinksArgs) {
-    const agentSourceRoot = path.join(coreRoot, 'agents', 'codex');
-    const agentLinks = codexAgentLinkDefinitions.map((linkDefinition) => ({
+    const agentSourceRoot = path.join(coreRoot, 'agents', 'project');
+    const agentLinks = projectAgentLinkDefinitions.map((linkDefinition) => ({
         ...linkDefinition,
         sourcePath: path.join(agentSourceRoot, linkDefinition.sourcePath),
     }));
@@ -86,7 +87,7 @@ function ensureSymlinks(appRoot: string, linkDefinitions: TAgentLinkDefinition[]
         const symlinkTarget = path.relative(projectParentDir, sourceFilepath);
         fs.symlinkSync(symlinkTarget, projectFilepath);
 
-        console.info(`${logPrefix} Created ${path.relative(appRoot, projectFilepath) || '.'} -> ${symlinkTarget}`);
+        logVerbose(`${logPrefix} Created ${path.relative(appRoot, projectFilepath) || '.'} -> ${symlinkTarget}`);
     }
 }
 

package/cli/utils/keyboard.ts

@@ -4,12 +4,13 @@
 
 // npm
 import readline, { Key } from 'readline';
+import { logVerbose } from '../runtime/verbose';
 
 /*----------------------------------
 - TYPES
 ----------------------------------*/
 
-type TKeyboardCommand = { remove?: boolean; run: (str: string, chunk: string, key: Key) => void };
+type TKeyboardCommand = { remove?: boolean; run: (str: string, chunk: string, key: Key) => void | Promise<void> };
 
 /*----------------------------------
 - METHODS
@@ -34,14 +35,19 @@ class KeyboardCommands {
             if (key.meta) str = 'meta+' + str;
 
             const kCommand = this.commands[str] || this.commands.fallback;
-            if (kCommand) {
-                kCommand.run(str, chunk, key);
 
-                if (kCommand.remove) delete this.commands[str];
+            try {
+                if (kCommand) {
+                    await kCommand.run(str, chunk, key);
+
+                    if (kCommand.remove) delete this.commands[str];
+                }
+            } catch (error) {
+                console.error(error);
             }
 
-            if (str === 'ctrl+c') {
-                console.log(`Exiting ...`);
+            if (str === 'ctrl+c' && !kCommand) {
+                logVerbose(`Exiting ...`);
                 process.exit(0);
             }
         });

package/client/app/index.ts

@@ -56,7 +56,6 @@ export default abstract class Application {
     public constructor() {}
 
     public registerService(service: AnyService) {
-        console.log(`[app] Register service`, service.constructor?.name);
         this.servicesList.push(service);
     }
 
@@ -69,14 +68,9 @@ export default abstract class Application {
     public abstract boot(): void;
 
     public startServices() {
-        console.log(`[app] Starting ${this.servicesList.length} services.`);
-
         for (const service of this.servicesList) {
-            console.log(`[app] Start service`, service);
             service.start();
         }
-
-        console.log(`[app] All ${this.servicesList.length} services were started.`);
     }
 
     public bindErrorHandlers() {

package/client/services/router/index.tsx

@@ -44,7 +44,7 @@ import ClientPage from './response/page';
 type AppPropsContext = Parameters<typeof App>[0]['context'];
 
 // Routes (import __register)
-import appRoutes from '@/client/.generated/routes';
+import appRoutes from '@generated/client/routes';
 
 /*----------------------------------
 - CONFIG

package/client/services/router/response/index.tsx

@@ -15,8 +15,8 @@ import type ClientResponse from '@client/services/router/response';
 import ClientRequest from '@client/services/router/request';
 import ClientPage from '@client/services/router/response/page';
 import { history } from '@client/services/router/request/history';
-import createControllers from '@/common/.generated/controllers';
-import type { TControllers } from '@/common/.generated/controllers';
+import createControllers from '@generated/common/controllers';
+import type { TControllers } from '@generated/common/controllers';
 
 /*----------------------------------
 - TYPES

package/common/dev/serverHotReload.ts

@@ -2,6 +2,7 @@ export const serverHotReloadMessageType = {
     request: 'proteum:router-reload',
     succeeded: 'proteum:router-reload-succeeded',
     failed: 'proteum:router-reload-failed',
+    ready: 'proteum:server-ready',
 } as const;
 
 export type TServerHotReloadRequest = { type: typeof serverHotReloadMessageType.request; changedFiles: string[] };
@@ -12,6 +13,11 @@ export type TServerHotReloadResult = {
     error?: string;
 };
 
+export type TServerReadyMessage = {
+    type: typeof serverHotReloadMessageType.ready;
+    publicUrl: string;
+};
+
 export const isServerHotReloadRequest = (value: unknown): value is TServerHotReloadRequest =>
     typeof value === 'object' &&
     value !== null &&
@@ -24,3 +30,9 @@ export const isServerHotReloadResult = (value: unknown): value is TServerHotRelo
     ((value as TServerHotReloadResult).type === serverHotReloadMessageType.succeeded ||
         (value as TServerHotReloadResult).type === serverHotReloadMessageType.failed) &&
     Array.isArray((value as TServerHotReloadResult).changedFiles);
+
+export const isServerReadyMessage = (value: unknown): value is TServerReadyMessage =>
+    typeof value === 'object' &&
+    value !== null &&
+    (value as TServerReadyMessage).type === serverHotReloadMessageType.ready &&
+    typeof (value as TServerReadyMessage).publicUrl === 'string';

package/common/router/index.ts

@@ -13,7 +13,7 @@ import type { TAnyRouter, TRouterContext as ServerRouterContext, TRouteHttpMetho
 
 import type RouterRequest from './request';
 
-import type { TUserRole } from '@server/services/auth';
+import type { TAuthCheckInput, TAuthTrackingContext } from '@server/services/auth';
 
 import type { TAppArrowFunction } from '@common/app';
 
@@ -86,7 +86,8 @@ export type TRouteOptions = {
     domain?: string;
     accept?: string;
     raw?: boolean; // true to return raw data
-    auth?: TUserRole | boolean;
+    auth?: TAuthCheckInput;
+    authTracking?: TAuthTrackingContext;
     redirectLogged?: string; // Redirect to this route if auth: false and user is logged
 
     // Rendering

package/common/router/layouts.ts

@@ -11,7 +11,7 @@ import type { TDataProvider, TPageRenderContext } from './response/page';
 
 // App
 import internalLayout from '@client/pages/_layout';
-import generatedLayouts, { layoutOrder } from '@/client/.generated/layouts';
+import generatedLayouts, { layoutOrder } from '@generated/client/layouts';
 
 /*----------------------------------
 - CONST

package/common/router/pageSetup.ts

@@ -11,6 +11,7 @@ export const routeSetupOptionKeys = [
     'accept',
     'raw',
     'auth',
+    'authTracking',
     'redirectLogged',
     'static',
     'whenStatic',

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
-	"description": "AI-first SSR, SEO, and TypeScript framework optimized for autonomous agent development.",
-	"version": "2.0.0",
+	"description": "LLM-first Opinionated Typescript Framework for web applications.",
+	"version": "2.1.0",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",
@@ -16,7 +16,9 @@
 		"proteum": "cli/bin.js"
 	},
 	"dependencies": {
-		"@prisma/client": "^6.5.0",
+		"@inkjs/ui": "^2.0.0",
+		"@prisma/adapter-mariadb": "7.2.0",
+		"@prisma/client": "7.2.0",
 		"@rspack/core": "^1.7.9",
 		"@tailwindcss/postcss": "^4.1.17",
 		"accepts": "^1.3.7",
@@ -25,12 +27,14 @@
 		"aws-sdk": "^2.1415.0",
 		"bowser": "^2.11.0",
 		"cli-highlight": "^2.1.11",
+		"clipanion": "^4.0.0-rc.4",
 		"compression": "^1.7.4",
 		"cookie-parser": "^1.4.5",
 		"cors": "^2.8.5",
 		"cron-parser": "^4.0.0",
 		"css-loader": "^6.2.0",
 		"dayjs": "^1.11.5",
+		"dotenv": "^17.2.3",
 		"escape-regexp": "^0.0.1",
 		"eslint": "^9.39.4",
 		"eslint-plugin-jsx-a11y": "^6.10.2",
@@ -47,6 +51,7 @@
 		"history": "^5.0.1",
 		"hpp": "^0.2.3",
 		"human-interval": "^2.0.1",
+		"ink": "^6.8.0",
 		"intl": "^1.2.5",
 		"iso-639-1": "^2.1.9",
 		"jsonwebtoken": "^8.5.1",
@@ -72,7 +77,6 @@
 		"slugify": "^1.6.6",
 		"source-map-support": "^0.5.21",
 		"stopword": "^3.1.1",
-		"style-loader": "^4.0.0",
 		"tailwindcss": "^4.1.17",
 		"ts-alias": "^0.0.7",
 		"ts-node": "^10.9.1",
@@ -81,8 +85,8 @@
 		"typescript-eslint": "^8.57.1",
 		"uuid": "^8.3.2",
 		"validator": "^13.7.0",
+		"webpack-bundle-analyzer": "^5.2.0",
 		"yaml": "^1.10.2",
-		"yargs-parser": "^21.1.1",
 		"youch": "^3.3.3",
 		"youch-terminal": "^2.2.3",
 		"zod": "^4.1.5"
@@ -101,8 +105,6 @@
 		"@types/prompts": "^2.0.14",
 		"@types/sharp": "^0.31.1",
 		"@types/universal-analytics": "^0.4.5",
-		"@types/yargs-parser": "^21.0.0",
-		"schema-dts": "^1.1.2",
-		"webpack-bundle-analyzer": "^5.2.0"
+		"schema-dts": "^1.1.2"
 	}
 }

package/prettier/router-registration-plugin.cjs

@@ -0,0 +1,52 @@
+const path = require('path');
+const { createRequire } = require('module');
+
+const requireFromWorkspace = createRequire(path.join(process.cwd(), 'package.json'));
+
+const estreePlugin = (() => {
+    try {
+        return requireFromWorkspace('prettier/plugins/estree');
+    } catch {
+        return require('prettier/plugins/estree');
+    }
+})();
+
+const basePrinter = estreePlugin.printers.estree;
+const ROUTER_REGISTRATION_METHODS = new Set(['page', 'error']);
+
+const isRouterRegistrationCall = (node) =>
+    node?.type === 'CallExpression' &&
+    node.callee?.type === 'MemberExpression' &&
+    node.callee.object?.type === 'Identifier' &&
+    node.callee.object.name === 'Router' &&
+    node.callee.property?.type === 'Identifier' &&
+    ROUTER_REGISTRATION_METHODS.has(node.callee.property.name);
+
+const printRouterRegistrationCall = (path, print) => {
+    const node = path.getValue();
+    const parts = [path.call(print, 'callee'), '('];
+
+    for (const [index] of node.arguments.entries()) {
+        if (index > 0) parts.push(', ');
+        parts.push(path.call(print, 'arguments', index));
+    }
+
+    parts.push(')');
+
+    return parts;
+};
+
+module.exports = {
+    printers: {
+        estree: {
+            ...basePrinter,
+            print(path, options, print) {
+                const node = path.getValue();
+
+                if (isRouterRegistrationCall(node)) return printRouterRegistrationCall(path, print);
+
+                return basePrinter.print(path, options, print);
+            },
+        },
+    },
+};

package/prettier.config.cjs

@@ -6,4 +6,5 @@ module.exports = {
     semi: true,
     trailingComma: 'all',
     objectWrap: 'preserve',
+    plugins: [require.resolve('./prettier/router-registration-plugin.cjs')],
 };

package/scripts/cleanup-generated-controllers.ts

@@ -14,7 +14,7 @@ const findControllerFiles = (dir: string): string[] => {
             continue;
         }
 
-        if (dirent.isFile() && dirent.name.endsWith('.controller.ts')) files.push(filepath);
+        if (dirent.isFile() && /\.(tsx?|jsx?)$/.test(dirent.name) && !dirent.name.endsWith('.d.ts')) files.push(filepath);
     }
 
     return files;
@@ -25,7 +25,7 @@ if (!repoRoots.length)
     throw new Error('Usage: ts-node scripts/cleanup-generated-controllers.ts <repo-root> [repo-root...]');
 
 for (const repoRoot of repoRoots) {
-    const controllerFiles = findControllerFiles(path.join(repoRoot, 'server', 'services'));
+    const controllerFiles = findControllerFiles(path.join(repoRoot, 'server', 'controllers'));
     let updated = 0;
 
     for (const controllerFile of controllerFiles) {

package/scripts/fix-reference-app-typing.ts

@@ -196,11 +196,11 @@ const patchCentralFiles = () => {
             ),
     );
 
-    applyLiteralReplacement(path.join(UNIQUE_ROOT, 'server/services/Domains/search/search.controller.ts'), (source) =>
+    applyLiteralReplacement(path.join(UNIQUE_ROOT, 'server/controllers/Domains/search.ts'), (source) =>
         source.includes('    public async GetLandingSeoCachedSearches() {')
             ? source
             : assertReplace(
-                  path.join(UNIQUE_ROOT, 'server/services/Domains/search/search.controller.ts'),
+                  path.join(UNIQUE_ROOT, 'server/controllers/Domains/search.ts'),
                   source,
                   `    public async GetLandingSeoCachedSearch() {
         const { Domains } = this.services;