proteum 2.0.0 → 2.1.0

package/agents/project/AGENTS.md

@@ -0,0 +1,138 @@
+# Architecture
+
+This is a full stack monolith project using Typescript, NodeJS, Preact, and Proteum.
+
+`/client`: frontend
+    `/assets`: CSS, images and other frontend assets
+    `/catalogs`: client-only catalogs and registries
+    `/components`: reusable components
+    `/pages`: page route files and page-local UI
+    `/hooks`
+`/common`: shared functions, constants, typings, and cross-runtime catalogs
+`/server`: backend
+    `/catalogs`: server-only catalogs and registries
+    `/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.
+
+# Framework contract
+
+For Proteum-wide project scaffolding, routing, SSR, controller, service, generated-code, and maintenance rules, use the
+framework guide in the Proteum repository at `agents/framework/AGENTS.md`.
+From a normal Proteum project install, read it at `./node_modules/proteum/agents/framework/AGENTS.md`.
+
+Start framework inspection with:
+
+- `./.proteum/manifest.json`
+- `npx proteum explain`
+- `npx proteum doctor`
+
+Generated files live under `./.proteum` and should not be edited by hand.
+Project code should use the generated aliases `@generated/client/*`, `@generated/common/*`, and `@generated/server/*`.
+Client context is typically imported from `@/client/context`.
+Prefer type inference from the explicit application class in `./server/index.ts` whenever possible. Treat it as the
+canonical type root for app services, router services, router context, and models instead of duplicating manual type
+declarations.
+
+# 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 normal implementation; use `*.ssr.ts` / `*.ssr.tsx` only when the project
+needs an SSR-specific variant
+
+## 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.
+
+- Client-only catalogs live in `/client/catalogs/**`
+- Server-only catalogs live in `/server/catalogs/**`
+- Shared catalogs used by both runtimes live in `/common/catalogs/**`
+- Organize those root catalog trees by business concern (mirror the feature path when useful)
+- Do not create nested `catalogs/` folders inside `/client/pages/**`, `/client/components/**`, `/server/services/**`, or similar feature folders
+
+## 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.
+- Keep app services, router services, router context, and model contracts inferred from `./server/index.ts` whenever
+possible instead of recreating parallel type maps.
+
+## 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 the app client context hook, usually imported from `@/client/context`.
+- For UI primitives, prefer the project's shared Shadcn-based components whenever they already exist and fit the need before creating bespoke buttons, inputs, dialogs, or similar building blocks.
+
+## Server runtime access
+
+- Normal business logic lives in `/server/services/**/index.ts` classes that extend `Service`.
+- Route entrypoints live in `/server/controllers/**/*.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`.
+- App service types should be inferred from the explicit application graph rooted at `./server/index.ts`.
+- Router services and request/context values such as `user`, `auth`, and similar request-scoped contracts should come
+from inferred request and app types, not ad hoc casts.
+- Models should be inferred from the app/model registry rooted at `./server/index.ts` and exposed through the generated
+server app shim, not from duplicated manual model maps.
+- Never use request-scoped state directly inside normal service methods.
+- Controllers should resolve auth and request-derived values, then pass plain typed arguments into services.
+- When referencing an app service, a router service, or a model, expose it in the current block scope first by
+destructuring from `this.request`, `this.app`, `this.models`, or the generated app/model accessors where applicable,
+then call methods on that local binding. The service, router value, or model should be the first element of the callee
+chain.
+
+# Agent behavior
+
+**Make sure the code you generate integrates perfectly with the current codebase by avoiding repetition and centralizing each purpose.**
+
+## Typings
+
+- Keep strong, consistent TypeScript typings across the whole project.
+- Do not introduce `any` or `unknown`, including through casts, helper aliases, or fallback generic defaults.
+- 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
+
+- Every time I input error messages without any instructions, don't implement fixes.
+Instead, investigate the potential causes of the errors, and for each:
+    1. Evaluate / quantify the probabilities
+    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".
+
+## High-impact files
+
+- Do not edit generated files under `.proteum` by hand.
+- Treat `tsconfig*.json`, `env*.yaml`, Prisma-generated files, and symbolic links as high-impact.
+- Edit them only when the task actually requires it, and keep those changes minimal and explicit.
+
+If a high-impact file change is not required for the task, leave it alone.
+
+## 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`.
+When implementing UI, prefer existing Shadcn components or local wrappers around them whenever they can satisfy the requirement cleanly.

package/agents/{codex → project}/CODING_STYLE.md

@@ -7,7 +7,7 @@ This file is the source of truth for codex coding style instructions in Proteum-
 - **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.
+- Every time possible, create reusable functions and components instead of repeating.
 
 ## Formatting
 
@@ -16,10 +16,11 @@ This file is the source of truth for codex coding style instructions in Proteum-
 - 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.
+- Keep `Router.page(...)` and `Router.error(...)` registrations in the compact inline-call shape when possible, for example `Router.page('/path', setup, render);`.
 
 ## File organization
 
-- Always keep one class or react component per file.
+- 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.

package/agents/project/client/AGENTS.md

@@ -0,0 +1,108 @@
+# Frontend
+
+UI components are defined in `/client/pages` and `/client/components`.
+Client-only catalogs and registries live in `/client/catalogs/**`.
+
+## Stack
+
+- Typescript strict
+- Preact with SSR
+- Follow the UI stack already used in the touched area.
+- Many Proteum apps use Tailwind and `@/client/components/Motion`, but those are app conventions, not framework guarantees.
+- When the project already exposes Shadcn components or `client/components/ui/**` primitives derived from them, prefer those components for standard UI instead of rebuilding the same primitives locally.
+
+Don't add `React` imports just for JSX.
+Use `React` only when a React or Preact API is actually needed.
+Don't use `React.useCallback` unless strictly necessary or already common in the touched area.
+
+## 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', ({ Feature }) => ({
+    _auth: 'USER',
+    dataKey: Feature.loadExample(),
+}), ({ dataKey }) => <Page data={dataKey} />);
+```
+
+- Keep the route registration compact instead of exploding the whole call into a staircase layout.
+- `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 the app client context hook, typically `useContext()` from `@/client/context`:
+
+```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
+- Follow the controller naming and hierarchy already used in the touched feature instead of inventing a new one
+- The thrown errors will automatically be displayed to the user, so don't silence them
+- Never depend on legacy `@app` imports on the client
+
+## Errors handling
+
+Errors caught from controller calls should never be silenced.
+If a catch is needed, rethrow or surface the failure clearly.
+
+## Design
+
+- Follow the existing design language of the app or feature area.
+- Keep layouts responsive and accessible.
+- Add motion only when the area already uses it or when it materially improves UX.
+- Reuse Shadcn-based shared primitives first for common controls like buttons, inputs, dialogs, dropdowns, tabs, tables, and forms when they cover the requirement.
+- Create custom UI primitives only when the existing Shadcn layer cannot express the interaction or visual requirement cleanly.
+
+## Rules
+
+- Don't add `React` imports unless the file actually uses a React or Preact API.
+- Don't use any component from `@client/components` unless the codebase already does in that area, except for established shared primitives such as the project's Shadcn-based `client/components/ui/**` layer
+- 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
+- Every time possible, load data and define action handlers in the directly concerned component instead of passing everything from the parent
+- Put curated lists, option registries, UI copy catalogs, and similar SSOT data under `/client/catalogs/**`, not inside page or component folders
+
+## 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 → project}/client/pages/AGENTS.md

@@ -7,26 +7,26 @@ Page files are located in `/client/pages/**/*.tsx`.
 Use one of these forms:
 
 ```typescript
-Router.page('/path', ({ request, ServiceName }) => {
-    return <Page />;
-});
+Router.page('/path', ({ request, Feature }) => <Page />);
 ```
 
 ```typescript
-Router.page('/path', ({ ServiceName }) => ({
+Router.page('/path', ({ Feature }) => ({
     _auth: 'USER',
-    dataKey: ServiceName.MethodName({ param1: 'value' }),
-}), ({ request, dataKey, ServiceName }) => {
-    return <Page data={dataKey} />;
-});
+    dataKey: Feature.loadData({ param1: 'value' }),
+}), ({ request, dataKey, Feature }) => <Page data={dataKey} />);
 ```
 
+- Keep the `Router.page(...)` call itself compact instead of expanding each argument onto its own outer line.
 - `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
+- Prefer the generated page arguments or the app context hook; do not import `.proteum` files directly.
 - Never use `api.fetch(...)` in page files
 - Never import client service values from `@app`
+- Compose page UI from shared Shadcn-based components when the project already provides them instead of redefining common controls inline in the page file
+- Keep page-local curated copy, option sets, and registries in `/client/catalogs/**`; do not create `catalogs/` folders under `client/pages/**`
 
 ## Typings
 

package/agents/{codex → project}/server/routes/AGENTS.md

@@ -2,8 +2,9 @@
 
 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`
+- Callable app APIs belong in `/server/controllers/**/*.ts`
 - `/server/routes/**` is for manual `Router.get/post/...` routes, redirects, resources, OAuth callbacks, etc.
+- If a route needs a curated list or registry, keep server-only data in `/server/catalogs/**` and shared data in `/common/catalogs/**`
 
 ## Generate absolute urls
 

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

@@ -0,0 +1,170 @@
+# Server Services
+
+Stack:
+- Typescript with strict mode
+- NodeJS
+- Prisma 7 ORM
+
+## Catalog placement
+
+- Server-only catalogs and registries live in `/server/catalogs/**`
+- Shared cross-runtime catalogs live in `/common/catalogs/**`
+- Do not create nested `catalogs/` folders under `/server/services/**`
+- Services should import curated lists from those root catalog locations instead of redefining them locally
+
+## 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 = Record<string, never>;
+
+/*----------------------------------
+- SERVICE
+----------------------------------*/
+
+export default class ServiceName extends Service<Config, {}, AppType, ParentServiceType> {
+
+    public async methodName(data: { param1: string }) {
+        return this.services.OtherService.otherMethod(data);
+    }
+}
+```
+
+Replace `AppType` and `ParentServiceType` with the local app types used by neighboring services.
+If the service receives config from a project config file, replace `Config` with the real config shape and expose a typed
+config export with `Services.config(ServiceName, { ... })` from `server/config/*.ts`.
+
+## 2. Create the controller file in `/server/controllers/...`
+
+Template:
+
+```typescript
+import Controller, { schema } from '@server/app/controller';
+
+const MethodInput = schema.object({
+    param1: schema.string(),
+});
+
+export default class ServiceNameController extends Controller<AppType> {
+
+    public async methodName() {
+        const input = this.input(MethodInput);
+        const currentUser = this.request.auth.check('USER', null);
+
+        return this.services.ServiceName.methodName({
+            ...input,
+            currentUser,
+        });
+    }
+}
+```
+
+Replace `AppType` with the local app type if the surrounding controllers use a generic.
+Place the controller under the path that should drive the public API shape, for example `/server/controllers/ServiceName.ts` or `/server/controllers/ServiceName/subFeature.ts`.
+
+Rules:
+- Only files under `/server/controllers/**/*.ts` 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`
+- Keep controllers thin and push business logic into services
+- Extract auth and request-derived values in the controller and pass explicit typed arguments into services
+
+## 3. Create the service metas file in `/server/services/<service name>/service.json`
+
+```json
+{
+    "id": "<AppIdentifier>/ServiceName",
+    "name": "ServiceName",
+    "parent": "app",
+    "dependences": []
+}
+```
+
+Use the same id namespace and naming convention as neighboring services in the project.
+
+## 4. Add a typed config export in `/server/config/*.ts` and instantiate the service in `/server/index.ts`
+
+```typescript
+// server/config/feature.ts
+import { Services } from '@server/app';
+import ServiceName from '@/server/services/ServiceName';
+
+export const serviceNameConfig = Services.config(ServiceName, {});
+```
+
+```typescript
+// server/index.ts
+import { Application } from '@server/app';
+import ServiceName from '@/server/services/ServiceName';
+import * as featureConfig from '@/server/config/feature';
+
+export default class MyApp extends Application {
+    public ServiceName = new ServiceName(this, featureConfig.serviceNameConfig, this);
+}
+```
+
+Match the existing config-grouping and namespace-import convention in the project instead of inventing a new bootstrap shape.
+
+## 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
+- If a service needs user identity, locale, cookies, or another request-derived value, compute it in the controller and pass only that value
+
+## 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
+- If you need generated runtime Prisma enums or helpers already emitted by Proteum, follow the local `@generated/server/models` import pattern
+- 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
+
+Never silence caught errors. Throw `Anomaly` with enough detail and the original error when needed.

package/agents/{codex → project}/tests/AGENTS.md

@@ -6,3 +6,4 @@
 - 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
+- Reuse root catalog files from `/client/catalogs/**`, `/server/catalogs/**`, or `/common/catalogs/**` instead of duplicating catalog constants inside tests

package/cli/app/config.ts

@@ -16,6 +16,7 @@ import yaml from 'yaml';
 
 // Types
 import type { TEnvConfig } from '../../server/app/container/config';
+import { logVerbose } from '../runtime/verbose';
 
 /*----------------------------------
 - LOADE
@@ -28,7 +29,7 @@ export default class ConfigParser {
     ) {}
 
     private loadYaml(filepath: string) {
-        console.info(`Loading config ${filepath}`);
+        logVerbose(`Loading config ${filepath}`);
         const rawConfig = fs.readFileSync(filepath, 'utf-8');
         return yaml.parse(rawConfig);
     }
@@ -36,7 +37,7 @@ 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);
+        logVerbose('[app] Using environment:', process.env.NODE_ENV);
         const envFileName = this.appDir + '/env.yaml';
         const envFile = this.loadYaml(envFileName);
         return {

package/cli/app/index.ts

@@ -20,12 +20,6 @@ import type { TEnvConfig } from '../../server/app/container/config';
 
 export type TAppSide = 'server' | 'client';
 
-type TServiceSetup = { id: string; name: string; config: {}; subservices: TServiceSubservices; type: 'service.setup' };
-
-type TServiceRef = { refTo: string; type: 'service.ref' };
-
-type TServiceSubservices = { [key: string]: TServiceSetup | TServiceRef };
-
 const parseRouterPortOverride = (rawPort: string | boolean | string[] | undefined): number | undefined => {
     if (rawPort === undefined || rawPort === '') return undefined;
 
@@ -65,13 +59,14 @@ export class App {
         public: path.join(cli.paths.appRoot, 'public'),
         pages: path.join(cli.paths.appRoot, 'client', 'pages'),
         cache: path.join(cli.paths.appRoot, '.cache'),
+        proteum: path.join(cli.paths.appRoot, '.proteum'),
 
-        client: { generated: path.join(cli.paths.appRoot, 'client', '.generated') },
+        client: { generated: path.join(cli.paths.appRoot, '.proteum', 'client') },
         server: {
-            generated: path.join(cli.paths.appRoot, 'server', '.generated'),
-            configs: path.join(cli.paths.appRoot, 'server', 'app'),
+            entry: path.join(cli.paths.appRoot, 'server', 'index.ts'),
+            generated: path.join(cli.paths.appRoot, '.proteum', 'server'),
         },
-        common: { generated: path.join(cli.paths.appRoot, 'common', '.generated') },
+        common: { generated: path.join(cli.paths.appRoot, '.proteum', 'common') },
 
         withAlias: (filename: string, side: TAppSide) => this.aliases[side].apply(filename),
 
@@ -122,63 +117,8 @@ export class App {
         return fs.readJSONSync(this.paths.root + '/package.json');
     }
 
-    /*----------------------------------
-    - WARMUP (Services awareness)
-    ----------------------------------*/
-
-    public registered = {};
-
-    public use(referenceName: string): TServiceRef {
-        // We don't check because all service are not regstered when we register subservices
-        /*if (this.registered[referenceName] === undefined) {
-            throw new Error(`Service ${referenceName} is not registered`);
-        }*/
-
-        return { refTo: referenceName, type: 'service.ref' };
-    }
-
-    public setup(
-        ...args:
-            | [
-                  // { user: app.setup('Core/User') }
-                  servicePath: string,
-                  serviceConfig?: {},
-              ]
-            | [
-                  // app.setup('User', 'Core/User')
-                  serviceName: string,
-                  servicePath: string,
-                  serviceConfig?: {},
-              ]
-    ): TServiceSetup {
-        // Registration to app root
-        if (typeof args[1] === 'string') {
-            const [name, id, config] = args;
-
-            const service = { id, name, config, type: 'service.setup' } as TServiceSetup;
-
-            this.registered[name] = service;
-
-            return service;
-
-            // Scoped to a parent service
-        } else {
-            const [id, config] = args;
-
-            const service = { id, config, type: 'service.setup' } as TServiceSetup;
-
-            return service;
-        }
-    }
-
     public async warmup() {
-        // Require all config files in @/server/config
-        const configDir = path.resolve(cli.paths.appRoot, 'server', 'config');
-        const configFiles = fs.readdirSync(configDir);
-        for (const configFile of configFiles) {
-            console.log('Loading config file:', configFile);
-            require(path.resolve(configDir, configFile));
-        }
+        return Promise.resolve();
     }
 }
 

package/cli/bin.js

@@ -21,7 +21,7 @@ const path = require('path');
 if (!process.env.TS_NODE_IGNORE) {
     process.env.TS_NODE_IGNORE = [
         // Default ts-node ignore rule (works when deps are nested under `../node_modules/...`)
-        '(node_modules\/(?!proteum\/))|(\.generated\/)|(\.cache\/)',
+        '(node_modules\/(?!proteum\/))|(\.generated\/)|(\.cache\/)|(\.proteum\/)',
         // Extra rule for deps hoisted next to Proteum (ex: `../../tailwindcss/...`)
         '^\\.\\./\\.\\./(?!\\./|\\.\\./)[^/]+/',
     ].join(',');
@@ -32,4 +32,9 @@ process.env.TS_NODE_TRANSPILE_ONLY = '1';
 
 require('ts-node/register/transpile-only');
 
-require('./index.ts');
+const { runCli } = require('./index.ts');
+
+Promise.resolve(runCli()).catch((error) => {
+    console.error(error);
+    process.exit(1);
+});