@mauroandre/velojs 0.0.37 → 0.0.38

package/README.md

@@ -746,18 +746,22 @@ poll({ intervalMs: 3000, tick: async (emit) => emit(await collect()) })
 Use `perChannelSource` for resources that scale per channel (SSH connections, DB cursors, pub/sub topics). Invoked once per channel on first subscriber, aborted when the last subscriber of that channel leaves.
 
 ```typescript
+// The client sends the composite key: useEventStream(stream_logs, { channel: `${worker}:${container}` })
 export const stream_logs = createEventStream<string>({
-    channel: (c) => `${c.req.param("worker")}:${c.req.param("container")}`,
+    channel: (c) => c.req.query("channel") ?? "",
     bufferSize: 500,
     perChannelSource: async (key, emit, { abortSignal }) => {
-        const conn = await ssh.connect(...);
-        const stream = conn.exec(`podman logs -f ${key.split(":")[1]}`);
+        const [worker, container] = key.split(":");
+        const conn = await ssh.connect(worker);
+        const stream = conn.exec(`podman logs -f ${container}`);
         stream.on("data", (d) => emit(d.toString(), { snapshot: true }));
         abortSignal.addEventListener("abort", () => { stream.close(); conn.end(); });
     },
 });
 ```
 
+> `c.req.param()` does **not** work in a `stream_*` resolver — convention streams mount at a static path (`/_event/{moduleId}/{name}`), so the page's `:params` are not in scope and it always returns empty. The channel travels as `?channel=`. (Params do work in a standalone stream given an explicit `path` containing `:segments`.)
+
 Mutually exclusive with `source`.
 
 ### Async channel resolver (auth + ownership)
@@ -1272,17 +1276,23 @@ Applied during Vite's `transform` hook to files in `appDirectory`:
 
 | # | Transform | When | What it does |
 |---|-----------|------|-------------|
-| 1 | `injectMetadata` | Server + Client | Adds `export const metadata = { moduleId, fullPath, path }` |
-| 2 | `transformLoaderFunctions` | Server + Client | Injects moduleId: `useLoader()` → `useLoader("moduleId")` |
-| 3 | `transformActionsForClient` | Client only | Replaces action body with `fetch()` stub |
-| 4 | `removeLoaders` | Client only | Removes `export const loader` entirely |
-| 5 | `removeMiddlewares` | Client only | Removes `middlewares: [...]` and related imports |
+| 1 | `removeMiddlewares` | Client only | Removes every `middlewares` property and the imports only it referenced |
+| 2 | `removeEndpointRoutes` | Client only | Strips `handler:` endpoint nodes from `routes.tsx` |
+| 3 | `injectMetadata` | Server + Client | Adds `export const metadata = { moduleId, fullPath, path }` |
+| 4 | `transformLoaderFunctions` | Server + Client | Injects moduleId: `useLoader()` → `useLoader("moduleId")` |
+| 5 | `transformActionsForClient` | Client only | Replaces action body with `fetch()` stub |
+| 6 | `transformStreamsForClient` | Client only | `stream_*` → `{ __isVeloEventStream, __path }` stub |
+| 7 | `transformSocketsForClient` | Client only | `socket_*` → `{ __isVeloSocket, __path }` stub |
+| 8 | `removeLoaders` | Client only | Removes `export const loader` entirely |
+| 9 | `pruneClientOnlyImports` | Client only | Drops imports left unreferenced by the strips above |
+
+Only `.ts`/`.tsx` files inside `appDirectory` are transformed — a `.jsx`/`.js` page, or one outside it, is not touched at all.
 
 ### Build Process
 
 ```bash
 velojs build
-# 1. vite build              → dist/client/ (client.js, client.css, manifest.json)
+# 1. vite build              → dist/client/ (client.[hash].js, client.[hash].css, .vite/manifest.json)
 # 2. vite build --mode server → dist/server.js (SSR entry)
 ```
 

package/agent/AGENTS.md

@@ -0,0 +1,143 @@
+# VeloJS — Agent Rules
+
+You are building an application **with** VeloJS. This file is the constitution and the
+map. It is not documentation: load the matching skill (below) before writing anything
+non-trivial.
+
+## The stack is a premise, not a choice
+
+Server: **Hono**. UI: **Preact** + `@preact/signals`. Router: **wouter-preact**.
+Build: **Vite** + the VeloJS Babel plugin.
+
+Never introduce, suggest, or import: Express, Fastify, Next, Remix, React Router,
+`react`/`react-dom` (both are aliased to `preact/compat` — import from `preact`),
+Redux/Zustand/Jotai (component state is `@preact/signals`), or any router other than
+the route tree. If a task seems to need one, you have misread the task — re-read the
+relevant skill first.
+
+## Rules that fail silently
+
+These do not fail typecheck. They do not throw at build. They produce a broken app that
+looks fine. Every row below was verified against the compiler transforms — treat them as
+hard constraints, not style.
+
+| Never write | Always write | What silently happens |
+|---|---|---|
+| `export default routes` (a variable) | the array literal inline in the `export default` — `satisfies AppRoutes` or `as AppRoutes` both work | the path map is built by reading the array **literal**; an identifier yields an empty map → no module gets `fullPath` → **every route 404s** |
+| `import Home from "./pages/Home.js"`<br>`import { Component } from "./pages/Home.js"` | `import * as Home from "./pages/Home.js"` | only `import * as` is registered → **that route silently disappears** |
+| `import * as Home from "../shared/Home.js"`<br>or a tsconfig alias, in `routes.tsx` | `./`-relative paths inside `appDirectory` | the map key won't match the module id → **route dropped** |
+| `export async function action_x(...)` | `export const action_x = async ({ body }) => {}` | no client stub is generated → **the action body and its server imports ship to the browser and execute there** |
+| `export const action_x = async (args) => {}` | `export const action_x = async ({ body }) => {}` | the generated stub references an undeclared `body` → **ReferenceError in the browser** when called |
+| `export const action_x = ({ body }) => {}` (not `async`) | `async ({ body }) => {}` | not recognized → no stub → **server code runs in the browser** |
+| `export async function loader(...)` | `export const loader = async ({ params }) => {}` | only `const` loaders are stripped → **the whole loader ships to the client bundle** |
+| `export const action_a = ..., action_b = ...` | one `export const` per declaration | only the **first** declarator is read → **the second is silently ignored** (same for `loader`, `stream_*`, `socket_*`, `metadata`) |
+| `useParams()` / `useQuery()` / `usePathname()` inside a `loader` | the loader's own args: `async ({ params, query, c }) => {}` | the async context wraps only rendering; loaders run **before** it → returns `{}` / `"/"` |
+| `c.req.param(...)` or `params.x` inside `action_*`, `stream_*`, `socket_*` | actions: read it from `body`. streams/sockets: send `?channel=` from the client and read `query.channel` | these register at **static** paths (`/_action/{moduleId}/{name}`, `/_event/…`, `/_socket/…`) — the page's `:params` are not in scope → always `{}` / `undefined` |
+| a page in `.jsx` / `.js`, or any page outside `appDirectory` | `.tsx` inside `app/` | **zero transforms**: no metadata, no stubs, loader ships to the client |
+| a root layout that doesn't render a literal `<head>` | `isRoot` component renders `<html><head>…</head><body>{children}</body></html>` | `__PAGE_DATA__` is injected by replacing `</head>` → **every loader hydrates `null`** and refetches |
+
+Never pass a module id to `useLoader()` / `Loader()` yourself — the plugin injects it.
+
+## Sharing a layout's data with its children
+
+`Loader()` is the importable handle for a module's loader data; `useLoader()` is the
+component-local form. Both read the same entry, so a child can read — and optimistically
+mutate — its layout's data:
+
+```ts
+// app/admin/CompaniesLayout.tsx
+export const { data: companiesData, refetch } = Loader<LoaderData>();
+
+// app/admin/companies/CompanyInfo.tsx — rendered inside it
+import { companiesData } from "../CompaniesLayout.js";
+companiesData.value!.companies[i] = saved;
+touch(companiesData);        // you already know the result — no round-trip
+refetch();                   // or make the server recompute
+```
+
+Never mirror loader data into a module-level `export let`: on the server a module binding
+is per-process, so a value stored there belongs to whichever request wrote it last.
+`Loader()`'s server value is an AsyncLocalStorage getter — per-request by construction.
+
+An entry refreshes on navigation when the params **its own route declares** change
+(`/x/:id`). A query string is not declared in `routes.tsx`, so nothing infers it — use
+`useLoader([query.tab])` when data depends on one.
+
+## A stream/socket `channel` is untrusted client input
+
+`useEventStream(s, { channel })` and `useSocket(s, { channel })` put the channel on the
+query string. Anyone can send any value. A resolver that echoes it back subscribes the
+caller to **someone else's data**:
+
+```ts
+channel: (c) => c.req.query("channel") ?? ""   // IDOR unless the route is already role-gated
+```
+
+Resolve it through an ownership check instead. Returning `null` denies with 403:
+
+```ts
+export const ownAppChannel = async (c: Context): Promise<string | null> => {
+    const appId = c.req.query("channel");
+    if (!appId) return null;
+    const user = c.get("user");                       // set by the route's middleware
+    if (!user?.id) return null;
+    const { getApp } = await import("./app.service.js");   // keep the service off the client graph
+    const app = await getApp({ id: appId });
+    if (!app) return null;
+    if (user.role !== "master" && app.ownerId !== user.id) return null;
+    return appId;
+};
+```
+
+Echoing the raw query value is only acceptable when the route's middleware already
+restricts every subscriber (e.g. a master-only page). Deriving the channel from the
+session instead — `channel: (c) => c.get("user").id` — needs no check, since the client
+cannot influence it.
+
+## The map
+
+| File | Role |
+|---|---|
+| `app/routes.tsx` | The route tree. `export default [...] satisfies AppRoutes`, `import * as` for every page/layout |
+| `app/<domain>/Page.tsx` | One module per route: `Component`, plus optional `loader`, `action_*`, `stream_*`, `socket_*`, `metadata`. Group by domain (`app/auth/`, `app/admin/`), not in a flat `pages/` folder |
+| `app/layouts/*.tsx` | Shared layouts. Long-lived `stream_*` declarations usually live on the layout that spans their pages |
+| `app/modules/<domain>/` | Server-side logic imported by pages: `*.service.ts`, `*.middleware.ts`, `*.stream.ts`. Not routed |
+| `app/components/*.tsx` | Shared UI with no route of its own |
+| `app/client-root.tsx` | The `isRoot` HTML shell — must render `<head>` with `<Scripts />` |
+| `app/server.tsx` | Server-only init (`addRoutes`, `onServer`, connections) |
+| `app/client.tsx` | Client-only init (global CSS) |
+| `vite.config.ts` | `veloPlugin()` |
+
+Import subpaths (the package root exports only types, `defineConfig`, `Scripts`, `Link`,
+`createEventStream`, `poll`): `@mauroandre/velojs/hooks`, `/server`, `/client`,
+`/events`, `/sockets`, `/testing`, `/vite`, `/config`, `/cookie`.
+
+Conventions that carry meaning: a route node is `{ path, module, children, middlewares,
+isRoot, statusCode }`; `{ path: "*" }` is the catch-all (served via Hono's `notFound`,
+defaults to 404); a node with `{ method, handler }` and no `module` is an HTTP endpoint.
+
+## Load the skill first
+
+Before writing anything non-trivial, load the skill for the subject. Do not infer the
+API from this file — it is deliberately incomplete.
+
+| Subject | Skill |
+|---|---|
+| New project, first page, project layout | `getting-started` |
+| Route tree, nesting, layouts, params, catch-all, status codes | `routes` |
+| Page modules, `Component`, `metadata` | `components` |
+| Server data for a page, SSR + SPA fetch | `loaders` |
+| Calling server code from the client, forms, mutations | `actions` |
+| REST/JSON endpoints, webhooks, non-page HTTP | `endpoints` |
+| Auth, guards, per-route server logic | `middlewares` |
+| `useLoader`, `useParams`, `useQuery`, `usePathname`, `useNavigate` | `hooks` |
+| Navigation, `<Link>` | `link-component` |
+| `<Scripts />`, assets, favicon | `scripts-component` |
+| SSE, live/progress/streaming data | `event-streams` |
+| WebSockets, bidirectional realtime | `sockets` |
+| `addRoutes`, `onServer`, ports, server lifecycle | `server-api` |
+| The build, transforms, `veloPlugin` options | `vite-plugin` |
+| SSG, prerendering, `staticPaths` | `static-generation` |
+| Deploy, env vars, Docker, production | `production-deploy` |
+| Writing tests, `createTestApp` | `testing` |
+| Exact type signatures | `type-reference` |

package/agent/skills/velojs-actions/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: velojs-actions
+description: "Server actions: call server code from the client as a normal async function. Use when building login, form submit, a mutation, save/delete buttons, or any server-side operation triggered by user interaction."
+---
+
+# Actions
+
+Actions are server-side functions that you can call from the client as if they were regular functions. VeloJS transforms them into HTTP calls automatically — you write server code, the framework handles the rest.
+
+## How actions work
+
+An exported **`const` holding an `async` arrow function** whose name starts with `action_` is treated as a server action:
+
+```typescript
+export const action_login = async ({
+    body,
+    c,
+}: ActionArgs<{ email: string; password: string }>) => {
+    const { authenticate } = await import("./auth.service.js");
+    const token = await authenticate(body.email, body.password);
+
+    const { setCookie } = await import("@mauroandre/velojs/cookie");
+    setCookie(c!, "session", token, { path: "/" });
+
+    return { ok: true };
+};
+```
+
+On the **server**, this function runs normally — it has access to the Hono context (`c`), can read cookies, access the database, and do anything a server function can do.
+
+On the **client**, the Vite plugin replaces the function body with a `fetch()` call. The client version looks like this:
+
+```typescript
+// What the client actually executes (generated automatically):
+export const action_login = async ({ body }: { body: { email: string; password: string } }) => {
+    return fetch("/_action/auth/Login/login", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    }).then(r => r.json());
+};
+```
+
+You don't write this — the Vite plugin generates it at build time by analyzing the AST of your code.
+
+## The shape is load-bearing
+
+The plugin recognizes actions by their exact shape. Write one differently and it is silently **not** transformed: the server still registers it, so it looks like it works — but the real body and its server-only imports ship to the browser and run there.
+
+```typescript
+// ✅ the only recognized form
+export const action_save = async ({ body }: ActionArgs<Body>) => { ... };
+
+// ❌ a function declaration — no stub is generated; your DB code goes to the browser
+export async function action_save({ body }: ActionArgs<Body>) { ... }
+
+// ❌ not async — same
+export const action_save = ({ body }: ActionArgs<Body>) => { ... };
+
+// ❌ the param must be destructured — the generated stub sends `body`, so a
+//    non-destructured param leaves it undeclared → ReferenceError when called
+export const action_save = async (args: ActionArgs<Body>) => { ... };
+
+// ❌ one action per `export const` — only the first declarator is read,
+//    so `action_b` is silently ignored
+export const action_a = async ({ body }) => { ... },
+             action_b = async ({ body }) => { ... };
+```
+
+## The ActionArgs type
+
+Every action receives an object with these properties:
+
+| Property | Type | Available on | Description |
+|----------|------|-------------|-------------|
+| `body` | `TBody` | Server + Client | The data sent from the client |
+| `c` | `Context` | Server only | Hono request context (cookies, headers, etc) |
+| `params` | `Record<string, string>` | Server only | **Always empty.** See below |
+| `query` | `Record<string, string>` | Server only | Empty unless you hand-craft the request (e.g. `app.action(fn, { query })` in a test) |
+
+On the client, only `body` is available (the rest are stripped by the Vite plugin).
+
+### `params` is always empty in an action
+
+An action is mounted at its own static path — `/_action/{moduleId}/{name}` — not at the URL of the page it lives on. That path has no `:segments`, so `params` never has anything in it, even when the page is at `/users/:id`.
+
+Put the id in the body:
+
+```typescript
+// ❌ params.id is undefined — the action isn't mounted on /users/:id
+export const action_remove = async ({ params }: ActionArgs) => remove(params.id);
+
+// ✅
+export const action_remove = async ({ body }: ActionArgs<{ id: string }>) => remove(body.id);
+```
+
+```tsx
+const params = useParams<{ id: string }>();
+await action_remove({ body: { id: params.id } });
+```
+
+## Error handling
+
+Actions **do not throw** on server errors. Instead, they resolve with `{ error: "message" }`. Always check for errors explicitly:
+
+```typescript
+const result = await action_login({ body: { email, password } });
+
+if (result.error) {
+    showToast(result.error, "danger");
+    return;
+}
+
+// Success
+window.location.href = "/admin";
+```
+
+## Remember: use dynamic imports
+
+Just like loaders, actions should use `await import()` for server-only code:
+
+```typescript
+export const action_delete = async ({ body }: ActionArgs<{ id: string }>) => {
+    // GOOD — dynamic import
+    const { deleteUser } = await import("./user.service.js");
+    await deleteUser(body.id);
+    return { ok: true };
+};
+```
+
+## Sharing actions across pages
+
+Every action lives at a fixed URL: `/_action/{moduleId}/{actionName}`. The `moduleId` comes from the file where the action is **declared** — never from the file where it's imported. This means you can declare an action once in a layout and import it from any child page.
+
+### When to use this
+
+Common cases:
+
+- **Logout** — every page under an auth layout needs the same action
+- **Global forms** — like a "contact us" that appears in multiple pages
+- **Shared mutations** — like toggling a theme or closing a notification
+
+### Example: logout action in a layout
+
+```typescript
+// app/admin/Layout.tsx
+import type { ActionArgs } from "@mauroandre/velojs";
+
+export const action_logout = async ({ c }: ActionArgs) => {
+    const { deleteCookie } = await import("@mauroandre/velojs/cookie");
+    deleteCookie(c!, "session");
+    return { ok: true };
+};
+
+export const Component = ({ children }) => (
+    <div>
+        <nav>/* ... */</nav>
+        {children}
+    </div>
+);
+```
+
+Now any page under the layout can import and call it:
+
+```typescript
+// app/admin/Dashboard.tsx
+import { action_logout } from "./Layout.js";
+
+export const Component = () => (
+    <button onClick={async () => {
+        await action_logout({});
+        window.location.href = "/login";
+    }}>
+        Logout
+    </button>
+);
+```
+
+```typescript
+// app/admin/Settings.tsx — same action, different page
+import { action_logout } from "./Layout.js";
+
+export const Component = () => (
+    <a onClick={() => action_logout({})}>Leave</a>
+);
+```
+
+Both imports compile to the **same URL**: `POST /_action/admin/Layout/logout`. Middlewares on the layout (like `authMiddleware`) apply automatically.
+
+### Why this works
+
+The Vite plugin replaces the action body with a `fetch()` call to its registered URL **during compile time**, using the `moduleId` of the file where the export lives. Imports in other files just reuse that compiled stub — they never change the URL.

package/agent/skills/velojs-components/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: velojs-components
+description: "Page and layout modules: the `Component` export, `metadata`/title, `children`, and keeping server-only code out of the client bundle. Use when creating a page or layout, setting a page title, or asked why a server import leaked to the browser."
+---
+
+# Components
+
+Every page and layout in VeloJS is a module that can export up to three things. Understanding these conventions is key to building with VeloJS.
+
+## The three exports
+
+| Export | Purpose |
+|--------|---------|
+| `export const Component` | The Preact component that renders the UI (required) |
+| `export const loader` | A server-side function that fetches data for the page |
+| `export const action_*` | Server-side functions callable from the client (RPC) |
+
+## Example page
+
+Here's a complete page that uses all three:
+
+```typescript
+// app/admin/Users.tsx
+import type { LoaderArgs, ActionArgs } from "@mauroandre/velojs";
+import { useLoader } from "@mauroandre/velojs/hooks";
+
+interface User { id: string; name: string; }
+
+// 1. Loader — runs on the server, fetches data
+export const loader = async ({ params, query, c }: LoaderArgs) => {
+    const { getUsers } = await import("./user.service.js");
+    return getUsers();
+};
+
+// 2. Action — runs on the server, called from the client
+export const action_delete = async ({
+    body,
+    c,
+}: ActionArgs<{ id: string }>) => {
+    const { deleteUser } = await import("./user.service.js");
+    await deleteUser(body.id);
+    return { ok: true };
+};
+
+// 3. Component — renders on both server (SSR) and client
+export const Component = () => {
+    const { data, loading, refetch } = useLoader<User[]>();
+
+    if (loading.value) return <div>Loading...</div>;
+
+    return (
+        <ul>
+            {data.value?.map((u) => (
+                <li key={u.id}>
+                    {u.name}
+                    <button onClick={async () => {
+                        await action_delete({ body: { id: u.id } });
+                        refetch();
+                    }}>Delete</button>
+                </li>
+            ))}
+        </ul>
+    );
+};
+```
+
+## Server-only imports (critical)
+
+This is the **most important convention** in VeloJS. Read this carefully.
+
+Your page file is bundled for **both** server and client. For the client, the Vite plugin removes the `loader` export, stubs `action_*` into `fetch()` calls, and then prunes any top-level import left **unreferenced** by that strip.
+
+So an import used only inside a loader is dropped for you. What survives the strip keeps its imports — and that's where server code leaks:
+
+**The rule**: always use `await import()` inside loaders and actions for server-only code. Never reference it from anything that survives into the client bundle.
+
+```typescript
+// BAD — `conn` is module-scope, so it survives the strip, so the import survives
+// with it, and the database driver lands in the browser.
+import { db } from "../db/engine.js";
+
+const conn = db.connect();
+
+export const loader = async () => conn.query("select * from users");
+```
+
+```typescript
+// GOOD — dynamic import only runs on the server
+export const loader = async () => {
+    const { getUsers } = await import("./user.service.js");
+    return getUsers();
+};
+```
+
+Why does this matter? Because `user.service.js` might import a database driver, which imports Node.js native modules like `fs` or `crypto`. If that code ends up in the client bundle, Vite will throw errors or include unnecessary code.
+
+The same applies anywhere the strip leaves a reference behind — a value used in the `Component`, a helper called at module scope, or a type kept in an action's signature. When in doubt, move the import inside the function that needs it.
+
+**Think of it this way**: any `import` at the top of the file is shared between server and client. Any `await import()` inside a function is server-only (because loaders and actions only run on the server).