proteum 2.0.0-1 → 2.1.0

package/AGENTS.md

@@ -16,11 +16,13 @@ When tradeoffs exist, prioritize framework decisions in this order:
 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.
+- Enforce strong, consistent TypeScript typings across the whole project. Do not introduce `any` or `unknown`.
 - 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 inference from the explicit application class in `server/index.ts` whenever possible. Treat `server/index.ts` as the canonical type root for application services, router services, router context, and models instead of duplicating manual type declarations.
 - 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.
@@ -54,14 +56,23 @@ When changing Proteum itself, always ground the work in the real apps that use i
 
 Future changes should preserve and extend the current explicit model instead of reintroducing runtime magic.
 
-- Server route entrypoints live in `*.controller.ts` files.
+- Strong typings are mandatory across the whole project. Do not use `any` or `unknown`; keep types explicit, precise, and consistent.
+- Prefer deriving types from the explicit application class in `server/index.ts` instead of recreating them manually in feature code, helpers, or generated output.
+- Server route entrypoints live in `server/controllers/**/*.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.
+- `server/config/*.ts` should export plain typed config constants with `Services.config(ServiceClass, { ... })`, for example `export const missionsConfig = Services.config(Missions, { ... })`.
+- `server/index.ts` should default-export the app `Application` subclass and instantiate root services as public fields via `new ServiceClass(this, config, this)`.
 - Normal services extend `Service` and should use `this.services`, `this.models`, and `this.app` instead of implicit globals or magic imports.
+- App services should be inferred from the explicit `server/index.ts` application graph and the config passed into each constructor, not hand-maintained parallel interfaces.
+- Router services and router/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 generated app types, not from duplicated hand-written model maps.
+- Controllers should own auth, input parsing, and request concerns, then pass explicit typed values into services.
 - 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.
+- 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`, or `this.app.Models.client`, then call methods on that local binding. The service, router value, or model should be the first element of the callee chain.
 
 ## Solution Proposals
 
@@ -82,6 +93,7 @@ When presenting a framework solution, make it easy to judge against the real app
 - 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.
+- Prefer local destructuring that exposes typed app services, router services, router context values, and models in the current block scope before use, instead of chaining through `this.request`, `this.app`, or `this.app.Models.client` at each call site.
 - 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.

package/README.md

@@ -0,0 +1,375 @@
+# Proteum
+
+Proteum is an LLM-first SSR / SEO / TypeScript framework for full-stack web applications.
+
+It is built for teams that want explicit server contracts, server-first rendering, deterministic generated artifacts, and a codebase that an AI agent can inspect without reverse-engineering hidden runtime magic.
+
+## Why Proteum
+
+Most full-stack frameworks optimize first for human convenience.
+
+Proteum optimizes first for:
+
+- explicit, typed, machine-readable contracts
+- SSR and SEO as framework primitives
+- server-first architecture with minimal client runtime
+- deterministic generation instead of ambient magic
+- codebases that stay explainable to humans and LLMs at the same time
+
+Proteum combines:
+
+- page-first SSR workflows similar to modern React meta-frameworks
+- explicit controller and service layers inspired by backend frameworks
+- generated manifests and contracts that make routes, services, layouts, and diagnostics easy to inspect
+
+## Core Principles
+
+- **Server-first by default.** Put data loading in the page setup function and keep client code focused on UI.
+- **Explicit request entrypoints.** Controllers are classes. Request access is explicit through `this.request`.
+- **Local validation.** Validate handler input inside the handler with `this.input(schema)`.
+- **Deterministic generation.** Proteum owns `.proteum/` and regenerates it from source.
+- **Explainability matters.** `proteum explain` and `proteum doctor` expose the framework view of your app.
+- **SEO is not an afterthought.** Identity, routes, layouts, and SSR data are part of the app contract.
+
+## What a Proteum App Looks Like
+
+```text
+my-app/
+  identity.yaml
+  env.yaml
+  package.json
+  client/
+    pages/
+      _layout/
+    components/
+    islands/
+    services/
+  server/
+    config/
+    index.ts
+    controllers/
+    services/
+  common/
+    models/
+    router/
+    errors/
+  .proteum/
+    manifest.json
+    client/
+    common/
+    server/
+```
+
+Important files:
+
+- `identity.yaml`: app identity, naming, locale, and SEO-facing metadata defaults
+- `env.yaml`: environment contract loaded by the app
+- `server/config/*.ts`: plain typed config exports consumed by the explicit app bootstrap
+- `server/index.ts`: default-exported `Application` subclass that instantiates root services and router plugins
+- `client/pages/**`: SSR page entrypoints registered through `Router.page(...)`
+- `server/controllers/**`: request handlers that extend `Controller`
+- `server/services/**`: business logic that extends `Service`
+- `.proteum/**`: framework-owned generated contracts and manifests
+
+## Example: Server Bootstrap
+
+Proteum app services are declared explicitly through typed config exports plus a concrete `Application` subclass.
+
+```ts
+// server/config/user.ts
+import { Services, type ServiceConfig } from '@server/app';
+import AppContainer from '@server/app/container';
+import Router from '@server/services/router';
+import Users from '@/server/services/Users';
+
+type RouterBaseConfig = Omit<ServiceConfig<typeof Router>, 'plugins'>;
+
+export const usersConfig = Services.config(Users, {});
+
+export const routerBaseConfig = {
+  domains: AppContainer.Environment.router.domains,
+  http: {
+    domain: 'example.com',
+    port: AppContainer.Environment.router.port,
+    ssl: true,
+    upload: { maxSize: '10mb' },
+  },
+  context: () => ({}),
+} satisfies RouterBaseConfig;
+```
+
+```ts
+// server/index.ts
+import { Application } from '@server/app';
+import Router from '@server/services/router';
+import SchemaRouter from '@server/services/schema/router';
+import Users from '@/server/services/Users';
+import * as userConfig from '@/server/config/user';
+
+export default class MyApp extends Application {
+  public Users = new Users(this, userConfig.usersConfig, this);
+  public Router = new Router(
+    this,
+    {
+      ...userConfig.routerBaseConfig,
+      plugins: {
+        schema: new SchemaRouter({}, this),
+      },
+    },
+    this
+  );
+}
+```
+
+Proteum reads `server/index.ts` plus `server/services/**/service.json` to derive the installed service graph and generated type contracts.
+
+## Example: Page
+
+Proteum pages are explicit SSR entrypoints.
+
+```tsx
+import Router from '@/client/router';
+
+Router.page(
+  '/',
+  ({ Plans, Stats }) => ({
+    _auth: false,
+    _layout: false,
+    plans: Plans.getPlans(),
+    stats: Stats.general(),
+  }),
+  ({ plans, stats }) => {
+    return <LandingPage plans={plans} stats={stats} />;
+  }
+);
+```
+
+What happens here:
+
+- the first argument is the route path
+- the optional setup function runs on the server for SSR data loading
+- keys prefixed with `_` become route options such as `_auth`, `_layout`, `_static`, or `_redirectLogged`
+- every other returned key becomes page data
+- the renderer receives the resolved data and the generated controller/service context
+
+## Example: Controller
+
+Proteum controllers are explicit request entrypoints.
+
+```ts
+import Controller, { schema } from '@server/app/controller';
+
+export default class AuthController extends Controller<MyApp> {
+  public async loginWithPassword() {
+    const { Auth } = this.services;
+    const data = this.input(
+      schema.object({
+        email: schema.string().email(),
+        password: schema.string().min(8),
+      })
+    );
+
+    return Auth.loginWithPassword(data, this.request);
+  }
+}
+```
+
+Controller rules:
+
+- read request-scoped values from `this.request`
+- validate once with `this.input(schema)`
+- call business logic through `this.services`, `this.models`, or `this.app`
+- return explicit values instead of relying on ambient globals
+
+## Example: Service
+
+Proteum services keep business logic out of request handlers.
+
+```ts
+import Service from '@server/app/service';
+
+export default class StatsService extends Service<Config, {}, MyApp, MyApp> {
+  public async general() {
+    return {
+      totalDomains: await this.models.SQL`SELECT COUNT(*) FROM domains`.value(),
+      tlds: Object.keys(this.app.Domains.tlds).length,
+    };
+  }
+}
+```
+
+Service rules:
+
+- services extend `Service`
+- request context should be resolved in controllers, then passed into services as explicit values
+- services can use `this.services`, `this.models`, and `this.app`
+
+## Framework-Owned Generated Contracts
+
+Proteum generates a machine-readable app description in `.proteum/`.
+
+Typical generated artifacts:
+
+- `.proteum/manifest.json`
+- `.proteum/client/routes.ts`
+- `.proteum/client/controllers.ts`
+- `.proteum/client/layouts.ts`
+- `.proteum/common/controllers.ts`
+- `.proteum/server/routes.ts`
+- `.proteum/server/controllers.ts`
+
+These files are not hand-written application code. They are deterministic outputs derived from your app source and used by the runtime, the compiler, and tooling.
+
+This is one of Proteum's most important properties: the framework can explain what it discovered instead of asking you to guess.
+
+## CLI
+
+Proteum ships with a compact CLI focused on the real app lifecycle:
+
+| Command | Purpose |
+| --- | --- |
+| `proteum dev` | Start the compiler, SSR server, and hot reload loop |
+| `proteum refresh` | Regenerate `.proteum` contracts and typings |
+| `proteum typecheck` | Refresh generated typings, then run TypeScript |
+| `proteum lint` | Run ESLint for the current app |
+| `proteum check` | Refresh, typecheck, and lint in one command |
+| `proteum build --prod` | Produce the production server and client bundles into `bin/` |
+| `proteum doctor` | Inspect manifest diagnostics |
+| `proteum explain` | Explain routes, controllers, services, layouts, conventions, and env |
+| `proteum init` | Experimental project scaffolding when scaffold assets are installed |
+
+Recommended daily workflow:
+
+```bash
+proteum dev
+proteum refresh
+proteum check
+proteum build --prod
+```
+
+Useful inspection commands:
+
+```bash
+proteum doctor
+proteum doctor --json
+proteum explain
+proteum explain --routes --controllers
+proteum explain --all --json
+```
+
+## LLM-Friendly By Design
+
+Proteum is built so an agent can answer these questions quickly and reliably:
+
+- What is this app called, and what are its SEO defaults?
+- Which routes exist?
+- Which controller handles a request?
+- Which services are installed?
+- Which layouts exist?
+- Which diagnostics did the framework detect?
+
+Proteum answers those questions with explicit artifacts:
+
+- `identity.yaml` for app identity
+- `env.yaml` for the environment surface
+- `server/index.ts` for the explicit root service graph
+- `.proteum/manifest.json` for machine-readable app structure
+- `proteum explain --json` for structured framework introspection
+- `proteum doctor --json` for structured diagnostics
+
+If you are an LLM or automation agent, start here:
+
+1. Read `identity.yaml`.
+2. Read `env.yaml`.
+3. Inspect `server/index.ts` and `server/config/*.ts` for the explicit app bootstrap.
+4. Read `.proteum/manifest.json` or run `proteum explain --json`.
+5. Inspect `server/controllers/**` for request entrypoints.
+6. Inspect `server/services/**` for business logic.
+7. Inspect `client/pages/**` for SSR routes and page setup contracts.
+
+## What Proteum Avoids
+
+Proteum intentionally avoids several patterns that make frameworks harder to inspect and harder to trust:
+
+- hidden runtime globals
+- implicit service registration hidden behind bootstrap helpers
+- implicit request state inside business services
+- controller validation defined far away from the handler
+- route systems that cannot be explained without reading the compiler
+- generated code that hides where it came from
+
+## Real-World Shape
+
+Proteum is already used on large application surfaces with:
+
+- many controllers and services
+- SSR landing pages and authenticated app pages
+- generated controller accessors injected into page context
+- build, typecheck, lint, and diagnostic workflows run from the CLI
+
+In real apps, the common `package.json` scripts look like this:
+
+```json
+{
+  "scripts": {
+    "dev": "proteum dev",
+    "refresh": "proteum refresh",
+    "typecheck": "proteum typecheck",
+    "check": "proteum check",
+    "build": "proteum build --prod",
+    "start": "node ./bin/server.js"
+  }
+}
+```
+
+## Installation
+
+Proteum currently targets:
+
+- Node.js `>=20.19.0`
+- npm `>=3.10.10`
+
+Install in an app:
+
+```bash
+npm install proteum
+```
+
+If the scaffold assets are available in your distribution, you can bootstrap a new app with:
+
+```bash
+npx proteum init
+```
+
+Then use the normal workflow:
+
+```bash
+npx proteum dev
+npx proteum check
+npx proteum build --prod
+```
+
+## Repository Structure
+
+This repository is organized around the same explicit framework surface it exposes:
+
+- `cli/`: compiler, commands, diagnostics, and developer workflow
+- `client/`: client runtime, page registration, islands, and router behavior
+- `server/`: controller base classes, services, runtime, and SSR server behavior
+- `common/`: shared router contracts, models, request/response types, and utilities
+- `doc/`: focused design notes and internal documentation
+- `agents/`: agent-specific conventions and scaffolding used in Proteum-based projects
+
+## Status
+
+Proteum is actively hardening its explicit model.
+
+The direction is deliberate:
+
+- less runtime magic
+- more generated and auditable contracts
+- clearer controller and service boundaries
+- better SSR, SEO, and explainability defaults
+- better ergonomics for both humans and AI agents
+
+If you want a framework that treats machine-readable architecture as a first-class feature, Proteum is what this repository is building.