create-veap 0.3.0 → 0.3.1

package/README.md

@@ -1,3 +1,74 @@
 # create-veap
 
-Initializer for Veap Framework applications. Scaffolds a full plugin-enabled Veap project on top of the official create-next-app.
+The official project initializer for [Veap Framework](https://veap.pl) applications. Scaffolds a full plugin-enabled Veap project on top of the official `create-next-app`.
+
+## Quickstart
+
+Initialize a new Veap project using your preferred package manager:
+
+```bash
+# Using Bun (recommended)
+bun create veap my-app
+
+# Using pnpm
+pnpm create veap my-app
+
+# Using npm
+npm create veap my-app
+
+# Using Yarn
+yarn create veap my-app
+```
+
+Or execute directly through a package runner:
+
+```bash
+bunx create-veap my-app
+# or
+npx create-veap my-app
+```
+
+When you omit the project name in an interactive terminal, `create-veap` prompts for a project name and optional Docker configuration.
+
+## Command options
+
+| Flag             | Description                                                                  |
+| ---------------- | ---------------------------------------------------------------------------- |
+| `--docker`       | Generate Docker configuration (`Dockerfile`, `compose.yml`, `.dockerignore`). |
+| `--no-docker`    | Skip Docker configuration without prompting.                                |
+| `--skip-install` | Do not run the package manager install step.                                 |
+| `--pm <manager>` | Specify package manager (`bun`, `pnpm`, `npm`, `yarn`).                      |
+| `--pnpm`         | Force pnpm as package manager.                                              |
+| `--bun`          | Force Bun as package manager.                                               |
+| `--npm`          | Force npm as package manager.                                               |
+| `--yarn`         | Force Yarn as package manager.                                              |
+
+### Automatic package manager detection
+
+`create-veap` automatically detects the package manager from the execution command (`bun create`, `pnpm create`, `npm create`, `yarn create`, `bunx`, or `npx`) and environment variables without prompting.
+
+If you want to use a different package manager than the runner (for example, executing via Bun while configuring the generated project for pnpm), pass the target package manager flag:
+
+```bash
+bun create veap my-app --pnpm
+```
+
+## What it scaffolds
+
+- Next.js 16 App Router with React Server Components, TypeScript, and Tailwind CSS v4.
+- Veap overlay with virtual routing (`app/[[...catchAll]]/page.tsx` and `app/api/[...catchAll]/route.ts`).
+- Service provider composition root in `lib/veap.ts`.
+- Workspace configuration for plugins (`plugins/` directory).
+- Default environment configuration (`.env`) with generated `ENCRYPTION_KEY` and local SQLite database.
+- Agent instructions (`AGENTS.md`) and project guide (`README.md`).
+
+## Documentation
+
+For full documentation and guides, visit:
+- [https://veap.pl/docs](https://veap.pl/docs)
+- [Installation Guide](https://veap.pl/docs/getting-started/installation)
+- [CLI Reference](https://veap.pl/docs/reference/cli)
+
+## License
+
+MIT

package/dist/commands/init.d.ts

@@ -1,5 +1,5 @@
-export declare function initProject(name?: string, options?: {
+import { type ResolvePackageManagerOptions } from "../package-manager.js";
+export declare function initProject(name?: string, options?: ResolvePackageManagerOptions & {
     docker?: boolean;
     skipInstall?: boolean;
-    pm?: string;
 }): Promise<void>;

package/dist/commands/init.js

@@ -32,9 +32,8 @@ export async function initProject(name, options) {
     if (withDocker === undefined) {
         withDocker = await promptConfirm("Include Docker configuration?", false);
     }
-    // Resolve the package manager up front so the prompt runs before any
-    // scaffolding starts (cleaner UX than asking mid-scaffold).
-    const pm = await resolvePackageManager({ pm: options?.pm });
+    // Resolve the package manager automatically (or from flags)
+    const pm = await resolvePackageManager(options);
     const overlayFolder = "../../stubs/overlay-full";
     console.log(`🚀 Initializing new Veap project (Full plugin-enabled): ${projectName} in ${destDir}...`);
     try {

package/dist/index.js

@@ -5,8 +5,13 @@ const cli = cac("create-veap");
 cli
     .command("[name]", "Initialize a new Veap project (asks for details when omitted)")
     .option("--docker", "Initialize Docker configuration")
+    .option("--no-docker", "Skip Docker configuration")
     .option("--skip-install", "Skip dependencies installation")
     .option("--pm <manager>", "Package manager to use: pnpm, npm, yarn or bun (auto-detected when omitted)")
+    .option("--pnpm, --use-pnpm", "Use pnpm as package manager")
+    .option("--bun, --use-bun", "Use bun as package manager")
+    .option("--npm, --use-npm", "Use npm as package manager")
+    .option("--yarn, --use-yarn", "Use yarn as package manager")
     .action(async (name, options) => {
     await initProject(name, options);
 });

package/dist/package-manager.d.ts

@@ -7,6 +7,15 @@ export interface PackageManagerDetection {
     /** Human-readable detail, e.g. "pnpm@11.9.0" or "pnpm-lock.yaml". */
     detail?: string;
 }
+/**
+ * Detects the package manager currently executing the process.
+ *
+ * Inspects:
+ * 1. `npm_config_user_agent` (set when invoked via npx, bunx, pnpm dlx, yarn create)
+ * 2. `process.versions.bun` (running directly inside Bun runtime)
+ * 3. `npm_execpath` (path containing the binary name)
+ */
+export declare function detectRunningPackageManager(env?: NodeJS.ProcessEnv, versions?: NodeJS.ProcessVersions): PackageManager | null;
 /**
  * Detects the package manager to default to by inspecting `dir` (usually the
  * directory the scaffolding command was launched from).
@@ -18,22 +27,32 @@ export declare function detectPackageManager(dir: string): PackageManagerDetecti
  * Interactive numbered-choice prompt rendered on readline (no external
  * prompt library, matching the rest of this CLI).
  *
- * The detected package manager is listed first as the default; pressing
- * Enter accepts it. Accepts a number (1-4) or a name (`pnpm`, `npm`,
- * `yarn`, `bun`). On EOF / closed stdin (piped input, CI) resolves to the
- * detected default instead of hanging.
+ * Kept as a fallback helper.
  */
 export declare function promptPackageManager(detection: PackageManagerDetection): Promise<PackageManager>;
+export interface ResolvePackageManagerOptions {
+    pm?: string;
+    pnpm?: boolean;
+    bun?: boolean;
+    npm?: boolean;
+    yarn?: boolean;
+    usePnpm?: boolean;
+    useBun?: boolean;
+    useNpm?: boolean;
+    useYarn?: boolean;
+}
 /**
  * Resolves the package manager to use for a new project.
  *
- * Order: explicit `--pm <name>` flag (validated hard - scripts must not hang
- * on a prompt) → interactive prompt (TTY only) → auto-detected default
- * (non-TTY, CI).
+ * Priority:
+ * 1. Explicit manager flag: `--pnpm`, `--bun`, `--npm`, `--yarn`
+ * 2. Explicit `--pm <name>` flag
+ * 3. Auto-detected from currently running environment (e.g. `bun create`, `pnpm dlx`, `npx`)
+ * 4. Auto-detected from current directory (packageManager field, lockfiles, or default)
+ *
+ * Automatically resolves without prompting.
  */
-export declare function resolvePackageManager(options?: {
-    pm?: string;
-}): Promise<PackageManager>;
+export declare function resolvePackageManager(options?: ResolvePackageManagerOptions, cwd?: string): Promise<PackageManager>;
 /**
  * Applies the chosen package manager to the freshly scaffolded project:
  *

package/dist/package-manager.js

@@ -21,6 +21,43 @@ const LOCKFILES = [
     { file: "package-lock.json", pm: "npm" },
 ];
 const isPackageManager = (value) => PACKAGE_MANAGERS.includes(value);
+/**
+ * Detects the package manager currently executing the process.
+ *
+ * Inspects:
+ * 1. `npm_config_user_agent` (set when invoked via npx, bunx, pnpm dlx, yarn create)
+ * 2. `process.versions.bun` (running directly inside Bun runtime)
+ * 3. `npm_execpath` (path containing the binary name)
+ */
+export function detectRunningPackageManager(env = process.env, versions = process.versions) {
+    const userAgent = env.npm_config_user_agent;
+    if (userAgent) {
+        if (userAgent.startsWith("pnpm"))
+            return "pnpm";
+        if (userAgent.startsWith("bun"))
+            return "bun";
+        if (userAgent.startsWith("yarn"))
+            return "yarn";
+        if (userAgent.startsWith("npm"))
+            return "npm";
+    }
+    // Running directly under Bun runtime (e.g. `bun create veap` or `bunx create-veap`)
+    if (typeof versions?.bun === "string") {
+        return "bun";
+    }
+    const execPath = env.npm_execpath;
+    if (execPath) {
+        if (execPath.includes("pnpm"))
+            return "pnpm";
+        if (execPath.includes("bun"))
+            return "bun";
+        if (execPath.includes("yarn"))
+            return "yarn";
+        if (execPath.includes("npm"))
+            return "npm";
+    }
+    return null;
+}
 /**
  * Detects the package manager to default to by inspecting `dir` (usually the
  * directory the scaffolding command was launched from).
@@ -56,8 +93,9 @@ export function detectPackageManager(dir) {
             detail: `multiple lockfiles found: ${found.map((l) => l.file).join(", ")}`,
         };
     }
-    if (found.length === 1) {
-        return { pm: found[0].pm, source: "lockfile", detail: found[0].file };
+    const first = found[0];
+    if (found.length === 1 && first) {
+        return { pm: first.pm, source: "lockfile", detail: first.file };
     }
     // 3. Framework default
     return { pm: "pnpm", source: "default" };
@@ -74,10 +112,7 @@ function formatDetection(d) {
  * Interactive numbered-choice prompt rendered on readline (no external
  * prompt library, matching the rest of this CLI).
  *
- * The detected package manager is listed first as the default; pressing
- * Enter accepts it. Accepts a number (1-4) or a name (`pnpm`, `npm`,
- * `yarn`, `bun`). On EOF / closed stdin (piped input, CI) resolves to the
- * detected default instead of hanging.
+ * Kept as a fallback helper.
  */
 export async function promptPackageManager(detection) {
     console.log(formatDetection(detection));
@@ -123,8 +158,11 @@ export async function promptPackageManager(detection) {
                 if (String(asNumber) === value &&
                     asNumber >= 1 &&
                     asNumber <= PACKAGE_MANAGERS.length) {
-                    finish(PACKAGE_MANAGERS[asNumber - 1]);
-                    return;
+                    const chosen = PACKAGE_MANAGERS[asNumber - 1];
+                    if (chosen) {
+                        finish(chosen);
+                        return;
+                    }
                 }
                 if (isPackageManager(value)) {
                     finish(value);
@@ -140,25 +178,52 @@ export async function promptPackageManager(detection) {
 /**
  * Resolves the package manager to use for a new project.
  *
- * Order: explicit `--pm <name>` flag (validated hard - scripts must not hang
- * on a prompt) → interactive prompt (TTY only) → auto-detected default
- * (non-TTY, CI).
+ * Priority:
+ * 1. Explicit manager flag: `--pnpm`, `--bun`, `--npm`, `--yarn`
+ * 2. Explicit `--pm <name>` flag
+ * 3. Auto-detected from currently running environment (e.g. `bun create`, `pnpm dlx`, `npx`)
+ * 4. Auto-detected from current directory (packageManager field, lockfiles, or default)
+ *
+ * Automatically resolves without prompting.
  */
-export async function resolvePackageManager(options) {
-    const detection = detectPackageManager(process.cwd());
+export async function resolvePackageManager(options, cwd = process.cwd()) {
+    // 1. Explicit boolean flags: --pnpm, --bun, --npm, --yarn
+    if (options?.pnpm || options?.usePnpm) {
+        console.log("📦 Using package manager: pnpm (specified via --pnpm flag)");
+        return "pnpm";
+    }
+    if (options?.bun || options?.useBun) {
+        console.log("📦 Using package manager: bun (specified via --bun flag)");
+        return "bun";
+    }
+    if (options?.npm || options?.useNpm) {
+        console.log("📦 Using package manager: npm (specified via --npm flag)");
+        return "npm";
+    }
+    if (options?.yarn || options?.useYarn) {
+        console.log("📦 Using package manager: yarn (specified via --yarn flag)");
+        return "yarn";
+    }
+    // 2. Explicit --pm <name> flag
     if (options?.pm) {
         const requested = options.pm.trim().toLowerCase();
         if (isPackageManager(requested)) {
+            console.log(`📦 Using package manager: ${requested} (specified via --pm flag)`);
             return requested;
         }
         console.error(`Error: Unknown package manager "${options.pm}". Allowed: ${PACKAGE_MANAGERS.join(", ")}.`);
         process.exit(1);
     }
-    if (!process.stdin.isTTY) {
-        console.log(`📦 Using ${detection.pm} (auto-detected${detection.detail ? `: ${detection.detail}` : ""})`);
-        return detection.pm;
+    // 3. Auto-detected from currently running execution environment
+    const running = detectRunningPackageManager();
+    if (running) {
+        console.log(`📦 Package manager detected: ${running} (from running environment)`);
+        return running;
     }
-    return promptPackageManager(detection);
+    // 4. Auto-detected from directory context or framework default
+    const detection = detectPackageManager(cwd);
+    console.log(formatDetection(detection));
+    return detection.pm;
 }
 /**
  * Applies the chosen package manager to the freshly scaffolded project:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-veap",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Initializer for Veap Framework applications",
   "bugs": "https://github.com/veapjs/create-veap/issues",
   "repository": {

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/lib/veap.ts.stub

@@ -1,7 +1,7 @@
 import { cache } from "react";
 import { Application } from "@veap/framework/core/server";
 
-import { appMigrations } from "../migrations";
+import { migrations } from "../migrations";
 import { plugins } from "./plugins.gen";
 import { SiteLayout } from "../components/site-layout";
 
@@ -14,7 +14,7 @@ export const app = Application.configure()
   .withRouter()
   .withSiteLayout(SiteLayout)
   .withSettings()
-  .withMigrations(appMigrations)
+  .withMigrations(migrations)
   .withPlugins(plugins)
   .create();
 

package/stubs/overlay-full/migrations/index.ts.stub

@@ -1,2 +1,2 @@
 // This file is auto-generated by Veap CLI. Do not edit manually.
-export const appMigrations: any[] = [];
+export const migrations: any[] = [];

package/stubs/overlay-full/next.config.ts.stub

@@ -14,6 +14,16 @@ const nextConfig: NextConfig = {
     turbopackRustReactCompiler: true
   },
 
+  // @tailwindcss/turbopack support
+  turbopack: {
+    rules: {
+      "*.css": {
+        loaders: ["@tailwindcss/turbopack"],
+        as: "*.css",
+      },
+    },
+  },
+  
   outputFileTracingIncludes: {
     "/**/*": ["veap.config.ts"],
   },