@mauroandre/velojs 0.0.36 → 0.0.38

package/agent/skills/velojs-getting-started/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: velojs-getting-started
+description: "Scaffold a new VeloJS project and its file layout: `velojs init`, `vite.config.ts`, `app/routes.tsx`, the root HTML shell, dev server. Use when starting a project from scratch or wiring up the toolchain."
+---
+
+# Getting Started
+
+VeloJS is a fullstack web framework that combines Hono (server), Preact (UI), and Vite (build) into a single, cohesive experience. You write your pages, loaders, and server actions in one place — VeloJS handles the rest.
+
+## Create a new project
+
+The fastest way to start is with the CLI:
+
+```bash
+npx @mauroandre/velojs init my-app
+cd my-app
+npm install
+npx velojs dev
+```
+
+This creates a ready-to-run project. Open `http://localhost:3000` and you should see your app.
+
+## Project structure
+
+Every VeloJS project follows this layout:
+
+```
+my-app/
+├── app/
+│   ├── routes.tsx        # Where you define all your routes
+│   ├── server.tsx        # Server-only init (databases, APIs, etc)
+│   ├── client.tsx        # Client-only init (global CSS, etc)
+│   ├── client-root.tsx   # The HTML shell (<html>, <head>, <body>)
+│   └── pages/            # Your pages, layouts, and modules
+├── vite.config.ts        # Vite configuration (just one plugin)
+├── tsconfig.json
+└── package.json
+```
+
+Let's walk through each file.
+
+## vite.config.ts
+
+VeloJS works through a single Vite plugin that handles everything — SSR, route scanning, code transforms, and the dev server:
+
+```typescript
+import { defineConfig } from "vite";
+import { veloPlugin } from "@mauroandre/velojs/vite";
+
+export default defineConfig({
+    plugins: [veloPlugin()],
+});
+```
+
+That's it. No extra plugins needed.
+
+## package.json scripts
+
+Your project needs three scripts:
+
+```json
+{
+    "scripts": {
+        "dev": "velojs dev",
+        "build": "velojs build",
+        "start": "velojs start"
+    }
+}
+```
+
+- `dev` — starts the development server with hot reload
+- `build` — compiles the client bundle and server entry for production
+- `start` — runs the production server (automatically sets `NODE_ENV=production`)
+
+## app/client-root.tsx — The HTML shell
+
+This is the outermost component of your app. It renders the `<html>`, `<head>`, and `<body>` tags. Every page in your app will be rendered inside this shell.
+
+The `<Scripts />` component is required — it injects the CSS and JavaScript that your app needs (Vite HMR in dev, compiled assets in production).
+
+```tsx
+import type { ComponentChildren } from "preact";
+import { Scripts } from "@mauroandre/velojs";
+
+export const Component = ({ children }: { children?: ComponentChildren }) => (
+    <html lang="en">
+        <head>
+            <meta charset="UTF-8" />
+            <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+            <title>My App</title>
+            <Scripts />
+        </head>
+        <body>{children}</body>
+    </html>
+);
+```
+
+## app/client.tsx — Client entry
+
+This file runs only on the client (browser). Use it to import global CSS or initialize client-side libraries:
+
+```typescript
+import "./styles/global.css";
+```
+
+## app/server.tsx — Server entry
+
+This file runs only on the server. Use it to connect to databases, register custom API routes, or start background jobs:
+
+```typescript
+import { addRoutes } from "@mauroandre/velojs/server";
+import type { Hono } from "hono";
+
+// Register custom API routes
+addRoutes((app: Hono) => {
+    app.get("/api/health", (c) => c.json({ ok: true }));
+});
+```
+
+## app/routes.tsx — Route definitions
+
+Routes are defined as a tree. Each node has a `module` (the page or layout component) and optionally `path`, `children`, and `middlewares`:
+
+```typescript
+import type { AppRoutes } from "@mauroandre/velojs";
+import * as Root from "./client-root.js";
+import * as Home from "./pages/Home.js";
+
+export default [
+    {
+        module: Root,
+        isRoot: true,
+        children: [
+            { path: "/", module: Home },
+        ],
+    },
+] satisfies AppRoutes;
+```
+
+Page and layout modules **must** be imported with `import * as Name from "./x.js"`. This isn't style: when the plugin resolves each module's URL it only reads namespace imports, so a default or named import silently drops the route — the server logs `Module … has no fullPath` at startup and the page 404s. Use `./`-relative paths inside `appDirectory` too; a `../` path or a tsconfig alias produces a key the plugin can't match, with the same result.
+
+## Your first page
+
+A page in VeloJS can export three things:
+
+- `Component` — the Preact component that renders the UI
+- `loader` — a server-side function that fetches data
+- `action_*` — server-side functions callable from the client
+
+Here's a simple page with a loader:
+
+```typescript
+import type { LoaderArgs } from "@mauroandre/velojs";
+import { useLoader } from "@mauroandre/velojs/hooks";
+
+// This runs on the server. It fetches data for the page.
+export const loader = async ({ c }: LoaderArgs) => {
+    return { message: "Hello, VeloJS!" };
+};
+
+// This runs on both server (SSR) and client (hydration).
+export const Component = () => {
+    const { data } = useLoader<{ message: string }>();
+    return <h1>{data.value?.message}</h1>;
+};
+```
+
+The loader runs on the server, and the data is automatically available in the component through `useLoader()`. On the first page load (SSR), the data is injected into the HTML. On client-side navigation, it's fetched via an API call — all automatically.
+
+## Run the dev server
+
+```bash
+npm run dev
+```
+
+Open `http://localhost:3000` in your browser. Changes to your code will hot-reload instantly.
+
+## Configuration
+
+The `veloPlugin()` accepts optional configuration:
+
+```typescript
+veloPlugin({
+    appDirectory: "./app",      // where your app files live (default: "./app")
+    routesFile: "routes.tsx",   // your routes file (default: "routes.tsx")
+    serverInit: "server.tsx",   // server init file (default: "server.tsx")
+    clientInit: "client.tsx",   // client init file (default: "client.tsx")
+});
+```
+
+Most projects don't need to change these defaults.

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

@@ -0,0 +1,103 @@
+---
+name: velojs-hooks
+description: "Client/SSR hooks: `useLoader`, `useParams`, `useQuery`, `usePathname`, `useNavigate`, `touch`, `useEventStream`, `useSocket`. Use when reading URL params or query string, navigating programmatically, or updating signal state."
+---
+
+# Hooks
+
+VeloJS provides a set of hooks that work identically on both server (SSR) and client. On the server, they read from `AsyncLocalStorage` (isolated per request). On the client, they use the DOM and wouter-preact.
+
+## Available hooks
+
+| Hook | Returns | Description |
+|------|---------|-------------|
+| `useLoader<T>(deps?)` | `{ data, loading, refetch }` | Page data with SSR + SPA support |
+| `Loader<T>()` | `{ data, loading }` | Module-level SSR-only data |
+| `useEventStream<T, S>(stream, opts?)` | `{ data, snapshot, closed, error }` | Real-time SSE stream subscription |
+| `useParams<T>()` | `T` | URL parameters (`:id`, etc) |
+| `useQuery<T>()` | `T` | Query string parameters |
+| `useNavigate()` | `navigate(path)` | Programmatic navigation |
+| `usePathname()` | `string` | Absolute URL pathname |
+| `touch(signal)` | `void` | Force signal notification after mutation |
+
+## useParams
+
+Reads URL parameters from the current route. For example, if your route path is `/users/:id`:
+
+```typescript
+const params = useParams<{ id: string }>();
+console.log(params.id); // "123" when visiting /users/123
+```
+
+## useQuery
+
+Reads query string parameters from the URL. For example, visiting `/search?q=hello&page=2`:
+
+```typescript
+const query = useQuery<{ q: string; page: string }>();
+console.log(query.q);    // "hello"
+console.log(query.page); // "2"
+```
+
+## useNavigate
+
+Returns a function for programmatic navigation (when you need to navigate from code, not from a link):
+
+```typescript
+const navigate = useNavigate();
+
+const handleLogin = async () => {
+    const result = await action_login({ body: credentials });
+    if (!result.error) {
+        navigate("/admin");
+    }
+};
+```
+
+## usePathname
+
+Returns the **absolute** pathname of the current URL, and works identically on the server (SSR) and the client. It reads the real URL rather than any router state, so you always get the full path.
+
+```typescript
+const pathname = usePathname();
+// Always returns the full path, e.g., "/admin/users/123"
+```
+
+This is useful when you need the exact current URL — for active-link styling, breadcrumbs, analytics, and the like.
+
+## useEventStream
+
+Subscribes to a server-sent event stream created with `createEventStream`. Returns reactive signals for the latest event, initial snapshot, close state, and errors.
+
+```typescript
+const { data, snapshot, closed, error } = useEventStream(stream, {
+    channel: "deploy-123",  // optional
+    enabled: true,          // optional, default true
+});
+
+// data.value     — latest event received from the server
+// snapshot.value — initial state on connect (if configured)
+// closed.value   — true when server closed the stream (closeOn matched)
+// error.value    — parse or connection error, if any
+```
+
+The hook handles `EventSource` lifecycle automatically: opens on mount, closes on unmount, re-opens when `channel` changes. See [Event Streams](/docs/event-streams) for the full guide.
+
+## touch
+
+Preact signals are great for reactivity, but they have a limitation: mutating a nested property (like changing `items[0].checked`) doesn't trigger a signal update. The `touch` function forces the signal to notify its subscribers after a mutation:
+
+```typescript
+import { useSignal } from "@preact/signals";
+import { touch } from "@mauroandre/velojs/hooks";
+
+const items = useSignal<Item[]>([]);
+
+// Mutating a nested property — signal doesn't know about this
+items.value[0].checked = true;
+
+// touch() creates a shallow copy, which triggers the update
+touch(items);
+```
+
+Use `touch` whenever you mutate nested properties on a signal value instead of replacing the entire value.

package/agent/skills/velojs-link-component/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: velojs-link-component
+description: "The `<Link>` component for SPA navigation, linking by route module, and substituting `:params`. Use when adding navigation, a menu, or any internal link."
+---
+
+# Link Component
+
+The `Link` component handles navigation in VeloJS. It supports both simple string paths and type-safe module references.
+
+All link paths are **root-absolute** — they resolve from the root of your app, exactly as the server does. There is no per-layout relative context to keep track of.
+
+## Basic usage
+
+```typescript
+import { Link } from "@mauroandre/velojs";
+
+// Simple string path
+<Link to="/users">Users</Link>
+
+// With URL parameters
+<Link to="/users/123">View User</Link>
+```
+
+## Module references
+
+Instead of hardcoding paths, you can pass a route module directly. The link uses the module's `fullPath`, so if the path changes in `routes.tsx`, your links update automatically:
+
+```typescript
+import { Link } from "@mauroandre/velojs";
+import * as UserPage from "./users/UserDetail.js";
+
+// Navigates to the module's full path (e.g. /users/:id)
+<Link to={UserPage} params={{ id: "123" }}>View</Link>
+```
+
+## Parameters and query strings
+
+Use `params` to substitute `:param` placeholders in the path, and `search` to add query string parameters:
+
+```typescript
+<Link to={UserPage} params={{ id: "123" }} search={{ tab: "settings" }}>
+    User Settings
+</Link>
+// Renders: /users/123?tab=settings
+```
+
+## The `~/` prefix
+
+String paths may start with `~/`. This is wouter-preact's root-absolute prefix: the `~` is stripped and the path resolves from the root. Since VeloJS links are already root-absolute, `~/x` and `/x` resolve to the same place:
+
+```typescript
+<Link to="~/stacks">Stacks</Link>   // → /stacks
+<Link to="/stacks">Stacks</Link>    // → /stacks  (identical)
+```
+
+The prefix is supported for backward compatibility — you can keep existing `~/` links as-is, or drop the `~` in new code.
+
+> **Migrating from older versions:** earlier releases resolved string and module links relative to the current layout's nest context, and `~/` escaped to the root. Layout nesting on the client now mirrors the server (full-path matching, no nested base), so every link is root-absolute. In practice: keep using absolute paths (`/stacks`) or module references; existing `~/` links keep working.
+
+## Props reference
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `to` | `string \| RouteModule` | Destination path or module. A string may start with `~/` (root-absolute); a module resolves to its `fullPath`. |
+| `params` | `Record<string, string>` | Substitutes `:param` placeholders in the path. |
+| `search` | `Record<string, string>` | Appends query string parameters to the URL. |
+| `absolute` | `boolean` | Deprecated, no-op. Module references always use `fullPath`. Kept for backward compatibility. |

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

@@ -0,0 +1,134 @@
+---
+name: velojs-loaders
+description: "Loading server data for a page: the `loader` export, `useLoader`, the `Loader` handle for sharing a layout's data with its children, hydration and SPA refetch. Use when a page needs data from a database or API before it renders."
+---
+
+# Loaders
+
+Loaders are how you fetch data on the server and make it available to your components. VeloJS provides two patterns, each designed for a different use case.
+
+## useLoader — Component-level data
+
+Use `useLoader` inside a `Component` when you need data that's specific to that page. It supports both SSR (server-side rendering) and SPA navigation (client-side fetch).
+
+```typescript
+export const Component = () => {
+    const { data, loading, refetch } = useLoader<MyType>();
+
+    // data: Signal<T | null>     — the loader data (reactive)
+    // loading: Signal<boolean>   — true while fetching
+    // refetch: () => void        — manually re-fetch the data
+};
+```
+
+**How it works:**
+- On the first page load (SSR), the data is rendered on the server and injected into the HTML
+- When the user navigates to this page via a link (SPA), `useLoader` fetches the data from the server automatically
+- The data is a Preact signal — your UI updates automatically when it changes
+
+### Re-fetching on route changes — automatic
+
+If your page's route declares a param, you don't have to do anything. VeloJS reads the route tree, so it already knows that a module at `/users/:id` depends on `id`, and refreshes its data when you navigate from `/users/1` to `/users/2`:
+
+```typescript
+// app/users/Detail.tsx — routed at /users/:id
+export const Component = () => {
+    const { data } = useLoader<User>();   // refreshes on :id change, no deps needed
+};
+```
+
+### Deps — for what the route doesn't declare
+
+`routes.tsx` declares path params (`/users/:id`), never query strings or client state. When your data depends on one of those, pass it as a dependency:
+
+```typescript
+const query = useQuery<{ tab: string }>();
+const { data } = useLoader<Report>([query.tab]);   // ?tab= is not in the route
+```
+
+A dep that just repeats a path param is harmless but redundant — the framework already knows.
+
+## Loader — Module-level shared data
+
+Use `Loader` (capital L, outside of components) when **another module needs your data**. It gives you a handle you can export — typically from a layout, so its child pages can read it.
+
+```typescript
+// app/admin/Layout.tsx
+import { Loader } from "@mauroandre/velojs/hooks";
+
+export const loader = async ({ c }: LoaderArgs) => {
+    const user = c.get("user");
+    return { name: user.name, role: user.role };
+};
+
+// Runs at module import — not inside a component
+export const { data: userData, refetch } = Loader<UserData>();
+
+export const Component = ({ children }) => (
+    <div>
+        <header>Hello, {userData.value?.name}</header>
+        {children}
+    </div>
+);
+```
+
+Child pages import the handle directly:
+
+```typescript
+// app/admin/Dashboard.tsx
+import { userData } from "./Layout.js";
+
+export const Component = () => (
+    <div>Role: {userData.value?.role}</div>
+);
+```
+
+`Loader` and `useLoader` for the same module return the **same signal**, so a layout's data and a child's read of it are one value. A child can update it after a mutation without a round-trip:
+
+```typescript
+import { userData } from "./Layout.js";
+import { touch } from "@mauroandre/velojs/hooks";
+
+const handleSave = async () => {
+    const saved = await action_save({ body: { name: name.value } });
+    userData.value!.name = saved.name;   // you already know the result
+    touch(userData);                      // notify — see the hooks doc
+};
+```
+
+Or let the server recompute, when the new state isn't something the client can derive:
+
+```typescript
+import { refetch } from "./Layout.js";
+await action_reset({ body: { id } });
+refetch();                                // e.g. aggregate counters
+```
+
+> **Never mirror loader data into a module-level `export let`.** On the server, a module binding is per-process, not per-request — a value stored there belongs to whichever request wrote it last. `Loader`'s server value is an AsyncLocalStorage getter, so it is per-request by construction. That's the whole reason the handle is safe to export.
+
+## When to use which
+
+| Scenario | Use |
+|----------|-----|
+| Page-specific data (list of users, post details) | `useLoader` |
+| Data another module reads (a layout's list, the current record) | `Loader` |
+| Data that changes when the route's params change | either — automatic |
+| Data that depends on a query string or client state | `useLoader` with deps |
+| Refresh after a mutation | `refetch()` (server recomputes) or `touch()` (you already know) |
+
+## How data flows
+
+Understanding the data flow helps you debug issues:
+
+**First page load (SSR):**
+1. All loaders in the route hierarchy run in parallel on the server
+2. The server injects every module's data into the HTML as `window.__PAGE_DATA__`, keyed by module
+3. `useLoader()` and `Loader()` read it — non-destructively, so any number of components can read the same module
+
+**Client-side navigation (SPA):**
+1. User clicks a link
+2. VeloJS compares each module's route pattern against the new URL and marks stale the ones whose **declared params** changed
+3. One `?_data=1` request serves all of them
+4. Only the stale modules are written — a module the client owns locally (a filtered list, an optimistic edit) is left alone
+
+That last point is why a layout at `/admin/empresas` keeps a filtered list while you navigate among its children: its route declares no param, so nothing invalidates it.

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

@@ -0,0 +1,143 @@
+---
+name: velojs-middlewares
+description: "Route middleware: auth guards, redirects, per-route server logic, passing values via `c.set`/`c.get`. Use when protecting a route, requiring login, checking permissions, or running server logic before a page or action."
+---
+
+# Middlewares
+
+Middlewares are server-side functions that run before your loaders and actions. They're perfect for authentication, authorization, logging, and other cross-cutting concerns. The Vite plugin automatically removes them from the client bundle.
+
+## Creating a middleware
+
+Use `createMiddleware` from `@mauroandre/velojs/factory`. It wraps Hono's middleware API:
+
+```typescript
+// app/modules/auth/auth.middleware.ts
+import { createMiddleware } from "@mauroandre/velojs/factory";
+import { getCookie } from "@mauroandre/velojs/cookie";
+
+export const authMiddleware = createMiddleware(async (c, next) => {
+    const token = getCookie(c, "session");
+
+    if (!token) {
+        // No token: redirect GET requests, return 401 for API calls
+        if (c.req.method === "GET") return c.redirect("/login");
+        return c.json({ error: "unauthorized" }, 401);
+    }
+
+    // Verify the token and attach user data to the context
+    const user = await verifyToken(token);
+    c.set("user", user);
+
+    // Continue to the next middleware or handler
+    await next();
+});
+```
+
+## Using in routes
+
+Add the `middlewares` property to any route node. All children of that node will inherit the middleware:
+
+```typescript
+export default [
+    {
+        module: Root,
+        isRoot: true,
+        children: [
+            // Public routes — no middleware
+            {
+                module: AuthLayout,
+                children: [
+                    { path: "/login", module: Login },
+                ],
+            },
+            // Protected routes — authMiddleware applies to everything below
+            {
+                module: AdminLayout,
+                middlewares: [authMiddleware],
+                children: [
+                    { path: "/", module: Dashboard },
+                    { path: "/stacks", module: Stacks },
+
+                    // Admin-only routes — both middlewares apply
+                    {
+                        path: "/master",
+                        module: MasterLayout,
+                        middlewares: [masterMiddleware],
+                        children: [
+                            { path: "/workers", module: Workers },
+                            { path: "/settings", module: Settings },
+                        ],
+                    },
+                ],
+            },
+        ],
+    },
+] satisfies AppRoutes;
+```
+
+## Inheritance
+
+Middlewares **accumulate** from parent to child. In the example above:
+
+- `/` and `/stacks` → only `authMiddleware` runs
+- `/master/workers` and `/master/settings` → `authMiddleware` runs first, then `masterMiddleware`
+
+### What middlewares protect
+
+A middleware on a layout guards **every request** that reaches a nested route, including:
+
+| Request type | URL pattern | When it happens |
+|--------------|-------------|-----------------|
+| Page load | `GET /stacks` | User opens the page directly (first visit, refresh) |
+| Data fetch | `GET /stacks?_data=1` | SPA navigation — `useLoader` fetches JSON |
+| Action call | `POST /_action/admin/Stacks/delete` | User triggers a server action |
+
+You don't need to add the middleware to each route manually — declaring it once on the layout covers all three paths automatically. This is especially important for authentication: without it, your API endpoints could be reached even if the page itself is protected.
+
+### Example: protecting an action via layout middleware
+
+```typescript
+// app/routes.tsx
+{
+    module: AdminLayout,
+    middlewares: [authMiddleware],
+    children: [
+        { path: "/stacks", module: Stacks },
+    ],
+}
+```
+
+```typescript
+// app/admin/Stacks.tsx
+export const action_delete = async ({ body, c }: ActionArgs<{ id: string }>) => {
+    // authMiddleware already ran — user is guaranteed to be authenticated
+    const user = c!.get("user");
+    // ... delete logic
+};
+```
+
+When the client calls `action_delete({ body: { id: "abc" } })`, it hits `POST /_action/admin/Stacks/delete`. Hono runs `authMiddleware` before the action executes. If the middleware returns an error (e.g., 401), the action never runs.
+
+## Sharing data between middleware and handlers
+
+Use Hono's `c.set()` in the middleware and `c.get()` in your loaders and actions:
+
+```typescript
+// Middleware sets the user
+c.set("user", { id: "123", name: "Mauro", role: "master" });
+
+// Loader reads it
+export const loader = async ({ c }: LoaderArgs) => {
+    const user = c.get("user");
+    return { greeting: `Hello, ${user.name}` };
+};
+
+// Action reads it
+export const action_save = async ({ body, c }: ActionArgs<{ name: string }>) => {
+    const user = c!.get("user");
+    // user is available here
+};
+```
+
+This is the recommended pattern for passing authentication data (current user, permissions, etc) from middleware to your page code.