@finesoft/front 0.1.76 → 0.1.77

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`

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