create-veap 0.1.4 → 0.3.1

package/stubs/overlay-full/AGENTS.md.stub

@@ -11,7 +11,7 @@ This project is a **Veap** application: the official `create-next-app` base plus
 - `app/[[...catchAll]]/page.tsx` - every page render goes through `VeapRouter` (route tree built from plugins + app routes). Do not add competing page routes without understanding the router.
 - `app/api/[...catchAll]/route.ts` - API pipeline: middlewares, auth, roles/permissions resolved from the route tree.
 - `app/layout.tsx`, `app/not-found.tsx` - root shell with the bootstrap and the **force-dynamic contract (below)**.
-- `plugins/`, `templates/` - workspace packages (pnpm workspace / npm workspaces).
+- `plugins/` - workspace packages (pnpm workspace / npm workspaces).
 - `migrations/` - app migrations (`veap make:migration`).
 
 ## Critical Contracts (do not break)

package/stubs/overlay-full/README.md.stub

@@ -0,0 +1,132 @@
+# {{name}}
+
+A modern full-stack web application built with [Veap](https://veap.pl) and Next.js 16 (App Router & React Server Components).
+
+## What is Veap?
+
+**Veap** is a modular application framework built on top of the Next.js App Router. It combines Next.js frontend flexibility with robust, enterprise-grade backend architectural primitives:
+
+- **Clean Architecture & Service Providers**: Inversion of control container and modular service providers configured in `lib/veap.ts`.
+- **Virtual Routing**: Dynamic route tree serving installed plugin routes and application routes through `app/[[...catchAll]]/page.tsx` and `app/api/[...catchAll]/route.ts`.
+- **Plugin System**: Isolated, composable packages located in `plugins/` with declarative extensions and widgets.
+- **ActiveRecord ORM**: Eloquent-style models and query builder backed by Knex with transactions and migrations.
+- **Authentication & RBAC**: Built-in session management, user models, role-based access control, and password hashing.
+- **Storage & Communication**: Unified file storage drivers and mail transports.
+
+---
+
+## Getting Started
+
+### 1. Requirements
+
+- **Node.js** `>= 22` or **Bun** `>= 1.2`
+- Supported package managers: `bun`, `pnpm`, `npm`, or `yarn`
+
+### 2. Environment Configuration
+
+During project initialization, a default `.env` file is generated with a secure random `ENCRYPTION_KEY` and a local SQLite database configuration:
+
+```bash
+DATABASE_CLIENT=sqlite3
+DATABASE_URL=./storage/veap.sqlite
+ENCRYPTION_KEY=<generated-key>
+```
+
+> **Important**: The application enforces fail-fast verification on `ENCRYPTION_KEY`. Never commit `.env` to version control.
+
+### 3. Run the Development Server
+
+Start the local development server:
+
+```bash
+# Using bun
+bun dev
+
+# Or using pnpm
+pnpm dev
+
+# Or using npm
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to view the application.
+
+---
+
+## Available Scripts
+
+| Command | Description |
+| --- | --- |
+| `bun dev` | Starts the Next.js development server with Turbopack |
+| `bun run build` | Builds the application for production |
+| `bun run start` | Runs the production build |
+| `bun run lint` | Runs ESLint checks |
+
+*(Replace `bun` with `pnpm` or `npm run` depending on your package manager)*
+
+---
+
+## Veap CLI
+
+The `veap` CLI manages plugins, database migrations, and framework components:
+
+```bash
+# Add and register a plugin package
+veap add <plugin-name>
+
+# Scaffold a new workspace plugin in plugins/
+veap make:plugin <plugin-name>
+
+# Create a new database migration
+veap make:migration <migration-name>
+
+# Scaffold a new site layout template
+veap make:template <template-name>
+
+# Re-synchronize and generate lib/plugins.gen.ts
+veap register
+
+# Generate Docker deployment configuration
+veap docker
+```
+
+---
+
+## Project Structure
+
+```
+├── app/
+│   ├── (site)/             # Declarative site layout route group
+│   ├── [[...catchAll]]/    # Veap virtual page router
+│   ├── api/[...catchAll]/  # Veap API pipeline (middlewares, RBAC, auth)
+│   ├── storage/            # Local storage route handler
+│   ├── layout.tsx          # Root layout shell with force-dynamic bootstrap
+│   └── globals.css         # Tailwind CSS styling
+├── components/             # Reusable UI components (SiteLayout, Navbar, Footer)
+├── lib/
+│   ├── veap.ts             # Composition root: Application configuration & bootstrap
+│   └── plugins.gen.ts      # Generated plugin registry (managed by veap register)
+├── migrations/             # Database migrations
+├── plugins/                # Local workspace plugins
+├── storage/                # Local SQLite database & uploaded files
+├── AGENTS.md               # AI coding agent instructions and architectural contracts
+└── next.config.ts          # Next.js configuration with Veap & Turbopack support
+```
+
+---
+
+## Documentation & Resources
+
+Explore the official Veap documentation to learn more about architecture, plugins, and guides:
+
+- **Official Website**: [https://veap.pl](https://veap.pl)
+- **Documentation**: [https://veap.pl/docs](https://veap.pl/docs)
+  - [Getting Started](https://veap.pl/docs/getting-started/introduction)
+  - [Architecture & Fundamentals](https://veap.pl/docs/fundamentals/architecture)
+  - [Virtual Routing & Middleware](https://veap.pl/docs/routing/routing)
+  - [Database & ORM](https://veap.pl/docs/data/database)
+  - [Authentication & RBAC](https://veap.pl/docs/auth)
+  - [Authoring Plugins](https://veap.pl/docs/plugins/creating-plugins)
+  - [CLI Reference](https://veap.pl/docs/reference/cli)
+- **GitHub Repository**: [https://github.com/veapjs/veap](https://github.com/veapjs/veap)
+- **Community Discussions**: [https://github.com/veapjs/veap/discussions](https://github.com/veapjs/veap/discussions)

package/stubs/overlay-full/app/(site)/layout.tsx.stub

@@ -0,0 +1,10 @@
+import { SiteLayout } from "@/components/site-layout";
+import type { ReactNode } from "react";
+
+export default function NativeSiteLayout({
+  children,
+}: {
+  children: ReactNode;
+}) {
+  return <SiteLayout>{children}</SiteLayout>;
+}

package/stubs/overlay-full/app/[[...catchAll]]/page.tsx.stub

@@ -1,47 +1,47 @@
-import { VeapRouter } from "@veap/framework/router";
-import { buildRouteTree } from "@veap/framework/router/server";
-import type { Metadata } from "next";
-import { initializeSystem } from "@/lib/veap";
-
-export const dynamic = "force-dynamic";
-
-export async function generateMetadata({
-  params,
-  searchParams,
-}: {
-  params: Promise<{ catchAll?: string[] }>;
-  searchParams: Promise<Record<string, string>>;
-}): Promise<Metadata> {
-  const { catchAll } = await params;
-  const sParams = await searchParams;
-  const path = catchAll && catchAll.length > 0 ? `/${catchAll.join("/")}` : "/";
-
-  await initializeSystem();
-  const tree = await buildRouteTree(true);
-  const result = await tree.generateMetadata(path, sParams);
-
-  return result;
-}
-
-export default async function CatchAllPage({
-  params,
-  searchParams,
-}: {
-  params: Promise<{ catchAll?: string[] }>;
-  searchParams: Promise<any>;
-}) {
-  const { catchAll } = await params;
-  const sParams = await searchParams;
-  const path = catchAll && catchAll.length > 0 ? `/${catchAll.join("/")}` : "/";
-
-  await initializeSystem();
-  const tree = await buildRouteTree(true);
-
-  const result = await VeapRouter({
-    tree,
-    path,
-    searchParams: sParams,
-  });
-
-  return result;
-}
+import { VeapRouter } from "@veap/framework/router";
+import { buildRouteTree } from "@veap/framework/router/server";
+import type { Metadata } from "next";
+import { initializeSystem } from "@/lib/veap";
+
+export const dynamic = "force-dynamic";
+
+export async function generateMetadata({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ catchAll?: string[] }>;
+  searchParams: Promise<Record<string, string>>;
+}): Promise<Metadata> {
+  const { catchAll } = await params;
+  const sParams = await searchParams;
+  const path = catchAll && catchAll.length > 0 ? `/${catchAll.join("/")}` : "/";
+
+  await initializeSystem();
+  const tree = await buildRouteTree(true);
+  const result = await tree.generateMetadata(path, sParams);
+
+  return result;
+}
+
+export default async function CatchAllPage({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ catchAll?: string[] }>;
+  searchParams: Promise<any>;
+}) {
+  const { catchAll } = await params;
+  const sParams = await searchParams;
+  const path = catchAll && catchAll.length > 0 ? `/${catchAll.join("/")}` : "/";
+
+  await initializeSystem();
+  const tree = await buildRouteTree(true);
+
+  const result = await VeapRouter({
+    tree,
+    path,
+    searchParams: sParams,
+  });
+
+  return result;
+}

package/stubs/overlay-full/app/api/[...catchAll]/route.ts.stub

@@ -1,111 +1,111 @@
-import { ApiEnsuredAuth, runApiPipeline } from "@veap/framework/router/server";
-import { initializeSystem } from "@/lib/veap";
-
-export const dynamic = "force-dynamic";
-
-async function handleRequest(
-  request: Request,
-  context: { params: Promise<{ catchAll: string[] }> },
-) {
-  // Ensure system is initialized (DB injected, plugins registered)
-  await initializeSystem();
-
-  const { catchAll } = await context.params;
-  const path = `/api/${catchAll.join("/")}`;
-
-  const { buildRouteTree } = await import("@veap/framework/router/server");
-  const tree = await buildRouteTree(true);
-
-  const match = tree.match(path);
-
-  const node = match?.node as any;
-
-  if (match?.isExact && node?.route) {
-    const method = request.method.toUpperCase();
-    const handler = node.route[method] || node.route.handler;
-
-    if (handler) {
-      const middlewares = [];
-
-      // Collect middlewares from the layout chain
-      for (const entry of match.layoutChain) {
-        if (entry.middlewares) {
-          middlewares.push(...entry.middlewares);
-        }
-      }
-
-      // Node middlewares
-      if (node.middlewares) {
-        middlewares.push(...node.middlewares);
-      }
-
-      // Resolve auth from chain (closest to leaf wins)
-      let authRequired = node.auth;
-      if (authRequired === undefined) {
-        for (let i = match.layoutChain.length - 1; i >= 0; i--) {
-          if (match.layoutChain[i].auth !== undefined) {
-            authRequired = match.layoutChain[i].auth;
-            break;
-          }
-        }
-      }
-
-      // Roles and permissions
-      let roles = node.roles;
-      if (!roles) {
-        for (let i = match.layoutChain.length - 1; i >= 0; i--) {
-          if (match.layoutChain[i].roles) {
-            roles = match.layoutChain[i].roles;
-            break;
-          }
-        }
-      }
-
-      let permissions = node.permissions;
-      if (!permissions) {
-        for (let i = match.layoutChain.length - 1; i >= 0; i--) {
-          if (match.layoutChain[i].permissions) {
-            permissions = match.layoutChain[i].permissions;
-            break;
-          }
-        }
-      }
-
-      if (authRequired) {
-        middlewares.unshift(ApiEnsuredAuth);
-      }
-
-      return await runApiPipeline(
-        middlewares as any,
-        request,
-        {
-          params: match.params,
-          roles,
-          permissions,
-        },
-        async (req: Request, ctx: any) => {
-          return handler(req, ctx);
-        },
-      );
-    } else {
-      return new Response(
-        JSON.stringify({ error: `Method ${method} Not Allowed` }),
-        {
-          status: 405,
-          headers: { "Content-Type": "application/json" },
-        },
-      );
-    }
-  }
-
-  return new Response(JSON.stringify({ error: "API Route not found" }), {
-    status: 404,
-    headers: { "Content-Type": "application/json" },
-  });
-}
-
-export const GET = handleRequest;
-export const POST = handleRequest;
-export const PUT = handleRequest;
-export const PATCH = handleRequest;
-export const DELETE = handleRequest;
+import { ApiEnsuredAuth, runApiPipeline } from "@veap/framework/router/server";
+import { initializeSystem } from "@/lib/veap";
+
+export const dynamic = "force-dynamic";
+
+async function handleRequest(
+  request: Request,
+  context: { params: Promise<{ catchAll: string[] }> },
+) {
+  // Ensure system is initialized (DB injected, plugins registered)
+  await initializeSystem();
+
+  const { catchAll } = await context.params;
+  const path = `/api/${catchAll.join("/")}`;
+
+  const { buildRouteTree } = await import("@veap/framework/router/server");
+  const tree = await buildRouteTree(true);
+
+  const match = tree.match(path);
+
+  const node = match?.node as any;
+
+  if (match?.isExact && node?.route) {
+    const method = request.method.toUpperCase();
+    const handler = node.route[method] || node.route.handler;
+
+    if (handler) {
+      const middlewares = [];
+
+      // Collect middlewares from the layout chain
+      for (const entry of match.layoutChain) {
+        if (entry.middlewares) {
+          middlewares.push(...entry.middlewares);
+        }
+      }
+
+      // Node middlewares
+      if (node.middlewares) {
+        middlewares.push(...node.middlewares);
+      }
+
+      // Resolve auth from chain (closest to leaf wins)
+      let authRequired = node.auth;
+      if (authRequired === undefined) {
+        for (let i = match.layoutChain.length - 1; i >= 0; i--) {
+          if (match.layoutChain[i].auth !== undefined) {
+            authRequired = match.layoutChain[i].auth;
+            break;
+          }
+        }
+      }
+
+      // Roles and permissions
+      let roles = node.roles;
+      if (!roles) {
+        for (let i = match.layoutChain.length - 1; i >= 0; i--) {
+          if (match.layoutChain[i].roles) {
+            roles = match.layoutChain[i].roles;
+            break;
+          }
+        }
+      }
+
+      let permissions = node.permissions;
+      if (!permissions) {
+        for (let i = match.layoutChain.length - 1; i >= 0; i--) {
+          if (match.layoutChain[i].permissions) {
+            permissions = match.layoutChain[i].permissions;
+            break;
+          }
+        }
+      }
+
+      if (authRequired) {
+        middlewares.unshift(ApiEnsuredAuth);
+      }
+
+      return await runApiPipeline(
+        middlewares as any,
+        request,
+        {
+          params: match.params,
+          roles,
+          permissions,
+        },
+        async (req: Request, ctx: any) => {
+          return handler(req, ctx);
+        },
+      );
+    } else {
+      return new Response(
+        JSON.stringify({ error: `Method ${method} Not Allowed` }),
+        {
+          status: 405,
+          headers: { "Content-Type": "application/json" },
+        },
+      );
+    }
+  }
+
+  return new Response(JSON.stringify({ error: "API Route not found" }), {
+    status: 404,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+export const GET = handleRequest;
+export const POST = handleRequest;
+export const PUT = handleRequest;
+export const PATCH = handleRequest;
+export const DELETE = handleRequest;

package/stubs/overlay-full/app/error.tsx.stub

@@ -1,34 +1,34 @@
-"use client";
-
-import { useTranslation } from "@veap/framework/intl";
-import { useEffect } from "react";
-
-export default function ErrorPage({
-  error,
-  reset,
-}: {
-  error: Error & { digest?: string };
-  reset: () => void;
-}) {
-  const { t } = useTranslation();
-  useEffect(() => {
-    console.error(error);
-  }, [error]);
-
-  return (
-    <div className="flex min-h-screen flex-col items-center justify-center p-4">
-      <div className="max-w-md text-center">
-        <h2 className="text-2xl font-bold mb-4">{t("Something went wrong!")}</h2>
-        <p className="text-muted-foreground mb-6">
-          {error.message || t("An unexpected error occurred.")}
-        </p>
-        <button
-          onClick={() => reset()}
-          className="px-4 py-2 bg-primary text-primary-foreground rounded-md hover:opacity-90"
-        >
-          {t("Try Again")}
-        </button>
-      </div>
-    </div>
-  );
-}
+"use client";
+
+import { useTranslation } from "@veap/framework/intl";
+import { useEffect } from "react";
+
+export default function ErrorPage({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  const { t } = useTranslation();
+  useEffect(() => {
+    console.error(error);
+  }, [error]);
+
+  return (
+    <div className="flex min-h-screen flex-col items-center justify-center p-4">
+      <div className="max-w-md text-center">
+        <h2 className="text-2xl font-bold mb-4">{t("Something went wrong!")}</h2>
+        <p className="text-muted-foreground mb-6">
+          {error.message || t("An unexpected error occurred.")}
+        </p>
+        <button
+          onClick={() => reset()}
+          className="px-4 py-2 bg-primary text-primary-foreground rounded-md hover:opacity-90"
+        >
+          {t("Try Again")}
+        </button>
+      </div>
+    </div>
+  );
+}