proteum 2.1.0-5 → 2.1.1

package/cli/compiler/common/commands.ts

@@ -0,0 +1,175 @@
+import fs from 'fs-extra';
+import path from 'path';
+import ts from 'typescript';
+
+export type TCommandSourceLocation = { line: number; column: number };
+
+export type TCommandMethodMeta = {
+    name: string;
+    path: string;
+    sourceLocation: TCommandSourceLocation;
+};
+
+export type TCommandFileMeta = {
+    importPath: string;
+    filepath: string;
+    className: string;
+    commandBasePath: string;
+    methods: TCommandMethodMeta[];
+};
+
+type TCommandSearchDir = { importPrefix: string; root: string };
+
+const getCommandSegments = (relativePath: string) => {
+    const segments = relativePath
+        .replace(/\.ts$/, '')
+        .split('/')
+        .filter(Boolean);
+
+    if (segments[segments.length - 1] === 'index') {
+        segments.pop();
+    }
+
+    return segments;
+};
+
+const getCommandBasePathFromFilepath = (filepath: string, root: string) =>
+    getCommandSegments(path.relative(root, filepath).replace(/\\/g, '/')).join('/');
+
+const getGeneratedClassName = (filepath: string) => {
+    const filename = path.basename(filepath, '.ts').replace(/[^A-Za-z0-9_$]+/g, '_');
+    const normalized = filename.length ? filename : 'Commands';
+
+    return normalized[0].toUpperCase() + normalized.substring(1);
+};
+
+const buildImportPath = (searchDir: TCommandSearchDir, filepath: string) =>
+    searchDir.importPrefix + path.relative(searchDir.root, filepath).replace(/\\/g, '/').replace(/\.ts$/, '');
+
+const findCommandFiles = (dir: string): string[] => {
+    if (!fs.existsSync(dir)) return [];
+
+    const files: string[] = [];
+
+    for (const dirent of fs.readdirSync(dir, { withFileTypes: true })) {
+        const filepath = path.join(dir, dirent.name);
+
+        if (dirent.isDirectory()) {
+            files.push(...findCommandFiles(filepath));
+            continue;
+        }
+
+        if (!dirent.isFile()) continue;
+        if (!dirent.name.endsWith('.ts')) continue;
+        if (dirent.name.endsWith('.d.ts')) continue;
+
+        files.push(filepath);
+    }
+
+    return files;
+};
+
+const parseSourceFile = (filepath: string, code: string) =>
+    ts.createSourceFile(
+        filepath,
+        code,
+        ts.ScriptTarget.Latest,
+        true,
+        filepath.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+    );
+
+const getNodeLocation = (sourceFile: ts.SourceFile, node: ts.Node): TCommandSourceLocation => {
+    const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+
+    return { line: line + 1, column: character + 1 };
+};
+
+const hasModifier = (node: ts.Node, kind: ts.SyntaxKind) =>
+    !!node.modifiers?.some((modifier) => modifier.kind === kind);
+
+const getDefaultExportClass = (sourceFile: ts.SourceFile) => {
+    const classes = new Map<string, ts.ClassDeclaration>();
+
+    for (const statement of sourceFile.statements) {
+        if (ts.isClassDeclaration(statement) && statement.name) {
+            classes.set(statement.name.text, statement);
+
+            if (hasModifier(statement, ts.SyntaxKind.DefaultKeyword)) {
+                return statement;
+            }
+        }
+    }
+
+    for (const statement of sourceFile.statements) {
+        if (!ts.isExportAssignment(statement) || statement.isExportEquals) continue;
+
+        if (ts.isIdentifier(statement.expression)) {
+            return classes.get(statement.expression.text);
+        }
+    }
+
+    return undefined;
+};
+
+const getExportedString = (sourceFile: ts.SourceFile, exportName: string) => {
+    for (const statement of sourceFile.statements) {
+        if (!ts.isVariableStatement(statement)) continue;
+        if (!hasModifier(statement, ts.SyntaxKind.ExportKeyword)) continue;
+
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name)) continue;
+            if (declaration.name.text !== exportName) continue;
+            if (!declaration.initializer || !ts.isStringLiteral(declaration.initializer)) continue;
+
+            return declaration.initializer.text;
+        }
+    }
+
+    return undefined;
+};
+
+export const indexCommands = (searchDirs: TCommandSearchDir[]) => {
+    const commands: TCommandFileMeta[] = [];
+
+    for (const searchDir of searchDirs) {
+        const commandFiles = findCommandFiles(searchDir.root);
+
+        for (const filepath of commandFiles.sort((a, b) => a.localeCompare(b))) {
+            const code = fs.readFileSync(filepath, 'utf8');
+            const sourceFile = parseSourceFile(filepath, code);
+
+            const commandPathOverride = getExportedString(sourceFile, 'commandPath');
+            const defaultClass = getDefaultExportClass(sourceFile);
+
+            if (!defaultClass) continue;
+
+            const className = defaultClass.name?.text || getGeneratedClassName(filepath);
+            const commandBasePath = commandPathOverride || getCommandBasePathFromFilepath(filepath, searchDir.root);
+            const methods: TCommandMethodMeta[] = [];
+
+            for (const member of defaultClass.members) {
+                if (!ts.isMethodDeclaration(member)) continue;
+                if (!member.body) continue;
+                if (!member.name || !ts.isIdentifier(member.name)) continue;
+
+                methods.push({
+                    name: member.name.text,
+                    path: [commandBasePath, member.name.text].filter(Boolean).join('/'),
+                    sourceLocation: getNodeLocation(sourceFile, member.name),
+                });
+            }
+
+            if (!methods.length) continue;
+
+            commands.push({
+                filepath,
+                importPath: buildImportPath(searchDir, filepath),
+                className,
+                commandBasePath,
+                methods,
+            });
+        }
+    }
+
+    return commands.sort((a, b) => a.filepath.localeCompare(b.filepath));
+};

package/cli/compiler/common/proteumManifest.ts

@@ -2,130 +2,21 @@ import path from 'path';
 import fs from 'fs-extra';
 
 import writeIfChanged from '../writeIfChanged';
-
-export type TProteumManifestScope = 'app' | 'framework';
-export type TProteumManifestSourceLocation = { line: number; column: number };
-export type TProteumManifestRouteTargetResolution = 'literal' | 'static-expression' | 'dynamic-expression';
-export type TProteumManifestDiagnosticLevel = 'warning' | 'error';
-
-export type TProteumManifestDiagnostic = {
-    level: TProteumManifestDiagnosticLevel;
-    code: string;
-    message: string;
-    filepath: string;
-    sourceLocation?: TProteumManifestSourceLocation;
-    relatedFilepaths?: string[];
-};
-
-export type TProteumManifestService = {
-    kind: 'service' | 'ref';
-    id?: string;
-    registeredName: string;
-    metaName?: string;
-    parent: string;
-    priority: number;
-    importPath?: string;
-    sourceDir?: string;
-    metasFilepath?: string;
-    refTo?: string;
-    scope: TProteumManifestScope;
-};
-
-export type TProteumManifestController = {
-    className: string;
-    importPath: string;
-    filepath: string;
-    sourceLocation: TProteumManifestSourceLocation;
-    routeBasePath: string;
-    methodName: string;
-    inputCallsCount: number;
-    hasInput: boolean;
-    routePath: string;
-    httpPath: string;
-    clientAccessor: string;
-    scope: TProteumManifestScope;
-};
-
-export type TProteumManifestRoute = {
-    kind: 'client-page' | 'client-error' | 'server-route';
-    methodName: string;
-    serviceLocalName: string;
-    filepath: string;
-    sourceLocation: TProteumManifestSourceLocation;
-    targetResolution: TProteumManifestRouteTargetResolution;
-    path?: string;
-    pathRaw?: string;
-    code?: number;
-    codeRaw?: string;
-    optionKeys: string[];
-    normalizedOptionKeys: string[];
-    invalidOptionKeys: string[];
-    reservedOptionKeys: string[];
-    optionsRaw?: string;
-    hasSetup: boolean;
-    chunkId?: string;
-    chunkFilepath?: string;
-    scope: TProteumManifestScope;
-};
-
-export type TProteumManifestLayout = {
-    chunkId: string;
-    filepath: string;
-    importPath: string;
-    depth: number;
-    scope: TProteumManifestScope;
-};
-
-export type TProteumManifest = {
-    version: 1;
-    app: {
-        root: string;
-        coreRoot: string;
-        identityFilepath: string;
-        identity: {
-            name: string;
-            identifier: string;
-            description: string;
-            language?: string;
-            locale?: string;
-            title?: string;
-            titleSuffix?: string;
-            fullTitle?: string;
-            webDescription?: string;
-            version?: string;
-        };
-    };
-    conventions: {
-        routeSetupOptionKeys: string[];
-        reservedRouteSetupKeys: string[];
-    };
-    env: {
-        source: string;
-        loadedVariableKeys: string[];
-        requiredVariables: {
-            key: string;
-            possibleValues: string[];
-            provided: boolean;
-        }[];
-        resolved: {
-            name: string;
-            profile: string;
-            routerPort: number;
-            routerCurrentDomain: string;
-        };
-    };
-    services: {
-        app: TProteumManifestService[];
-        routerPlugins: TProteumManifestService[];
-    };
-    controllers: TProteumManifestController[];
-    routes: {
-        client: TProteumManifestRoute[];
-        server: TProteumManifestRoute[];
-    };
-    layouts: TProteumManifestLayout[];
-    diagnostics: TProteumManifestDiagnostic[];
-};
+import type { TProteumManifest } from '@common/dev/proteumManifest';
+
+export type {
+    TProteumManifest,
+    TProteumManifestCommand,
+    TProteumManifestController,
+    TProteumManifestDiagnostic,
+    TProteumManifestDiagnosticLevel,
+    TProteumManifestLayout,
+    TProteumManifestRoute,
+    TProteumManifestRouteTargetResolution,
+    TProteumManifestScope,
+    TProteumManifestService,
+    TProteumManifestSourceLocation,
+} from '@common/dev/proteumManifest';
 
 export const getProteumManifestPath = (appRoot: string) => path.join(appRoot, '.proteum', 'manifest.json');
 

package/cli/compiler/index.ts

@@ -16,6 +16,7 @@ import { writeClientManifest } from './common/clientManifest';
 import { logVerbose } from '../runtime/verbose';
 import { createCompileReporter, type TCompileReporter } from '../presentation/compileReporter';
 import { generateRoutingArtifacts } from './artifacts/routing';
+import { generateCommandArtifacts } from './artifacts/commands';
 import { generateControllerArtifacts } from './artifacts/controllers';
 import { generateServiceArtifacts } from './artifacts/services';
 import { writeCurrentProteumManifest } from './artifacts/manifest';
@@ -32,6 +33,7 @@ export default class Compiler {
     public compiling: { [compiler: string]: Promise<void> } = {};
     private recentCompilationResults: { [compiler: string]: TRecentCompilationResult } = {};
     private recentModifiedFiles: { [compiler: string]: string[] } = {};
+    private manualModifiedFiles: { [compiler: string]: Set<string> } = {};
     private refreshingGeneratedArtifacts?: Promise<void>;
     private compileReporter?: TCompileReporter;
 
@@ -140,11 +142,13 @@ export default class Compiler {
             this.refreshingGeneratedArtifacts = (async () => {
                 const services = generateServiceArtifacts();
                 const controllers = generateControllerArtifacts();
+                const commands = generateCommandArtifacts();
                 const { clientRoutes, serverRoutes, layouts } = generateRoutingArtifacts();
 
                 writeCurrentProteumManifest({
                     services,
                     controllers,
+                    commands,
                     routes: { client: clientRoutes, server: serverRoutes },
                     layouts,
                 });
@@ -172,6 +176,21 @@ export default class Compiler {
         return recentCompilationResults;
     }
 
+    public noteManualModifiedFiles(compilerNames: string[] | string, filepaths: string[]) {
+        const normalizedCompilerNames = Array.isArray(compilerNames) ? compilerNames : [compilerNames];
+        const normalizedFilepaths = filepaths.map((filepath) => normalizePath(path.resolve(filepath)));
+
+        for (const compilerName of normalizedCompilerNames) {
+            const pendingFiles = this.manualModifiedFiles[compilerName] || new Set<string>();
+
+            for (const filepath of normalizedFilepaths) {
+                pendingFiles.add(filepath);
+            }
+
+            this.manualModifiedFiles[compilerName] = pendingFiles;
+        }
+    }
+
     public async create() {
         await this.warmupApp();
 
@@ -204,9 +223,13 @@ export default class Compiler {
             compiler.hooks.compile.tap(name, (compilation) => {
                 this.callbacks.before && this.callbacks.before(compiler);
 
-                this.recentModifiedFiles[name] = [...(compiler.modifiedFiles ? [...compiler.modifiedFiles] : [])].map(
-                    (filepath) => normalizePath(path.resolve(filepath)),
+                const compilerModifiedFiles = [...(compiler.modifiedFiles ? [...compiler.modifiedFiles] : [])].map((filepath) =>
+                    normalizePath(path.resolve(filepath)),
                 );
+                const manualModifiedFiles = [...(this.manualModifiedFiles[name] || [])];
+                delete this.manualModifiedFiles[name];
+
+                this.recentModifiedFiles[name] = [...new Set([...compilerModifiedFiles, ...manualModifiedFiles])];
 
                 this.compiling[name] = new Promise((resolve) => (finished = resolve));
 

package/cli/compiler/server/index.ts

@@ -184,9 +184,12 @@ export default function createCompiler(
                         // Prisma 7 generates TypeScript entrypoints under var/prisma.
                         app.paths.root + '/var/prisma',
 
+                        app.paths.root + '/commands',
+
                         // Dossiers server uniquement pour le bundle server
                         app.paths.root + '/server',
                         app.paths.server.generated,
+                        ...frameworkRoots.map((rootPath) => rootPath + '/commands'),
                         ...frameworkRoots.map((rootPath) => rootPath + '/client'),
                         ...frameworkRoots.map((rootPath) => rootPath + '/common'),
                         ...frameworkRoots.map((rootPath) => rootPath + '/server'),

package/cli/presentation/commands.ts

@@ -14,6 +14,7 @@ export const proteumCommandNames = [
     'doctor',
     'explain',
     'trace',
+    'command',
 ] as const;
 
 export type TProteumCommandName = (typeof proteumCommandNames)[number];
@@ -46,7 +47,7 @@ export const proteumRecommendedFlow: TRow[] = [
 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', 'trace'] },
+    { title: 'Manifest and contracts', names: ['doctor', 'explain', 'trace', 'command'] },
     { title: 'Project scaffolding', names: ['init'] },
 ];
 
@@ -171,14 +172,14 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         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]',
+        usage: 'proteum explain [--all|--app|--conventions|--env|--services|--controllers|--commands|--routes|--layouts|--diagnostics] [--json]',
         bestFor:
-            'Inspecting how source files became generated routes, controllers, layouts, services, and diagnostics without reading compiler internals.',
+            'Inspecting how source files became generated routes, controllers, commands, 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: 'Inspect generated routes, controllers, and commands together',
+                command: 'proteum explain --routes --controllers --commands',
             },
             { description: 'Emit the selected manifest sections as JSON', command: 'proteum explain --routes --json' },
         ],
@@ -206,6 +207,37 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         ],
         status: 'experimental',
     },
+    command: {
+        name: 'command',
+        category: 'Manifest and contracts',
+        summary: 'Run a dev-only app command from /commands or against an existing dev instance.',
+        usage: 'proteum command <path> [--port <port>|--url <baseUrl>] [--json]',
+        bestFor:
+            'Internal testing, debugging, and one-off service execution that should not be exposed as a normal controller or route.',
+        examples: [
+            {
+                description: 'Run a local command through a temporary bundled dev server',
+                command: 'proteum command proteum/diagnostics/ping',
+            },
+            {
+                description: 'Run a command against an existing dev server',
+                command: 'proteum command proteum/diagnostics/ping --port 3101',
+            },
+            {
+                description: 'Emit the command execution as JSON',
+                command: 'proteum command proteum/diagnostics/ping --json',
+            },
+        ],
+        notes: [
+            'Commands live under `./commands/**/*.ts` and default-export a class that extends `{ Commands }` from `@server/app/commands`.',
+            'Methods are addressed by file path plus method name, mirroring controller path generation.',
+            'Proteum creates `./commands/tsconfig.json` and `.proteum/server/commands.d.ts` so `/commands` gets a command-specific alias/type project.',
+            'Prefer `extends Commands` directly inside `/commands`; importing the app class is still supported through a generated command-only `@/server/index` type alias.',
+            'Without `--port` or `--url`, Proteum refreshes generated artifacts, builds the dev output, starts a temporary local dev server, runs the command, and exits.',
+            'With `--port` or `--url`, Proteum talks to the running app over the dev-only `__proteum/commands` HTTP endpoints.',
+        ],
+        status: 'experimental',
+    },
 };
 
 export const isLikelyProteumAppRoot = (workdir: string) =>

package/cli/runtime/commands.ts

@@ -153,6 +153,7 @@ class ExplainCommand extends ProteumCommand {
     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 commands = Option.Boolean('--commands', false, { description: 'Include the commands 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, {
@@ -169,6 +170,7 @@ class ExplainCommand extends ProteumCommand {
             env: this.env,
             services: this.services,
             controllers: this.controllers,
+            commands: this.commands,
             routes: this.routes,
             layouts: this.layouts,
             diagnostics: this.diagnostics,
@@ -177,7 +179,7 @@ class ExplainCommand extends ProteumCommand {
         applyLegacyBooleanArgs(
             'explain',
             this.legacyArgs,
-            ['json', 'all', 'app', 'conventions', 'env', 'services', 'controllers', 'routes', 'layouts', 'diagnostics'],
+            ['json', 'all', 'app', 'conventions', 'env', 'services', 'controllers', 'commands', 'routes', 'layouts', 'diagnostics'],
             args,
         );
         this.setCliArgs(args);
@@ -214,6 +216,30 @@ class TraceCommand extends ProteumCommand {
     }
 }
 
+class CommandCommand extends ProteumCommand {
+    public static paths = [['command']];
+
+    public static usage = buildUsage('command');
+
+    public port = Option.String('--port', { description: 'Target an existing dev server on the given port.' });
+    public url = Option.String('--url', { description: 'Target an existing dev server at the given base URL.' });
+    public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    public args = Option.Rest();
+
+    public async execute() {
+        const [path = ''] = this.args;
+
+        this.setCliArgs({
+            path,
+            port: this.port ?? '',
+            url: this.url ?? '',
+            json: this.json,
+        });
+
+        await runCommandModule(() => import('../commands/command'));
+    }
+}
+
 export const registeredCommands = {
     init: InitCommand,
     dev: DevCommand,
@@ -225,6 +251,7 @@ export const registeredCommands = {
     doctor: DoctorCommand,
     explain: ExplainCommand,
     trace: TraceCommand,
+    command: CommandCommand,
 } as const;
 
 export const createCli = (version: string) => {
@@ -247,6 +274,7 @@ export const createCli = (version: string) => {
     clipanion.register(DoctorCommand);
     clipanion.register(ExplainCommand);
     clipanion.register(TraceCommand);
+    clipanion.register(CommandCommand);
 
     return clipanion;
 };

package/cli/tsconfig.json

@@ -29,9 +29,12 @@
         "outDir": "./bin",
 
         "paths": {
+            "@client/*": [ "../client/*" ],
             "@cli/*": [ "./*" ],
             "@cli/app": [ "./app" ],
-            "@cli": [ "./" ]
+            "@cli": [ "./" ],
+            "@common/*": [ "../common/*" ],
+            "@server/*": [ "../server/*" ]
         },
     },
 

package/cli/utils/check.ts

@@ -5,7 +5,7 @@ import cli from '..';
 import Compiler from '../compiler';
 import { runProcess } from './runProcess';
 
-const tsconfigPaths = ['client/tsconfig.json', 'server/tsconfig.json'];
+const tsconfigPaths = ['client/tsconfig.json', 'server/tsconfig.json', 'commands/tsconfig.json'];
 const eslintConfigPaths = ['eslint.config.mjs', 'eslint.config.js', 'eslint.config.cjs'];
 
 const resolveInstalledBinary = (name: string) => {

package/client/app/component.tsx

@@ -21,10 +21,17 @@ export default function App({ context }: { context: ClientContext }) {
     const curLayout = context.page?.layout;
     const [layout, setLayout] = React.useState<Layout | false | undefined>(curLayout);
     const [apiData, setApiData] = React.useState<{ [k: string]: any } | null>(context.page?.data || {});
+    const shouldEnableDevProfiler = __DEV__ && typeof window !== 'undefined' && window.dev;
+    const [isDevProfilerMounted, setDevProfilerMounted] = React.useState(false);
 
     // TODO: context.page is always provided in the context on the client side
     if (context.app.side === 'client') context.app.setLayout = setLayout;
 
+    React.useEffect(() => {
+        if (!shouldEnableDevProfiler) return;
+        setDevProfilerMounted(true);
+    }, [shouldEnableDevProfiler]);
+
     const layoutProps: LayoutProps = {
         ...context,
         context,
@@ -32,10 +39,14 @@ export default function App({ context }: { context: ClientContext }) {
         menu: undefined,
         children: undefined,
     };
+    const DevProfiler = shouldEnableDevProfiler
+        ? ((require('@client/dev/profiler') as typeof import('@client/dev/profiler')).default as React.ComponentType)
+        : null;
 
     return (
         <ReactClientContext.Provider value={context}>
             <DialogManager />
+            {DevProfiler && isDevProfilerMounted ? <DevProfiler /> : null}
 
             {!layout ? (
                 <RouterComponent service={context.Router} />