proteum 1.0.2 → 2.0.0

package/AGENTS.md

@@ -0,0 +1,101 @@
+# Proteum Framework
+
+## Vision
+
+Proteum aims to become the first SSR / SEO / TypeScript framework built primarily for non-human developers and AI agents.
+
+The framework should maximize LLM efficiency, correctness, determinism, and performance when building Proteum-based projects.
+
+When tradeoffs exist, prioritize framework decisions in this order:
+
+1. Reduce shipped client bundle size and unnecessary runtime code.
+2. Increase build-time, server-time, and browser-time performance.
+3. Improve SEO output and LLM-friendly, crawlable, semantic HTML.
+4. Preserve explicit, typed, machine-readable contracts for agents.
+
+When working on Proteum itself, optimize for agent ergonomics first:
+
+- Prefer explicit, typed, machine-readable contracts over implicit runtime magic, hidden conventions, ambient globals, or tribal knowledge.
+- Make routes, data loading, server actions / controllers, services, SEO metadata, sitemap generation, static generation, and environment contracts easy to discover, inspect, and explain.
+- Treat SSR and SEO as first-class framework primitives, not app-level patchwork.
+- Prefer server-first designs that avoid shipping client JavaScript unless it is required for user-facing behavior.
+- Favor small, single-purpose files and modules that reduce context load and make edits easier for agents to scope safely.
+- Generated code should improve traceability and type safety, not obscure behavior. It should be deterministic, auditable, and easy for agents to map back to source files.
+- Prefer exact end-to-end contracts for inputs, outputs, errors, side effects, and caching behavior.
+- Prefer framework features that make impact analysis, verification, and debugging easier for agents.
+- Prefer output that is fast to render, easy to crawl, semantically rich, and easy for LLMs to parse reliably.
+- Avoid introducing abstractions that require broad codebase memory to use correctly.
+
+When proposing or implementing a core change, evaluate it against this question:
+
+- Does this make Proteum easier for an AI agent to understand, modify, verify, and operate with high confidence?
+
+# 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.
+
+## Framework Workflow
+
+When changing Proteum itself, always ground the work in the real apps that use it.
+
+- Treat these two projects as the reference surface for current Proteum usage and needs:
+  - `/Users/gaetan/Desktop/Projets/crosspath/platform`
+  - `/Users/gaetan/Desktop/Projets/unique.domains/website`
+- Before proposing a framework change, inspect how both apps currently use the feature, runtime, API, compiler behavior, or generated files involved.
+- Prefer removing framework magic when the same result can be expressed with explicit runtime contracts, generated code, or typed context.
+- If a webpack plugin, Babel plugin, alias, helper, runtime service, or npm package is not meaningfully used by both reference apps, challenge its existence and prefer deleting it.
+
+## Current Proteum Direction
+
+Future changes should preserve and extend the current explicit model instead of reintroducing runtime magic.
+
+- Server route entrypoints live in `*.controller.ts` files.
+- Controllers extend `Controller` and read request-scoped values from `this.request`.
+- Controllers validate request input via `this.input(schema)` inside the method body. Do not use decorators for validation metadata.
+- Normal services extend `Service` and should use `this.services`, `this.models`, and `this.app` instead of implicit globals or magic imports.
+- Do not reintroduce runtime server imports or globals such as `@request`, `@models`, or `@app`.
+- Client pages use `Router.page(path, render)` or `Router.page(path, setup, render)`.
+- SSR data loading belongs in the `setup` function returned object, not in `api.fetch(...)`.
+- Client-side controller access should come from the generated controller tree and client context, not from fake runtime imports.
+
+## Solution Proposals
+
+When presenting a framework solution, make it easy to judge against the real apps.
+
+- Start from the actual mismatch or risk seen in the apps, not from abstract framework theory.
+- Show the target API with concrete client and server usage examples that match current Proteum conventions.
+- Distinguish:
+  - the ideal end-state API
+  - any transitional migration rule or guardrail
+- Call out what becomes impossible or safer after the change.
+- If the change affects generated code, explain what source files drive generation and what artifacts are produced.
+- If the change removes older behavior, explicitly name what is being deleted and why it is obsolete.
+
+## Implementation Rules
+
+- Keep framework changes aligned with the explicit controller/page architecture already adopted in the reference apps.
+- Prefer deleting client-side code, dependencies, and emitted assets when the same capability can stay on the server or be generated statically.
+- Prefer deleting obsolete branches, compatibility layers, plugins, and dependencies over keeping dead paths around.
+- Prefer compiler logic that is deterministic, auditable, and easy for another agent to trace from source to generated output.
+- Reject changes that increase bundle size, runtime cost, or crawlability risk unless the benefit is concrete and validated in both reference apps.
+- When removing old behavior, also remove the related packages, config flags, typings, docs, and dead helper files in the same pass when safe.
+- If a core change breaks one of the reference apps, keep iterating until the framework and the affected app usage are both corrected.
+
+## Real-World Validation
+
+Do not stop at static analysis or isolated core compilation when the change affects runtime behavior.
+
+- Validate framework changes against the two reference apps whenever the change touches routing, controllers, generated code, SSR, client runtime, services, webpack, Babel, or emitted assets.
+- Preferred runtime validation:
+  - run `npx proteum dev --no-cache -port 3xxx` in both apps on explicit ports
+  - open the real pages with Playwright
+  - inspect browser console errors and warnings
+  - inspect server startup and runtime errors
+- Build-only checks are not sufficient for runtime/compiler changes. Use them as supplements, not as the final proof.
+- Keep fixing regressions exposed by the dev-server and browser pass until both apps boot and the browser console shows no new real errors.
+- Treat external/local-environment warnings separately from framework regressions, and say clearly when something is unrelated to the current change.

package/agents/codex/AGENTS.md

@@ -0,0 +1,95 @@
+# Architecture
+
+This is a full stack monolith project using Typescript, NodeJS, Preact, and Proteum.
+
+`/client`: frontend
+    `/assets`: CSS, images and other frontend assets
+    `/components`: reusable components
+    `/pages`: page route files and page-local UI
+    `/hooks`
+`/common`: shared functions, constants and typings
+`/server`: backend
+    `/config`: service configuration
+    `/services`: backend services and controllers
+    `/routes`: explicit non-controller routes
+    `/lib`: helper functions
+`/tests`
+
+# Coding style
+
+See `CODING_STYLE.md`.
+This file is the source of truth for formatting, section-comment structure, and general coding style.
+
+# Files organization
+
+- Always keep one class / react component per file
+- Prefer a deep tree structure that groups files by business concern instead of long file names
+- The default `*.ts` / `*.tsx` file is the browser implementation; use `*.ssr.ts` / `*.ssr.tsx` only for SSR-safe fallbacks
+
+## Centralize feature catalogs (Single Source of Truth)
+
+When implementing a feature that relies on a **curated list of items**, keep **one canonical catalog/registry file** and make all other code import it.
+
+## Runtime access rules
+
+- `@models/types`: Prisma typings only. Can be imported anywhere.
+- Never use runtime value imports from `@request` or `@models`.
+- Never expose request-scoped state through imports.
+
+## Client runtime access
+
+- Page route files use `Router.page(...)`.
+- `Router.page(path, render)` for pages without SSR setup.
+- `Router.page(path, setup, render)` for pages with SSR config/data.
+- `setup` receives the normal page context plus the generated controller tree spread into it.
+- `render` receives the normal page context plus the resolved setup data and the same controller tree spread into it.
+- Components and hooks use `useContext()` to access controller instances and client runtime services.
+
+## Server runtime access
+
+- Normal business logic lives in `/server/services/**/index.ts` classes that extend `Service`.
+- Route entrypoints live in `*.controller.ts` classes that extend `Controller`.
+- Only controller files are indexed as callable API endpoints.
+- Controller methods validate input with `this.input(schema)` and access request scope through `this.request`.
+- Service classes access other services via `this.services` and prisma models via `this.models`.
+- Never use request-scoped state directly inside normal service methods.
+
+# Agent behavior
+
+**Make sure the code you generate integrates perfectly with the current codebase by avoiding repetition and centralizing each purpose.**
+
+## Typings
+
+- Fix typing issues only on the code you wrote.
+- Never cast with `as any` or `as unknown`; fix the type contract or introduce an explicit typed adapter instead. If you find no other solution, tell me in the output.
+
+## 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 the changes you made since the beginning of the conversation. Output as "Commit message".
+
+## Never edit the following files
+
+- Prisma files (except schema.prisma)
+- tsconfigs
+- env
+- Any file / folder that is a symbolic link
+
+If you need to edit them, just suggest it in the chat.
+
+## Don't run any of these commands
+
+```
+git restore
+git reset
+prisma *
+And any git command in the write mode.
+```
+
+# Copy and UX
+
+Before making UX/copy decisions, read `docs/PERSONAS.md`, `docs/PRODUCT.md`, `docs/MARKETING.md`.

package/agents/codex/CODING_STYLE.md

@@ -0,0 +1,71 @@
+# Coding style
+
+This file is the source of truth for codex coding style instructions in Proteum-based projects.
+
+## Baseline
+
+- **The code should be at the highest level of industry, as the product will be used by GAFAMs and will be maintained by a team of 10 developers.**
+- Write clean, consistent, readable code with a tab size of 4.
+- Keep functions and methods short.
+- Everytime possible, create reusable functions and components instead of repeating.
+
+## Formatting
+
+- Optimize for human readability while keeping the code vertically compact when horizontal space is available.
+- Preserve the high-level shape of function calls instead of exploding arguments too early.
+- Keep short arrow functions and short returned object literals compact when they are easy to scan.
+- Keep JSX multiline only when it is clearly more readable; otherwise keep short JSX compact.
+- Avoid staircase formatting and unnecessary blank lines inside short callbacks.
+
+## File organization
+
+- Always keep one class or react component per file.
+- Prefer a deep tree structure that groups files by business concern instead of long file names.
+- The default `*.ts` / `*.tsx` file is the browser implementation; use `*.ssr.ts` / `*.ssr.tsx` only for SSR-safe fallbacks.
+- When implementing a feature that relies on a curated list of items, keep one canonical catalog or registry file and make all other code import it.
+
+## Section comments and simple comments
+
+- Organize files with explicit banner comments:
+
+```typescript
+/*----------------------------------
+- SECTION NAME
+----------------------------------*/
+```
+
+- Reuse project-native section names when possible, especially:
+  - `DEPENDANCES`
+  - `TYPES`
+  - `HELPERS`
+  - `CONSTANTS`
+  - `COMPONENT`
+  - `SERVICE`
+  - `CONTROLEUR`
+  - `ROUTES`
+  - `PAGE`
+  - `CONFIG`
+  - `PUBLIC API`
+  - `API`
+  - `HOOKS`
+  - `LAYOUT`
+  - `CLASS`
+  - `MODULE`
+  - `STATE`
+  - `CONTEXT`
+  - `QUERIES`
+  - `SCHEMA`
+  - `SCHEMAS`
+  - `ROUTING`
+  - `RENDER`
+  - `EXPORTS`
+  - `UTILS`
+  - `CONTENT`
+  - `FILTERS`
+  - `STATS`
+  - `BUILDERS`
+  - `CATALOG`
+  - `CATALOG (SSOT)`
+- File-specific section names are allowed when they improve navigation, for example `ROUTE: ...`, `COMPONENT: ...`, or `VIEW: ...`.
+- Add short, useful comments that explain grouping, intent, lifecycle, or why a block exists.
+- Do not add noisy comments that simply restate obvious code.

package/agents/codex/client/AGENTS.md

@@ -0,0 +1,102 @@
+# Frontend designing
+
+UI components are defined in `/client/pages` and `/client/components`.
+
+## Stack
+
+- Typescript strict
+- Preact with SSR
+- Base UI
+- `@/client/components/Motion`
+- Tailwind CSS 4
+
+Don't use React.useCallback unless strictly necessary.
+
+## Communicate with the server
+
+### Pages
+
+Pages use `Router.page(...)`.
+
+Use `Router.page(path, render)` when there is no SSR setup.
+
+Use `Router.page(path, setup, render)` when the page needs SSR config or SSR data:
+
+```typescript
+Router.page('/dashboard/example', ({ Missions }) => ({
+    _auth: 'USER',
+    missions: Missions.Get(),
+}), ({ request, missions, Missions }) => {
+    return <Page missions={missions} />;
+});
+```
+
+- `setup` returns one flat object
+- keys like `_auth`, `_layout`, `_priority` are route config
+- all other keys are SSR data fetchers
+- never use `api.fetch(...)` in page files
+
+### Components and hooks
+
+Components and hooks access controllers through `useContext()`:
+
+```typescript
+const { Auth, Domains } = useContext();
+```
+
+Then call controller methods directly:
+
+```typescript
+Auth.Signup(data).then((result) => {
+    ...
+});
+```
+
+### Async calls
+
+- Prefer direct controller calls from the context or page render args
+- The thrown errors will automatically be displayed to the user, so don't silent them
+- Never depend on legacy `@app` imports on the client
+
+## Errors handling
+
+Errors catched from controller calls should never be silented.
+If a catch is needed, rethrow or surface the failure clearly.
+
+## Design
+
+- Beautiful, modern, minimalist and intuitive design
+- Responsive layout
+- Enhance the UX with meaningful animations
+
+## Rules
+
+- Always import React in react files (`.tsx`)
+- Don't use any component from `@client/components` unless the codebase already does in that area
+- To create a link / button, always use the `Link` component when the codebase expects navigation links
+
+## Keep the code organized
+
+- Split big components (more than 1000 lines) into smaller components
+- Always use one component per file
+- Everytime possible, load data and define action handlers in the directly concerned component instead of passing everything from the parent
+
+## Split the page by sections via comments
+
+Use:
+
+```typescript
+/*----------------------------------
+- SECTION NAME
+----------------------------------*/
+```
+
+File sections:
+- DEPENDENCIES
+- TYPES
+- COMPONENT / PAGE
+
+Component / page sections:
+- INIT
+- ACTIONS
+- RENDER

package/agents/codex/client/pages/AGENTS.md

@@ -0,0 +1,35 @@
+# Page files
+
+Page files are located in `/client/pages/**/*.tsx`.
+
+## Router.page contract
+
+Use one of these forms:
+
+```typescript
+Router.page('/path', ({ request, ServiceName }) => {
+    return <Page />;
+});
+```
+
+```typescript
+Router.page('/path', ({ ServiceName }) => ({
+    _auth: 'USER',
+    dataKey: ServiceName.MethodName({ param1: 'value' }),
+}), ({ request, dataKey, ServiceName }) => {
+    return <Page data={dataKey} />;
+});
+```
+
+- `setup` is the second `Router.page` argument
+- `render` is the last `Router.page` argument
+- `setup` receives the page context plus generated controller instances
+- `render` receives the page context, resolved setup data, and generated controller instances
+- Never use `api.fetch(...)` in page files
+- Never import client service values from `@app`
+
+## Typings
+
+- Treat generated controller method typings as the source of truth
+- Never cast controller methods, their parameters, or their return types
+- If a page needs route data, return it from `setup` and consume it from `render`

package/agents/codex/server/routes/AGENTS.md

@@ -0,0 +1,12 @@
+# Server routes
+
+Use `/server/routes/**` only for explicit custom routes that should not be generated from controllers.
+
+- Callable app APIs belong in `*.controller.ts` files under `/server/services`
+- `/server/routes/**` is for manual `Router.get/post/...` routes, redirects, resources, OAuth callbacks, etc.
+
+## Generate absolute urls
+
+The absolute urls are generated via `Router.url()`:
+
+`const absoluteUrl = Router.url('/relative/path')`

package/agents/codex/server/services/AGENTS.md

@@ -0,0 +1,137 @@
+# Server Services
+
+Stack:
+- Typescript with strict mode
+- NodeJS
+- Prisma 7 ORM
+
+## 1. Create the service file in `/server/services/<service name>/index.ts`
+
+Template:
+
+```typescript
+/*----------------------------------
+- DEPENDANCE
+----------------------------------*/
+
+// Core libs
+import Service from '@server/app/service';
+
+/*----------------------------------
+- TYPES
+----------------------------------*/
+
+export type Config = <ServiceConfig>;
+
+/*----------------------------------
+- SERVICE
+----------------------------------*/
+
+export default class ServiceName extends Service<Config, {}, CrossPath, CrossPath> {
+
+    public async MethodName(data: { param1: string }) {
+        const { OtherService } = this.services;
+
+        return OtherService.OtherMethod(data);
+    }
+}
+```
+
+`<ServiceConfig>` is an object containing api keys and other variables we can adjust in the future.
+
+## 2. Create the controller file in `/server/services/<service name>/<ServiceName>.controller.ts`
+
+Template:
+
+```typescript
+import Controller, { schema } from '@server/app/controller';
+import type { TMethodInput } from './index';
+
+const MethodInput = schema.object({
+    param1: schema.string(),
+});
+
+export default class ServiceNameController extends Controller {
+
+    public async MethodName() {
+        const data = this.input(MethodInput);
+        const { ServiceName } = this.services;
+        const { auth, request, user } = this.request;
+
+        return ServiceName.MethodName(data);
+    }
+}
+```
+
+Rules:
+- Only `*.controller.ts` files are indexed as callable API endpoints
+- Route path is derived from the controller file path and the method name
+- `this.input(schema)` is the only validation entrypoint
+- Call `this.input(...)` at most once per controller method
+- Request-scoped state exists only on `this.request`
+
+## 3. Create the service metas file in `/server/services/<service name>/service.json`
+
+```json
+{
+    "id": "CrossPath/ServiceName",
+    "name": "CrossPathServiceName",
+    "parent": "app",
+    "dependences": []
+}
+```
+
+## 4. Register the service in `/server/config/<app>.ts`
+
+```typescript
+app.setup('ServiceName', 'CrossPath/ServiceName', <ServiceConfig>);
+```
+
+## 5. Keep classes clean
+
+If the class grows too large, split business concerns into subservices.
+
+## 6. Use request-aware features only in controllers
+
+Use:
+
+```typescript
+const { auth, request, user, response } = this.request;
+```
+
+- Never import runtime request state from `@request`
+- Never access request-scoped state inside normal service methods unless the controller passes the minimal values explicitly
+
+## 7. Fetch and return data from the database
+
+Use runtime models through `this.models`:
+
+```typescript
+const users = await this.models.user.findMany({
+    select: {
+        id: true,
+    },
+});
+```
+
+Use prisma typings through `@models/types` only:
+
+```typescript
+import type * as Models from '@models/types';
+```
+
+Rules:
+- Never edit prisma files, except the schema
+- Never use runtime `@models` imports
+- In all queries and joins, always specify what fields to select
+
+## DTO and typing rules
+
+- Prefer inferred return types:
+`export type TResult = Awaited<ReturnType<MyService["MethodName"]>>;`
+- Never create manual DTO types when the exact return type can be inferred
+
+## Errors handling
+
+Unhandled errors are passed to the `bug` app hook.
+Never silent caught errors. Throw `Anomaly` with enough detail and the original error when needed.

package/agents/codex/tests/AGENTS.md

@@ -0,0 +1,8 @@
+# Codex guidance for writing E2E tests
+
+- Understand the typical user flow and the main feature branches
+- Favor as many tests as possible to cover real usage
+- Always locate elements via their `data-testid` attribute
+- Add `data-testid` where needed
+- Keep test files clean, organized and structured
+- Test the current controller/page runtime model, not legacy `@Route` or `api.fetch` behavior

package/cli/app/config.ts

@@ -21,15 +21,13 @@ import type { TEnvConfig } from '../../server/app/container/config';
 - LOADE
 ----------------------------------*/
 export default class ConfigParser {
-
     public constructor(
         public appDir: string,
-        public envName?: string
-    ) {
-
-    }
+        public envName?: string,
+        public routerPortOverride?: number,
+    ) {}
 
-    private loadYaml( filepath: string ) {
+    private loadYaml(filepath: string) {
         console.info(`Loading config ${filepath}`);
         const rawConfig = fs.readFileSync(filepath, 'utf-8');
         return yaml.parse(rawConfig);
@@ -38,17 +36,21 @@ export default class ConfigParser {
     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);
+        console.log('[app] Using environment:', process.env.NODE_ENV);
         const envFileName = this.appDir + '/env.yaml';
-        const envFile = this.loadYaml( envFileName );
+        const envFile = this.loadYaml(envFileName);
         return {
             ...envFile,
-            version: 'CLI'
-        }
+            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 );
+        return this.loadYaml(identityFile);
     }
 }