@finesoft/front 0.1.75 → 0.1.77

package/docs/advanced/multi-tenant-scopes.md

@@ -0,0 +1,330 @@
+# Advanced: multi-tenant scopes
+
+A multi-tenant app serves multiple customers from one deployment, but each customer's request must see their own:
+
+- Database connection / API client
+- Logger / metrics tagged with the tenant
+- Feature flags / pricing / branding
+- Cached translations / content
+
+The DI container's child scopes are the right primitive. This recipe shows how to wire per-tenant isolation through a `beforeLoad` guard.
+
+## Mental model
+
+```
+Framework
+  └── parent Container        ← shared services (HTTP pool, base recorder, ...)
+      └── per-request scope   ← framework creates this for every SSR request
+          ↑
+          └── tenant overrides registered by a beforeLoad guard
+```
+
+The per-request scope is created by the framework automatically. Your guard registers tenant-specific overrides on top. Anything you don't override falls through to the parent.
+
+## Step 1: identify the tenant
+
+This is your business logic. Common sources:
+
+- **Subdomain**: `acme.myapp.com` → `acme`
+- **Path prefix**: `/t/acme/...` → `acme`
+- **Header**: `X-Tenant-Id: acme`
+- **Authenticated user**: cookie → session → tenant
+
+```ts
+// src/lib/tenants/resolve.ts
+import type { NavigationContext } from "@finesoft/front";
+
+export function resolveTenant(ctx: NavigationContext): string | null {
+    const host = ctx.url.hostname;
+    const sub = host.split(".")[0];
+    if (sub && sub !== "www" && sub !== "myapp") return sub;
+    return null;
+}
+```
+
+## Step 2: load tenant config
+
+```ts
+// src/lib/tenants/config.ts
+export interface TenantConfig {
+    tenantId: string;
+    displayName: string;
+    upstreamUrl: string;
+    apiToken: string;
+    featureFlags: Record<string, unknown>;
+    locale: string;
+}
+
+const cache = new Map<string, TenantConfig>();
+
+export async function getTenantConfig(tenantId: string): Promise<TenantConfig | null> {
+    if (cache.has(tenantId)) return cache.get(tenantId)!;
+
+    // Load from your config store — file, DB, KV
+    const config = await loadFromStore(tenantId);
+    if (!config) return null;
+
+    cache.set(tenantId, config);
+    return config;
+}
+```
+
+A real implementation would have cache invalidation on config updates. For most apps, refresh on a timer or via a webhook is enough.
+
+## Step 3: register tenant services in a guard
+
+```ts
+// src/lib/guards/tenant.ts
+import { deny, next, type NavigationContext, DEP_KEYS } from "@finesoft/front";
+import { resolveTenant } from "../tenants/resolve";
+import { getTenantConfig } from "../tenants/config";
+import { UserApi } from "../api/user";
+import { WithFieldsRecorder } from "@finesoft/front";
+
+export async function tenantGuard(ctx: NavigationContext) {
+    const tenantId = resolveTenant(ctx);
+    if (!tenantId) return deny(404, "Unknown tenant");
+
+    const config = await getTenantConfig(tenantId);
+    if (!config) return deny(404, "Tenant not found");
+
+    // Register tenant-specific services on the request scope
+    const scope = ctx.container;
+    scope.register("tenantConfig", () => config);
+
+    scope.register(
+        "userApi",
+        () =>
+            new UserApi({
+                baseUrl: config.upstreamUrl,
+                defaultHeaders: { Authorization: `Bearer ${config.apiToken}` },
+            }),
+    );
+
+    scope.register(DEP_KEYS.FEATURE_FLAGS, () => ({
+        get: (key, fallback) => config.featureFlags[key] ?? fallback,
+    }));
+
+    // Decorate the parent's recorder with tenant context
+    const baseRecorder = scope.parent!.resolve(DEP_KEYS.EVENT_RECORDER);
+    scope.register(
+        DEP_KEYS.EVENT_RECORDER,
+        () => new WithFieldsRecorder(baseRecorder, [{ getFields: () => ({ tenantId }) }]),
+    );
+
+    return next();
+}
+```
+
+Key insights:
+
+- **The scope is already created by the framework.** You register on `ctx.container` — that's the request scope.
+- **Fall-through is automatic.** Anything not registered here resolves from the parent container.
+- **Decorate, don't replace.** The recorder is wrapped with tenant fields rather than replaced — base behavior (HTTP transmission, batching) stays in place.
+
+## Step 4: install the guard globally
+
+```ts
+// src/bootstrap.ts
+import { type Framework, defineRoutes } from "@finesoft/front";
+import { tenantGuard } from "./lib/guards/tenant";
+// ... other imports
+
+export function bootstrap(framework: Framework): void {
+    framework.middleware.use("beforeLoad", tenantGuard);
+
+    defineRoutes(framework, [
+        { path: "/", intentId: "home", controller: new HomeController() },
+        { path: "/billing", intentId: "billing", controller: new BillingController() },
+        // ...
+    ]);
+}
+```
+
+`tenantGuard` runs before any route-specific guard, so by the time any controller executes, the tenant scope is set up.
+
+## Step 5: controllers transparently get the right services
+
+```ts
+// src/controllers/billing.ts
+export class BillingController extends BaseController<{}, BillingPage> {
+    readonly intentId = "billing";
+
+    async execute(_params, container) {
+        const config = container.resolve<TenantConfig>("tenantConfig");
+        const api = container.resolve<UserApi>("userApi"); // tenant-specific client
+
+        const usage = await api.getUsage();
+        const invoices = await api.getInvoices();
+
+        return {
+            kind: "billing",
+            tenantName: config.displayName,
+            usage,
+            invoices,
+        };
+    }
+}
+```
+
+The controller doesn't know about tenants — it just resolves `userApi` and gets the right one for this request.
+
+## Cross-tenant prohibitions
+
+To prevent a user authenticated for tenant A from accessing tenant B's data:
+
+```ts
+async function sameTenantGuard(ctx: NavigationContext) {
+    const session = await ctx.container.resolve<SessionService>("session").current();
+    const requestedTenant = ctx.container.resolve<TenantConfig>("tenantConfig").tenantId;
+
+    if (!session) return redirect("/login");
+    if (session.tenantId !== requestedTenant) return deny(403, "Cross-tenant access forbidden");
+
+    return next();
+}
+
+// Apply after tenantGuard:
+framework.middleware.use("beforeLoad", tenantGuard);
+framework.middleware.use("beforeLoad", sameTenantGuard);
+```
+
+Guard order matters — `tenantGuard` must register `tenantConfig` before `sameTenantGuard` reads it.
+
+## Hydration considerations
+
+Tenant configs include `featureFlags`, which are read on both server and client. The framework's `PrefetchedIntents` serialization handles this — the browser receives the same flag values the server saw, so client-side reads stay consistent.
+
+Tenant config itself is **not** automatically serialized. If your view needs to display `tenantConfig.displayName`, the controller should include it in the `Page` object:
+
+```ts
+async execute(_params, container) {
+    const config = container.resolve<TenantConfig>("tenantConfig");
+    return {
+        kind: "home",
+        tenant: {
+            id: config.tenantId,
+            displayName: config.displayName,
+        },
+        // ...
+    };
+}
+```
+
+The `Page` is serialized, so it survives the SSR → CSR boundary. The full `TenantConfig` (with secrets) should never end up in a `Page`.
+
+## Browser-side considerations
+
+`tenantGuard` runs on the browser too — on initial navigation and on every subsequent navigation. For browser-only apps (`renderMode: "csr"`), this is the only time it runs.
+
+But the browser can't safely resolve secrets like `apiToken`. Two approaches:
+
+**Approach 1: server proxies all API calls.** The browser hits `/api/users` (your proxy), which forwards to `${upstreamUrl}/users` with the auth header injected from `process.env[apiTokenEnvKey]`. The browser never sees the token.
+
+**Approach 2: short-lived session token.** The server issues a JWT scoped to the tenant; the browser uses it for direct upstream calls. Token rotation handled by your auth layer.
+
+Most apps go with approach 1. The framework's proxy router is designed for it.
+
+## Caveats
+
+### Don't cache tenant scopes across requests
+
+```ts
+// BAD
+const tenantScopeCache = new Map<string, Container>();
+
+async function tenantGuard(ctx) {
+    let scope = tenantScopeCache.get(tenantId);
+    if (!scope) {
+        scope = framework.container.createScope();
+        tenantScopeCache.set(tenantId, scope);
+    }
+    // Use scope...
+}
+```
+
+Each request needs its own scope — even for the same tenant — because:
+
+- Other guards add request-specific overrides (auth, trace id) that shouldn't leak across requests
+- The scope holds resolved instances of stateful services; sharing them across requests breaks isolation
+
+Tenant **config** can be cached. Tenant **scope** cannot.
+
+### Be careful with shared service instances
+
+If you cache the `UserApi` instance at module level instead of registering a factory, all requests share state:
+
+```ts
+// BAD
+const apiByTenant = new Map<string, UserApi>();
+scope.register("userApi", () => {
+    let api = apiByTenant.get(tenantId);
+    if (!api) {
+        api = new UserApi({ baseUrl: config.upstreamUrl });
+        apiByTenant.set(tenantId, api);
+    }
+    return api;
+});
+```
+
+If `UserApi` has any request-scoped state (interceptors that capture closures over request-specific values), they'll bleed across tenants. Register a fresh factory; let the container cache it per scope.
+
+## Testing
+
+```ts
+import { describe, test, expect, vi, afterEach } from "vite-plus/test";
+import { Container } from "@finesoft/front";
+import { tenantGuard } from "./tenant";
+
+afterEach(() => vi.restoreAllMocks());
+
+describe("tenantGuard", () => {
+    test("registers tenant services for known tenant", async () => {
+        const parent = new Container();
+        const scope = parent.createScope();
+
+        vi.spyOn(await import("../tenants/config"), "getTenantConfig").mockResolvedValue({
+            tenantId: "acme",
+            displayName: "Acme Co",
+            upstreamUrl: "https://acme.example",
+            apiToken: "token-123",
+            featureFlags: { darkMode: true },
+            locale: "en-US",
+        });
+
+        const ctx = {
+            url: new URL("https://acme.myapp.com/"),
+            container: scope,
+            intent: { intentId: "home", params: {} },
+            getCookie: () => null,
+            getHeader: () => null,
+            isSsr: true,
+        };
+
+        const result = await tenantGuard(ctx as any);
+
+        expect(result).toEqual({ kind: "next" });
+        expect(scope.resolve("tenantConfig")).toMatchObject({ tenantId: "acme" });
+    });
+
+    test("denies unknown tenant", async () => {
+        const ctx = {
+            url: new URL("https://unknown.myapp.com/"),
+            container: new Container(),
+            intent: { intentId: "home", params: {} },
+            getCookie: () => null,
+            getHeader: () => null,
+            isSsr: true,
+        };
+
+        const result = await tenantGuard(ctx as any);
+        expect(result).toMatchObject({ kind: "deny", status: 404 });
+    });
+});
+```
+
+## Related
+
+- [Chapter 7: DI container](../07-di-container.md) — scopes and fallback resolution
+- [Chapter 3: Middleware](../03-middleware.md) — global guards
+- [Pitfall: container scope leak](../pitfalls/container-scope-leak.md) — what goes wrong if you cache scopes

package/docs/engineering/ci-release-flow.md

@@ -0,0 +1,244 @@
+# Engineering: CI & release flow
+
+How the framework itself is released, and how to set up the same workflow for an app that depends on it.
+
+## What ships
+
+Only `@finesoft/front` is published to npm. The internal `core` / `browser` / `ssr` / `server` packages are bundled into `front` via `tsdown`'s `noExternal: [@finesoft/*]`.
+
+This means:
+
+- One npm package for users to install
+- Internal refactors don't bump multiple versions
+- Single CHANGELOG to read
+
+`create-finesoft-app` is its own published package (a CLI), separate from the framework runtime.
+
+## The release workflow
+
+The repo ships a single `.github/workflows/release.yml` that handles everything inline. Trigger: push to `main`.
+
+```
+push to main
+    │
+    ▼
+Checkout main (with PAT, not GITHUB_TOKEN)
+    │
+    ▼
+Reconcile npm registry with main
+    ├── npm == main? → continue
+    ├── main > npm? → catch-up publish current main version
+    └── npm > main? → error, manual investigation
+    │
+    ▼
+Generate auto-changeset (one patch per push)
+    │
+    ▼
+Apply version bump
+    ├── changes? → continue
+    └── no changes? → done, nothing to publish
+    │
+    ▼
+Commit "chore(release): version packages"
+    │
+    ▼
+Build all packages, publish @finesoft/front to npm
+    │
+    ▼
+Push commit + tag back to main (with rebase retry)
+```
+
+### Why one inline workflow instead of changesets/action's PR mode
+
+The standard changesets workflow opens a PR ("Version Packages") that, when merged, triggers a second workflow run that publishes. **But `GITHUB_TOKEN`-merged commits don't trigger subsequent workflows** (GitHub's anti-recursion safety) — the publish never fires. The inline workflow does everything in one run, no PR hop.
+
+### Why a PAT instead of `GITHUB_TOKEN`
+
+The repo has a ruleset enforcing signed commits, linear history, and required PRs on `main`. Bypass actors include `RepositoryRole=5 (admin)` but **not** `github-actions[bot]`. GitHub's UI does not allow adding the bot to the bypass list. Push from a PAT owned by an admin user matches the existing bypass entry.
+
+The PAT is `Contents: Read & Write` only — the minimum needed for `git push`.
+
+## Concurrency
+
+```yaml
+concurrency: release-${{ github.ref }}
+```
+
+Multiple pushes to `main` queue rather than cancel. This matters because:
+
+- Cancellation mid-publish leaves npm in an inconsistent state
+- Each push must wait for the previous to finish to avoid version-number races
+- The next run's reconcile step picks up whatever the previous one published
+
+## Idempotency
+
+`changeset publish` skips versions already on npm. So if push to `main` fails after publish:
+
+- npm: has version 0.1.75
+- main: stuck at 0.1.74
+
+The next release run's reconcile detects `main < npm`, refuses to "catch up backwards," and errors out. Manual remediation: open a PR that bumps `packages/front/package.json` to match npm and merges. Subsequent pushes resume normally.
+
+## Setting up the same for an app
+
+Most apps don't need a publish step — they have deploys instead. But the changeset + auto-bump shape still works:
+
+```yaml
+name: Release
+
+on:
+    push:
+        branches:
+            - main
+
+concurrency: release-${{ github.ref }}
+
+jobs:
+    release:
+        runs-on: ubuntu-latest
+        if: "!startsWith(github.event.head_commit.message, 'chore(release):')"
+        permissions:
+            contents: write
+        steps:
+            - uses: actions/checkout@v5
+              with:
+                  ref: main
+                  fetch-depth: 0
+                  token: ${{ secrets.RELEASE_PUSH_TOKEN }}
+
+            - uses: voidzero-dev/setup-vp@v1
+              with:
+                  node-version: 24
+                  cache: true
+
+            - run: vp install --frozen-lockfile
+
+            - name: Configure git
+              run: |
+                  git config user.name "github-actions[bot]"
+                  git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+            - name: Generate auto changeset
+              run: vp run release:auto:changeset
+
+            - name: Apply version bump
+              id: bump
+              run: |
+                  vp run version
+                  if git diff --quiet; then
+                      echo "should_publish=false" >> "$GITHUB_OUTPUT"
+                  else
+                      NEW=$(node -p "require('./package.json').version")
+                      echo "version=$NEW" >> "$GITHUB_OUTPUT"
+                      echo "should_publish=true" >> "$GITHUB_OUTPUT"
+                  fi
+
+            - name: Commit version
+              if: steps.bump.outputs.should_publish == 'true'
+              run: |
+                  git add -A
+                  git commit -m "chore(release): version packages"
+
+            - name: Build
+              if: steps.bump.outputs.should_publish == 'true'
+              run: vp run build
+
+            - name: Deploy
+              if: steps.bump.outputs.should_publish == 'true'
+              run: vp run deploy # your deploy command
+
+            - name: Push tag and commit
+              if: steps.bump.outputs.should_publish == 'true'
+              run: git push --follow-tags origin HEAD:main
+```
+
+Replace `vp run deploy` with your platform's deploy command (Vercel, Cloudflare, your own infra).
+
+## Conventional commits + auto-changeset
+
+The `release:auto:changeset` script (in this repo, generates one patch changeset per push) is intentionally simple — every merged PR becomes one patch bump. For semver-driven versioning, replace it with a script that:
+
+- Reads `git log` since the last tag
+- Maps commit prefixes (`feat:`, `fix:`, `BREAKING:`) to changeset types
+- Writes the right `.changeset/*.md`
+
+The framework's repo uses patch-only because:
+
+- Every push is a small change; large changes go through review and become small commits anyway
+- Real breaking changes are rare and warrant manual changesets
+- It avoids a class of "the prefix lies" bugs
+
+Pick the policy that matches how your team commits.
+
+## Per-PR validation (`quality.yml`)
+
+The repo also has a `quality.yml` workflow on PRs:
+
+```yaml
+on:
+    pull_request:
+    push:
+        branches:
+            - main
+
+jobs:
+    coverage:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v5
+            - uses: voidzero-dev/setup-vp@v1
+              with: { node-version: 24, cache: true }
+            - run: vp install --frozen-lockfile
+            - run: vp test --coverage
+            - uses: actions/upload-artifact@v7
+              with:
+                  name: coverage-report
+                  path: reports/coverage
+                  if-no-files-found: error
+```
+
+The `check` job (format + lint + types) is gated off by `if: false` in this repo because Vite+ runs them all locally via pre-commit. Re-enable it if your team doesn't run pre-commit hooks consistently.
+
+## CodeQL
+
+The repo enables CodeQL on a schedule and PRs. Scan scope is restricted to `packages/{core,browser,ssr,server,front}/src/**` — tests, templates, scripts, and the scaffolder are excluded.
+
+For application repos, enable the default CodeQL config — its noise is low and it catches real issues (open redirects, SQL injection, secret exposure).
+
+## Required status checks
+
+The repo ruleset requires:
+
+- `Coverage` (from `quality.yml`)
+- `CodeQL`
+
+PRs cannot merge until both pass. The release workflow bypasses these via the admin PAT — release runs after merge, on `main`, so the checks already passed on the PR.
+
+## Migration: from changesets PR mode to inline
+
+If you're moving an existing repo from `changesets/action` (PR mode):
+
+1. Delete the old release workflow
+2. Create the inline workflow above
+3. Generate a fine-grained PAT, store as `RELEASE_PUSH_TOKEN`
+4. The first push to main after this change will:
+    - Detect main == npm (no catch-up needed)
+    - Generate one patch changeset
+    - Bump + publish + push back to main
+
+If there's a pending "Version Packages" PR from the old workflow, close it without merging. The auto-changeset will pick up everything from there.
+
+## What can go wrong
+
+| Symptom                                         | Cause                                                                             | Fix                                                            |
+| ----------------------------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `[remote rejected] HEAD -> main`                | PAT actor not in ruleset bypass; PAT lacks `Contents: Write`                      | Verify PAT scope; confirm push actor is an admin user          |
+| `npm ... is ahead of main`                      | Previous run published but failed to push                                         | Open a PR syncing `packages/front/package.json` to npm version |
+| Workflow doesn't trigger after a release commit | `if: "!startsWith(github.event.head_commit.message, 'chore(release):'"` filtering | Working as intended — recursion prevention                     |
+| Pre-commit hook (`vp check`) fails CI           | Local formatter not run                                                           | `vp check --fix` locally; commit; rerun                        |
+
+## See also
+
+- The actual release workflow: `.github/workflows/release.yml`
+- The actual quality workflow: `.github/workflows/quality.yml`
+- [Changesets docs](https://github.com/changesets/changesets) — for understanding `vp run version` and `vp run release`