@finesoft/front 0.1.75 → 0.1.77

package/docs/engineering/project-structure.md

@@ -0,0 +1,296 @@
+# Engineering: project structure
+
+Recommended layout for apps past the scaffolded starter. The shape that works for ~20 routes and ~10 engineers without major reorganization.
+
+## Layout
+
+```
+my-app/
+├── src/
+│   ├── bootstrap.ts             # routes + DI setup (shared SSR + CSR)
+│   ├── main.ts                  # browser entry
+│   ├── ssr.ts                   # SSR entry
+│   ├── App.vue                  # root component
+│   │
+│   ├── routes/                  # route definitions, grouped by domain
+│   │   ├── home.ts
+│   │   ├── product.ts
+│   │   ├── checkout.ts
+│   │   └── admin.ts
+│   │
+│   ├── controllers/             # controllers, one file per intent
+│   │   ├── home.ts
+│   │   ├── product.ts
+│   │   └── checkout.ts
+│   │
+│   ├── views/                   # view components, mirror controllers
+│   │   ├── Home.vue
+│   │   ├── Product.vue
+│   │   └── Checkout.vue
+│   │
+│   ├── lib/
+│   │   ├── api/                 # HttpClient subclasses
+│   │   │   ├── user.ts
+│   │   │   └── product.ts
+│   │   ├── guards/              # reusable middleware
+│   │   │   ├── auth.ts
+│   │   │   ├── locale.ts
+│   │   │   └── analytics.ts
+│   │   ├── di/
+│   │   │   ├── keys.ts          # APP_KEYS const map
+│   │   │   └── register.ts      # central registration
+│   │   ├── i18n/
+│   │   │   └── translator.ts    # Translator factory
+│   │   └── pages/
+│   │       └── types.ts         # Page union type
+│   │
+│   ├── locales/
+│   │   ├── en-US.json
+│   │   ├── zh-Hans.json
+│   │   └── ja-JP.json
+│   │
+│   └── env.ts                   # env var parsing + validation
+│
+├── public/                      # static assets, served at /
+├── index.html
+├── vite.config.ts
+├── package.json
+└── tsconfig.json
+```
+
+## Why this shape
+
+### `routes/` separate from `controllers/`
+
+A route is **where** an intent is exposed (URL pattern, guards, render mode). A controller is **what** an intent does. Splitting them lets you:
+
+- Reuse a controller across multiple URLs without route definitions cluttering its file
+- Find "what URLs does my app serve" by reading one folder
+- Find "what does intent X compute" by reading one folder
+
+### `controllers/` mirrors `views/`
+
+One file per intent on both sides. The intent id, controller file, and view file share the same name. Finding the rendering code for `/products/:id` becomes mechanical.
+
+### `lib/` for everything cross-cutting
+
+Anything that isn't a route, controller, or view. The framework's `bootstrap()` reaches into `lib/di/register.ts` for the heavy registration; controllers reach into `lib/api/*` for clients; guards live in `lib/guards/`.
+
+### `env.ts` at the top of `src/`
+
+Parse and validate environment variables once, in one file. Use [zod](https://zod.dev/) or hand-rolled checks. Re-export typed constants everywhere else.
+
+```ts
+// src/env.ts
+function requireEnv(name: string): string {
+    const v = process.env[name];
+    if (!v) throw new Error(`Missing env: ${name}`);
+    return v;
+}
+
+export const env = {
+    UPSTREAM_URL: requireEnv("UPSTREAM_URL"),
+    SESSION_SECRET: requireEnv("SESSION_SECRET"),
+    NODE_ENV: process.env.NODE_ENV ?? "development",
+} as const;
+```
+
+This makes "what env vars does this app need" trivially discoverable, and the build fails fast on missing values instead of crashing at request time.
+
+## `bootstrap.ts` shape
+
+Keep `bootstrap.ts` thin — it should orchestrate, not contain logic:
+
+```ts
+// src/bootstrap.ts
+import { type Framework } from "@finesoft/front";
+import { registerDependencies } from "./lib/di/register";
+import { homeRoutes } from "./routes/home";
+import { productRoutes } from "./routes/product";
+import { checkoutRoutes } from "./routes/checkout";
+import { adminRoutes } from "./routes/admin";
+
+export function bootstrap(framework: Framework): void {
+    registerDependencies(framework.container);
+
+    homeRoutes(framework);
+    productRoutes(framework);
+    checkoutRoutes(framework);
+    adminRoutes(framework);
+}
+```
+
+Each `*Routes` function calls `defineRoutes(framework, [...])` with its own routes. Adding a new route group is one import + one call.
+
+## Per-domain route file
+
+```ts
+// src/routes/product.ts
+import { defineRoutes, type Framework } from "@finesoft/front";
+import { ProductController } from "../controllers/product";
+import { ProductListController } from "../controllers/product-list";
+import { authGuard } from "../lib/guards/auth";
+
+export function productRoutes(framework: Framework): void {
+    defineRoutes(framework, [
+        { path: "/products", intentId: "product-list", controller: new ProductListController() },
+        { path: "/products/:id", intentId: "product", controller: new ProductController() },
+        {
+            path: "/products/:id/edit",
+            intentId: "product-edit",
+            controller: new ProductEditController(),
+            beforeLoad: [authGuard],
+            renderMode: "csr",
+        },
+    ]);
+}
+```
+
+## Central DI registration
+
+```ts
+// src/lib/di/register.ts
+import { type Container, DEP_KEYS } from "@finesoft/front";
+import { APP_KEYS } from "./keys";
+import { UserApi } from "../api/user";
+import { ProductApi } from "../api/product";
+import { ConsoleLogger } from "@finesoft/front";
+import { env } from "../../env";
+
+export function registerDependencies(container: Container): void {
+    container.register(DEP_KEYS.LOGGER, () => new ConsoleLogger("app"));
+
+    container.register(
+        APP_KEYS.USER_API,
+        () =>
+            new UserApi({
+                baseUrl: env.UPSTREAM_URL,
+            }),
+    );
+    container.register(
+        APP_KEYS.PRODUCT_API,
+        () =>
+            new ProductApi({
+                baseUrl: env.UPSTREAM_URL,
+            }),
+    );
+}
+```
+
+Centralizing keeps the wiring inspectable. Adding a service is a single edit, not a search across the project.
+
+## Typed DI keys
+
+```ts
+// src/lib/di/keys.ts
+export const APP_KEYS = {
+    USER_API: "userApi",
+    PRODUCT_API: "productApi",
+    SESSION: "session",
+    FEATURE_BUCKETING: "featureBucketing",
+} as const;
+
+export type AppKey = (typeof APP_KEYS)[keyof typeof APP_KEYS];
+```
+
+Then in any controller:
+
+```ts
+import { APP_KEYS } from "../lib/di/keys";
+
+async execute(params, container) {
+    const api = container.resolve<UserApi>(APP_KEYS.USER_API);
+    // ...
+}
+```
+
+A typo in `APP_KEYS.USER_PAI` is a compile error. A typo in `"userPai"` is a runtime error.
+
+## Page type union
+
+```ts
+// src/lib/pages/types.ts
+import type { HomePage } from "../../controllers/home";
+import type { ProductPage } from "../../controllers/product";
+import type { CheckoutPage } from "../../controllers/checkout";
+import type { ErrorPage } from "./error";
+
+export type Page = HomePage | ProductPage | CheckoutPage | ErrorPage;
+```
+
+Use a discriminated union with a `kind` field. The view layer's root component switches on `page.kind`:
+
+```vue
+<script setup lang="ts">
+import type { Page } from "@/lib/pages/types";
+const props = defineProps<{ page: Page }>();
+</script>
+
+<template>
+    <Home v-if="page.kind === 'home'" :page="page" />
+    <Product v-else-if="page.kind === 'product'" :page="page" />
+    <Checkout v-else-if="page.kind === 'checkout'" :page="page" />
+    <Error v-else-if="page.kind === 'error'" :page="page" />
+</template>
+```
+
+The discriminant narrows the type inside each branch — view components get a fully typed `page` prop without casts.
+
+## Splitting the SSR and browser entries
+
+Keep `ssr.ts` and `main.ts` thin. They differ only in:
+
+- `ssr.ts` calls `createSSRRender` and exports `render` + `serializeServerData`
+- `main.ts` calls `startBrowserApp` and mounts the view layer
+
+Everything else — routes, controllers, DI, i18n — is shared via `bootstrap.ts`.
+
+```ts
+// src/ssr.ts
+import { createSSRRender, serializeServerData } from "@finesoft/front";
+import { renderToString } from "vue/server-renderer";
+import { createSSRApp } from "vue";
+import App from "./App.vue";
+import { bootstrap } from "./bootstrap";
+
+export const render = createSSRRender({
+    bootstrap,
+    getErrorPage: () => ({ kind: "error", title: "Server error" }),
+    async renderApp(page) {
+        const html = await renderToString(createSSRApp(App, { page }));
+        return { html, head: `<title>${page.title}</title>`, css: "" };
+    },
+});
+
+export { serializeServerData };
+```
+
+```ts
+// src/main.ts
+import { startBrowserApp } from "@finesoft/front/browser";
+import { createSSRApp } from "vue";
+import App from "./App.vue";
+import { bootstrap } from "./bootstrap";
+
+startBrowserApp({
+    bootstrap,
+    mount(target, { framework }) {
+        createSSRApp(App, { framework }).mount(target);
+    },
+});
+```
+
+## When to break this layout
+
+The shape above works through ~50 routes. Past that, consider:
+
+- **Per-feature folders** (`src/features/checkout/{routes,controllers,views,api}.ts`) for very large apps. Each feature is independently understandable.
+- **Lazy-loaded route bundles** with `import()` inside the route definition. The Vite plugin splits them automatically.
+- **Workspace packages** if multiple apps share the same controllers / API clients. Move shared code to `packages/shared` and import from there.
+
+Don't pre-emptively reorganize. The flat `routes/` + `controllers/` shape is fine well into the hundreds of files.
+
+## See also
+
+- [Engineering: testing](./testing.md) — how to test against this structure
+- [DI container](../07-di-container.md) — registration patterns

package/docs/engineering/testing.md

@@ -0,0 +1,317 @@
+# Engineering: testing
+
+The framework is built to be tested. Routes, controllers, and middleware all run through the same dispatch path on server and browser, so a single test exercises both worlds.
+
+## What to test
+
+| Subject        | What to assert                                                                                   | Layer       |
+| -------------- | ------------------------------------------------------------------------------------------------ | ----------- |
+| Controllers    | Given params + scoped container, the page produced is correct.                                   | unit        |
+| Guards         | Given a `NavigationContext`, the result is `next` / `redirect` / `rewrite` / `deny` as expected. | unit        |
+| Routes         | URL → expected intent + render mode.                                                             | unit        |
+| Full request   | URL → final HTML / status code through the full pipeline.                                        | integration |
+| Proxy / server | Hono routes return the right responses for synthetic requests.                                   | integration |
+
+## Vitest setup
+
+The repo uses Vite+. Always import from `vite-plus/test`:
+
+```ts
+import { describe, expect, test, vi, beforeEach, afterEach } from "vite-plus/test";
+```
+
+Run tests with:
+
+```bash
+vp test                     # all
+vp test path/to/file.test.ts # one file
+vp test -t "name match"     # filter by test name
+vp test --coverage          # with coverage
+```
+
+## Testing a controller
+
+```ts
+// src/controllers/product.test.ts
+import { afterEach, describe, expect, test, vi } from "vite-plus/test";
+import { Container } from "@finesoft/front";
+import { ProductController } from "./product";
+
+describe("ProductController", () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    test("returns product page on success", async () => {
+        const container = new Container();
+        container.register("productApi", () => ({
+            getById: vi.fn(async (id) => ({ name: "Widget", price: 9.99 })),
+        }));
+
+        const controller = new ProductController();
+        const page = await controller.execute({ id: "42" }, container);
+
+        expect(page).toEqual({
+            kind: "product",
+            id: "42",
+            name: "Widget",
+            price: 9.99,
+        });
+    });
+
+    test("fallback returns degraded page on api failure", () => {
+        const controller = new ProductController();
+        const page = controller.fallback({ id: "42" }, new Error("network down"));
+
+        expect(page).toMatchObject({
+            kind: "product",
+            id: "42",
+            name: "Not available",
+        });
+    });
+});
+```
+
+Key idea: **build a `Container` per test, register only what the controller needs.** Don't pull in a real `Framework` — you'd be testing the framework, not your controller.
+
+## Testing a guard
+
+Guards take a `NavigationContext` and return a `MiddlewareResult`. Build a fake context inline:
+
+```ts
+import { afterEach, describe, expect, test, vi } from "vite-plus/test";
+import { Container } from "@finesoft/front";
+import { authGuard } from "./auth";
+
+function makeCtx(overrides: Partial<{ cookie: string | null }> = {}) {
+    return {
+        url: new URL("http://app.test/admin"),
+        intent: { intentId: "admin", params: {} },
+        container: new Container(),
+        getCookie: vi.fn((name: string) => overrides.cookie ?? null),
+        getHeader: vi.fn(() => null),
+        isSsr: true,
+    };
+}
+
+describe("authGuard", () => {
+    test("redirects unauthenticated user to /login", () => {
+        const ctx = makeCtx({ cookie: null });
+        const result = authGuard(ctx);
+
+        expect(result).toEqual({
+            kind: "redirect",
+            url: "/login?next=%2Fadmin",
+            status: 302,
+        });
+    });
+
+    test("passes through when token is present", () => {
+        const ctx = makeCtx({ cookie: "valid-token" });
+        const result = authGuard(ctx);
+
+        expect(result).toEqual({ kind: "next" });
+    });
+});
+```
+
+The factory function (`makeCtx`) is the pattern — keep it co-located with the guard, parameterize the bits the test actually cares about.
+
+## Testing routes
+
+To assert URL → intent mapping:
+
+```ts
+import { describe, expect, test } from "vite-plus/test";
+import { Framework } from "@finesoft/front";
+import { bootstrap } from "./bootstrap";
+
+describe("routes", () => {
+    test("resolves /products/42 to product intent", () => {
+        const framework = Framework.create({});
+        bootstrap(framework);
+
+        const match = framework.router.resolve("/products/42");
+
+        expect(match).toMatchObject({
+            intent: { intentId: "product", params: { id: "42" } },
+            renderMode: "ssr",
+        });
+    });
+
+    test("returns null for unmatched URL", () => {
+        const framework = Framework.create({});
+        bootstrap(framework);
+
+        expect(framework.router.resolve("/does-not-exist")).toBeNull();
+    });
+});
+```
+
+This catches route regressions during refactors — a renamed intent shows up as a failing test, not a 404 in production.
+
+## Testing the full request pipeline
+
+For SSR end-to-end tests, exercise `createSSRRender`:
+
+```ts
+import { describe, expect, test } from "vite-plus/test";
+import { createSSRRender } from "@finesoft/front";
+import { bootstrap } from "./bootstrap";
+
+describe("SSR pipeline", () => {
+    test("renders home page with serialized data", async () => {
+        const render = createSSRRender({
+            bootstrap,
+            getErrorPage: () => ({ kind: "error", title: "Error" }),
+            async renderApp(page) {
+                return {
+                    html: `<main>${(page as any).title}</main>`,
+                    head: "",
+                    css: "",
+                };
+            },
+        });
+
+        const result = await render("/", {
+            template: `<!doctype html><html><head><!--head--></head><body><!--ssr--></body></html>`,
+        });
+
+        expect(result.status).toBe(200);
+        expect(result.html).toContain("<main>Welcome</main>");
+        expect(result.html).toContain('id="__finesoft_data__"');
+    });
+
+    test("returns 302 when guard redirects", async () => {
+        const render = createSSRRender({
+            /* ... */
+        });
+        const result = await render("/admin");
+
+        expect(result.status).toBe(302);
+        expect(result.redirectUrl).toBe("/login?next=%2Fadmin");
+    });
+});
+```
+
+This is the highest-value test layer — it exercises routing, middleware, controllers, and rendering together.
+
+## Mocking the network
+
+`HttpClient` uses `fetch` directly. Stub it via `vi.stubGlobal`:
+
+```ts
+import { afterEach, beforeEach, test, vi, expect } from "vite-plus/test";
+
+let fetchMock: ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+    fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+});
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+});
+
+test("UserApi.list parses JSON response", async () => {
+    fetchMock.mockResolvedValueOnce(
+        new Response(JSON.stringify([{ id: "1", name: "Alice" }]), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+        }),
+    );
+
+    const api = new UserApi({ baseUrl: "/api" });
+    const users = await api.list();
+
+    expect(users).toEqual([{ id: "1", name: "Alice" }]);
+    expect(fetchMock).toHaveBeenCalledWith("/api/users", expect.any(Object));
+});
+```
+
+For tests with many fetches, build a small registry:
+
+```ts
+function setupFetch(routes: Record<string, () => Response>) {
+    fetchMock.mockImplementation(async (url: string) => {
+        const handler = routes[url];
+        if (!handler) throw new Error(`Unexpected fetch: ${url}`);
+        return handler();
+    });
+}
+
+setupFetch({
+    "/api/users": () => new Response(JSON.stringify(users), { status: 200 }),
+    "/api/products": () => new Response(JSON.stringify(products), { status: 200 }),
+});
+```
+
+This makes "what does my test expect to be fetched" readable at a glance.
+
+## Disposing scopes in tests
+
+If your test creates a scope, dispose it in `afterEach`:
+
+```ts
+let scope: Container | null = null;
+
+afterEach(() => {
+    scope?.dispose();
+    scope = null;
+});
+
+test("...", () => {
+    scope = framework.container.createScope();
+    scope.register("api", () => mockApi);
+    // ...
+});
+```
+
+Vitest isolates tests by default, but disposing exposes leaks if the scope had `destroy()`-able resources (recorders, etc.).
+
+## Testing middleware with `rewrite`
+
+`rewrite` in `beforeLoad` recurses through the router. Test both the rewrite signal and the resolved final route:
+
+```ts
+test("legacy URL rewrites to canonical", async () => {
+    const render = createSSRRender({ bootstrap /* ... */ });
+    const result = await render("/old/products/42");
+
+    // The user-visible URL stays unchanged
+    expect(result.status).toBe(200);
+
+    // But the rendered controller was for /products/42 — assert via the rendered HTML
+    expect(result.html).toContain("Widget"); // product 42's name
+});
+```
+
+For `afterLoad` rewrites (canonicalization), assert the `Content-Location` header:
+
+```ts
+const result = await render("/page?utm=x");
+expect(result.headers["Content-Location"]).toBe("/page");
+```
+
+## Coverage targets
+
+The framework itself targets >95% on `core` and >85% on `server`. For application code, aim for:
+
+- **Controllers**: 100% of `execute()` happy paths + at least one `fallback()` test.
+- **Guards**: every branch (pass / redirect / deny).
+- **Routes**: at least one assertion per route group that the URLs resolve as expected.
+
+Don't chase 100% on view components — those test the view layer, not the framework. Test the page-shape contracts the controllers produce instead.
+
+## Speed
+
+Vitest with vite-plus is fast — ~1ms per test for unit, ~10ms for integration. If you see slower:
+
+- Avoid creating a full `Framework` in tight loops; build a `Container` directly.
+- Mock heavy `bootstrap()` calls in unit tests.
+- Use `vi.useFakeTimers()` for tests that wait on `setTimeout` (retry logic, debouncing).
+
+## See also
+
+- [Testing the proxy](../09-server-and-deployment.md#proxy-routes) — the framework's own tests at `packages/server/test/proxy.test.ts` are good references