create-veap 0.1.4 → 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/bin/veap.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { createRequire } from "module";
+
 const require = createRequire(import.meta.url);
 
 // We run the compiled CLI from dist

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

@@ -2,12 +2,12 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import ora from "ora";
-import { processStubs } from "../utils.js";
+import { appendGitignore, clearAppDirectory, injectVeapDependencies, writeEnvFile, } from "../mutate.js";
 import { applyPackageManager, pmInstall, pmRunCommand, resolvePackageManager, } from "../package-manager.js";
-import { scaffoldNextApp } from "../scaffold.js";
-import { promptConfirm, promptProjectName } from "../prompts.js";
 import { parseProjectName, projectNameError } from "../project-name.js";
-import { appendGitignore, clearAppDirectory, injectVeapDependencies, writeEnvFile, } from "../mutate.js";
+import { promptConfirm, promptProjectName } from "../prompts.js";
+import { scaffoldNextApp } from "../scaffold.js";
+import { processStubs } from "../utils.js";
 export async function initProject(name, options) {
     // ---- Resolve the project name: from the CLI argument or the interactive
     // prompt (which resolves to a default on non-TTY, so scripts never hang).
@@ -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 {
@@ -75,7 +74,6 @@ export async function initProject(name, options) {
             path.join(destDir, "public"),
             path.join(destDir, "storage"),
             path.join(destDir, "plugins"),
-            path.join(destDir, "templates"),
         ]) {
             if (!fs.existsSync(dir)) {
                 fs.mkdirSync(dir, { recursive: true });

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).
@@ -53,13 +90,12 @@ export function detectPackageManager(dir) {
         return {
             pm: "pnpm",
             source: "lockfile",
-            detail: `multiple lockfiles found: ${found
-                .map((l) => l.file)
-                .join(", ")}`,
+            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" };
@@ -76,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));
@@ -125,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);
@@ -142,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:
@@ -189,11 +252,11 @@ export function applyPackageManager(projectDir, pm) {
         // undefined in package.json to avoid a shadowing duplicate). Written
         // only when missing - an existing one is the source of truth.
         if (!fs.existsSync(pnpmWorkspace)) {
-            fs.writeFileSync(pnpmWorkspace, 'packages:\n  - "plugins/*"\n  - "templates/*"\n', "utf-8");
+            fs.writeFileSync(pnpmWorkspace, 'packages:\n  - "plugins/*"\n', "utf-8");
         }
     }
     else {
-        pkg.workspaces = ["plugins/*", "templates/*"];
+        pkg.workspaces = ["plugins/*"];
         if (fs.existsSync(pnpmWorkspace)) {
             // Switching away from pnpm: the file would shadow the workspaces field.
             fs.rmSync(pnpmWorkspace);

package/package.json

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

package/stubs/docker/.dockerignore.stub

@@ -1,39 +1,39 @@
-node_modules/
-.pnpm-store/
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-pnpm-debug.log*
-
-.next/
-out/
-dist/
-build/
-.vercel/
-
-coverage/
-*.test.*
-*.spec.*
-
-.git/
-.gitignore
-.vscode/
-.idea/
-*.swp
-*.log
-
-.env
-.env*.local
-
-Dockerfile*
-.dockerignore
-compose.yaml
-compose.yml
-
-*.md
-docs/
-
-.turbo/
-.tmp/
-.temp/
-.DS_Store
+node_modules/
+.pnpm-store/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+.next/
+out/
+dist/
+build/
+.vercel/
+
+coverage/
+*.test.*
+*.spec.*
+
+.git/
+.gitignore
+.vscode/
+.idea/
+*.swp
+*.log
+
+.env
+.env*.local
+
+Dockerfile*
+.dockerignore
+compose.yaml
+compose.yml
+
+*.md
+docs/
+
+.turbo/
+.tmp/
+.temp/
+.DS_Store

package/stubs/docker/Dockerfile.stub

@@ -1,49 +1,49 @@
-# Stage 1: Base image with pnpm
-FROM node:22-alpine AS base
-RUN apk add --no-cache libc6-compat
-ENV PNPM_HOME="/pnpm"
-ENV PATH="$PNPM_HOME:$PATH"
-
-RUN corepack enable
-RUN corepack prepare pnpm@10.29.3 --activate
-
-# Stage 2: Install dependencies
-FROM base AS deps
-WORKDIR /app
-COPY . .
-RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
-    pnpm config set store-dir /pnpm/store && \
-    pnpm config set fetch-retries 10 && \
-    pnpm config set fetch-retry-maxtimeout 120000 && \
-    pnpm config set fetch-timeout 600000 && \
-    pnpm install --frozen-lockfile
-
-# Stage 3: Build the project
-FROM base AS builder
-WORKDIR /app
-COPY --from=deps /app ./
-RUN pnpm build
-
-# Stage 4: Production runner
-FROM base AS runner
-WORKDIR /app
-
-ENV NODE_ENV=production
-ENV NEXT_TELEMETRY_DISABLED=1
-
-RUN addgroup --system --gid 1001 nodejs
-RUN adduser --system --uid 1001 nextjs
-
-# Automatically leverage output traces to reduce image size
-COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
-COPY --from=builder --chown=nextjs:nodejs /app/.next/static .next/static
-COPY --from=builder --chown=nextjs:nodejs /app/public public
-
-USER nextjs
-
-EXPOSE 3000
-
-ENV PORT=3000
-ENV HOSTNAME="0.0.0.0"
-
-CMD ["node", "./server.js"]
+# Stage 1: Base image with pnpm
+FROM node:22-alpine AS base
+RUN apk add --no-cache libc6-compat
+ENV PNPM_HOME="/pnpm"
+ENV PATH="$PNPM_HOME:$PATH"
+
+RUN corepack enable
+RUN corepack prepare pnpm@10.29.3 --activate
+
+# Stage 2: Install dependencies
+FROM base AS deps
+WORKDIR /app
+COPY . .
+RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
+    pnpm config set store-dir /pnpm/store && \
+    pnpm config set fetch-retries 10 && \
+    pnpm config set fetch-retry-maxtimeout 120000 && \
+    pnpm config set fetch-timeout 600000 && \
+    pnpm install --frozen-lockfile
+
+# Stage 3: Build the project
+FROM base AS builder
+WORKDIR /app
+COPY --from=deps /app ./
+RUN pnpm build
+
+# Stage 4: Production runner
+FROM base AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nextjs
+
+# Automatically leverage output traces to reduce image size
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static .next/static
+COPY --from=builder --chown=nextjs:nodejs /app/public public
+
+USER nextjs
+
+EXPOSE 3000
+
+ENV PORT=3000
+ENV HOSTNAME="0.0.0.0"
+
+CMD ["node", "./server.js"]

package/stubs/docker/compose.yml.stub

@@ -1,58 +1,58 @@
-services:
-  # Node.js service (use with: docker compose up {{name}} --build)
-  {{name}}:
-    build:
-      context: .
-      dockerfile: Dockerfile
-    image: {{name}}-image
-    container_name: {{name}}
-    env_file:
-      - .env
-    environment:
-      NODE_ENV: production
-      PORT: "3000"
-      NEXT_TELEMETRY_DISABLED: "1"
-      DATABASE_URL: "postgresql://postgres:postgres@database:5432/postgres?sslmode=disable"
-    depends_on:
-      database:
-        condition: service_healthy
-      redis:
-        condition: service_started
-    ports:
-      - "80:3000"
-    restart: unless-stopped
-    volumes:
-      - ./storage:/app/public/storage
-
-  # PostgreSQL service
-  database:
-    image: postgres:17-alpine
-    container_name: {{name}}-db
-    restart: always
-    environment:
-      POSTGRES_USER: postgres
-      POSTGRES_PASSWORD: postgres
-      POSTGRES_DB: postgres
-    ports:
-      - "5432:5432"
-    volumes:
-      - postgres_data:/var/lib/postgresql/data
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U postgres -d postgres"]
-      interval: 5s
-      timeout: 5s
-      retries: 5
-
-  # Redis service
-  redis:
-    image: redis:7-alpine
-    container_name: {{name}}-redis
-    restart: always
-    ports:
-      - "6379:6379"
-    volumes:
-      - redis_data:/data
-
-volumes:
-  postgres_data:
-  redis_data:
+services:
+  # Node.js service (use with: docker compose up {{name}} --build)
+  {{name}}:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: {{name}}-image
+    container_name: {{name}}
+    env_file:
+      - .env
+    environment:
+      NODE_ENV: production
+      PORT: "3000"
+      NEXT_TELEMETRY_DISABLED: "1"
+      DATABASE_URL: "postgresql://postgres:postgres@database:5432/postgres?sslmode=disable"
+    depends_on:
+      database:
+        condition: service_healthy
+      redis:
+        condition: service_started
+    ports:
+      - "80:3000"
+    restart: unless-stopped
+    volumes:
+      - ./storage:/app/public/storage
+
+  # PostgreSQL service
+  database:
+    image: postgres:17-alpine
+    container_name: {{name}}-db
+    restart: always
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: postgres
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  # Redis service
+  redis:
+    image: redis:7-alpine
+    container_name: {{name}}-redis
+    restart: always
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis_data:/data
+
+volumes:
+  postgres_data:
+  redis_data: