create-veap 0.1.2

package/README.md

@@ -0,0 +1,3 @@
+# create-veap
+
+Initializer for Veap Framework applications. Scaffolds a full plugin-enabled Veap project on top of the official create-next-app.

package/bin/veap.js

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

package/dist/commands/docker.d.ts

@@ -0,0 +1 @@
+export declare function initDockerConfig(targetDir?: string, pm?: "pnpm" | "npm" | "yarn" | "bun"): Promise<void>;

package/dist/commands/docker.js

@@ -0,0 +1,55 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import ora from "ora";
+export async function initDockerConfig(targetDir, pm) {
+    const rootDir = targetDir || process.cwd();
+    console.log(`\n🐳 Initializing Docker configuration in ${rootDir}...`);
+    // Read project name for compose.yml placeholders (like @veap/cli does)
+    let projectName = "veap-app";
+    const pkgPath = path.join(rootDir, "package.json");
+    if (fs.existsSync(pkgPath)) {
+        try {
+            projectName =
+                JSON.parse(fs.readFileSync(pkgPath, "utf-8")).name || projectName;
+        }
+        catch (_) { }
+    }
+    const stubsDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../stubs/docker");
+    if (!fs.existsSync(stubsDir)) {
+        console.error(`Error: Missing Docker stubs directory at ${stubsDir}`);
+        return;
+    }
+    const files = [
+        { src: "Dockerfile.stub", dest: "Dockerfile" },
+        { src: ".dockerignore.stub", dest: ".dockerignore" },
+        { src: "compose.yml.stub", dest: "compose.yml" },
+    ];
+    const spin = ora("Generating Docker files...").start();
+    try {
+        for (const f of files) {
+            let content = fs.readFileSync(path.join(stubsDir, f.src), "utf-8");
+            // Replace project name in compose.yml
+            if (f.dest === "compose.yml") {
+                content = content.replace(/\{\{name\}\}/g, projectName);
+            }
+            fs.writeFileSync(path.join(rootDir, f.dest), content, "utf-8");
+        }
+        // Copy the Dockerfile variant for the chosen package manager over the
+        // pnpm baseline shipped in the stubs.
+        if (pm && pm !== "pnpm") {
+            const variantPath = path.join(stubsDir, `Dockerfile.${pm}.stub`);
+            if (fs.existsSync(variantPath)) {
+                fs.writeFileSync(path.join(rootDir, "Dockerfile"), fs.readFileSync(variantPath, "utf-8"), "utf-8");
+            }
+        }
+        spin.succeed("Docker configuration files initialized.");
+        console.log("  - Dockerfile");
+        console.log("  - compose.yml");
+        console.log("  - .dockerignore\n");
+    }
+    catch (err) {
+        spin.fail("Failed to generate Docker files.");
+        console.error(err);
+    }
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,5 @@
+export declare function initProject(name?: string, options?: {
+    docker?: boolean;
+    skipInstall?: boolean;
+    pm?: string;
+}): Promise<void>;

package/dist/commands/init.js

@@ -0,0 +1,111 @@
+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 { 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";
+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).
+    let nameInput = (name ?? "").trim();
+    if (!nameInput) {
+        nameInput = await promptProjectName("my-veap-app", process.cwd());
+    }
+    else {
+        const error = projectNameError(nameInput, process.cwd());
+        if (error) {
+            console.error(`Error: ${error}`);
+            process.exit(1);
+        }
+    }
+    // npm name rules: `@scope/name` keeps the full name in package.json while
+    // the project folder receives the base name.
+    const parsed = parseProjectName(nameInput);
+    const projectName = parsed.folder;
+    const destDir = path.resolve(process.cwd(), projectName);
+    // ---- Docker is opt-in; ask when the flag was not given (TTY only).
+    let withDocker = options?.docker;
+    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 });
+    const overlayFolder = "../../stubs/overlay-full";
+    console.log(`🚀 Initializing new Veap project (Full plugin-enabled): ${projectName} in ${destDir}...`);
+    try {
+        // ---- 1. Scaffold the Next.js shell with the official create-next-app.
+        // CNA owns the boilerplate (Next version, tsconfig, postcss, fonts,
+        // README, git init); it runs with explicit flags so it never prompts.
+        const spin = ora("Scaffolding Next.js app (create-next-app)...").start();
+        try {
+            scaffoldNextApp(projectName, { cwd: process.cwd(), pm });
+            spin.succeed("Next.js app scaffolded.");
+        }
+        catch (err) {
+            spin.fail("create-next-app failed.");
+            throw err;
+        }
+        const variables = { name: projectName };
+        // ---- 2. The overlay owns the whole app/ tree: a leftover CNA page would
+        // collide with the optional catch-all route (same specificity).
+        clearAppDirectory(destDir);
+        // ---- 3. Apply the veap overlay: only the files CNA cannot know about
+        // (veap layout, router catch-all, api pipeline, storage route, bootstrap,
+        // veap next.config...). Overlay files overwrite CNA counterparts.
+        const overlaySpin = ora("Applying Veap overlay files...").start();
+        const stubsDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), overlayFolder);
+        processStubs(stubsDir, destDir, variables);
+        overlaySpin.succeed("Veap overlay applied.");
+        // ---- 4. Mutate the generated project: veap dependencies, starter .env
+        // (with a fresh random ENCRYPTION_KEY) and .gitignore additions. Scoped
+        // names are restored into package.json here (CNA derives the name from
+        // the folder and drops the scope).
+        const mutateSpin = ora("Configuring Veap (deps, .env)...").start();
+        injectVeapDependencies(destDir, parsed.packageName);
+        writeEnvFile(destDir);
+        appendGitignore(destDir);
+        mutateSpin.succeed("Veap configuration applied.");
+        // ---- 5. Workspace and storage folders.
+        for (const dir of [
+            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 });
+            }
+        }
+        // ---- 6. Package manager: packageManager field, workspaces config,
+        // .yarnrc.yml for yarn berry.
+        applyPackageManager(destDir, pm);
+        // ---- 7. Docker configuration (optional).
+        if (withDocker) {
+            const { initDockerConfig } = await import("./docker.js");
+            await initDockerConfig(destDir, pm);
+        }
+        // ---- 8. Single dependency install, after all mutations.
+        if (!options?.skipInstall) {
+            const spinner = ora(`📦 Installing dependencies (${pm} install)...`).start();
+            try {
+                pmInstall(pm, destDir);
+                spinner.succeed("Dependencies installed.");
+            }
+            catch (_err) {
+                spinner.fail(`Failed to install dependencies automatically. Run ${pm} install manually.`);
+            }
+        }
+        console.log(`\n✨ Veap project "${projectName}" initialized successfully!`);
+        console.log(`💡 Go to project directory: cd ${projectName}`);
+        console.log(`💡 Start dev server: ${pmRunCommand(pm, "dev")}`);
+    }
+    catch (err) {
+        console.error("Error initializing project:", err);
+        process.exit(1);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { initProject } from "./commands/init.js";
+export { initProject };

package/dist/index.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import cac from "cac";
+import { initProject } from "./commands/init.js";
+const cli = cac("create-veap");
+cli
+    .command("[name]", "Initialize a new Veap project (asks for details when omitted)")
+    .option("--docker", "Initialize Docker configuration")
+    .option("--skip-install", "Skip dependencies installation")
+    .option("--pm <manager>", "Package manager to use: pnpm, npm, yarn or bun (auto-detected when omitted)")
+    .action(async (name, options) => {
+    await initProject(name, options);
+});
+cli.help();
+cli.version("0.4.0");
+cli.parse();
+export { initProject };

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+export { initProject } from "./commands/init.js";
+export type { PackageManager } from "./package-manager.js";

package/dist/main.js

@@ -0,0 +1 @@
+export { initProject } from "./commands/init.js";

package/dist/manifests.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Veap-specific dependencies layered on top of the freshly generated
+ * `create-next-app` project. The CNA-provided Next/React/TypeScript/Tailwind
+ * versions are intentionally NOT pinned here - we take whatever the official
+ * scaffolder ships, so generated apps never lag behind the framework.
+ *
+ * Only `@types/node` is overridden: the engine requirement is Node >= 22.
+ * The linter comes from CNA (`--eslint`); no Biome, no changesets.
+ */
+export interface VeapDependencyManifest {
+    dependencies: Record<string, string>;
+    devDependencies: Record<string, string>;
+    scripts?: Record<string, string>;
+}
+/**
+ * Versions deliberately pinned OVER the CNA-provided ones: the engine
+ * requirement is Node >= 22. Applied after the spread merge so CNA cannot
+ * win these keys.
+ */
+export declare const PINNED_DEV_DEPENDENCIES: Record<string, string>;
+/** Full plugin-enabled project. */
+export declare const FULL_MANIFEST: VeapDependencyManifest;

package/dist/manifests.js

@@ -0,0 +1,32 @@
+/**
+ * Veap-specific dependencies layered on top of the freshly generated
+ * `create-next-app` project. The CNA-provided Next/React/TypeScript/Tailwind
+ * versions are intentionally NOT pinned here - we take whatever the official
+ * scaffolder ships, so generated apps never lag behind the framework.
+ *
+ * Only `@types/node` is overridden: the engine requirement is Node >= 22.
+ * The linter comes from CNA (`--eslint`); no Biome, no changesets.
+ */
+/**
+ * Versions deliberately pinned OVER the CNA-provided ones: the engine
+ * requirement is Node >= 22. Applied after the spread merge so CNA cannot
+ * win these keys.
+ */
+export const PINNED_DEV_DEPENDENCIES = {
+    "@types/node": "^22.20.2",
+};
+/** Full plugin-enabled project. */
+export const FULL_MANIFEST = {
+    dependencies: {
+        dotenv: "^17.2.3",
+        pg: "^8.16.3",
+        "@veap/framework": "latest",
+        "@veap/ui": "latest",
+    },
+    devDependencies: {
+        ...PINNED_DEV_DEPENDENCIES,
+        "@types/pg": "^8.16.0",
+        rimraf: "^6.1.3",
+        "tw-animate-css": "^1.4.0",
+    },
+};

package/dist/mutate.d.ts

@@ -0,0 +1,46 @@
+import { type VeapDependencyManifest } from "./manifests.js";
+/**
+ * Post-scaffold mutations applied to the freshly generated
+ * `create-next-app` project. Everything CNA generated is kept as-is - these
+ * functions only inject what Veap needs on top of it.
+ */
+/** The dependency manifest applied to every generated project. */
+export declare function getManifest(): VeapDependencyManifest;
+/**
+ * Removes the CNA-generated `app/` directory before the overlay is applied.
+ * The overlay owns the whole `app/` tree: Next.js forbids a static page route
+ * at the same specificity as an optional catch-all, so a leftover
+ * `app/page.tsx` would conflict with the Veap `app/[[...catchAll]]/page.tsx`
+ * ("You cannot define a route with the same specificity as an optional
+ * catch-all route").
+ */
+export declare function clearAppDirectory(projectDir: string): void;
+/**
+ * Merges the veap dependency manifest into the CNA-generated package.json.
+ * CNA-provided entries (next, react, typescript, tailwind, eslint setup)
+ * win for keys they already define; the manifest only fills the gaps and
+ * overrides `@types/node` (Node >= 22 engine) plus adds `engines`.
+ *
+ * `packageName` overrides the generated package name (CNA derives it from
+ * the folder, which loses the scope of names like `@scope/name`).
+ */
+export declare function injectVeapDependencies(projectDir: string, packageName?: string): void;
+/**
+ * Builds the starter `.env` content.
+ *
+ * ENCRYPTION_KEY is generated randomly per project (16 bytes, base64 - the
+ * exact contract validated at boot by @veap/framework, which has no fallback
+ * since the fail-fast fix). DATABASE_URL defaults to a local SQLite file;
+ * mail values are left as documented placeholders.
+ */
+export declare function buildEnvFile(): string;
+/**
+ * Writes the starter `.env`. CNA's generated `.gitignore` ignores `.env*`,
+ * so the file stays local to the new project.
+ */
+export declare function writeEnvFile(projectDir: string): void;
+/**
+ * Appends the missing veap entries (storage dirs, plugin dist) to the
+ * CNA-generated `.gitignore`. Idempotent: no-op when everything is present.
+ */
+export declare function appendGitignore(projectDir: string): void;

package/dist/mutate.js

@@ -0,0 +1,127 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { FULL_MANIFEST, PINNED_DEV_DEPENDENCIES, } from "./manifests.js";
+/**
+ * Post-scaffold mutations applied to the freshly generated
+ * `create-next-app` project. Everything CNA generated is kept as-is - these
+ * functions only inject what Veap needs on top of it.
+ */
+/** The dependency manifest applied to every generated project. */
+export function getManifest() {
+    return FULL_MANIFEST;
+}
+/**
+ * Removes the CNA-generated `app/` directory before the overlay is applied.
+ * The overlay owns the whole `app/` tree: Next.js forbids a static page route
+ * at the same specificity as an optional catch-all, so a leftover
+ * `app/page.tsx` would conflict with the Veap `app/[[...catchAll]]/page.tsx`
+ * ("You cannot define a route with the same specificity as an optional
+ * catch-all route").
+ */
+export function clearAppDirectory(projectDir) {
+    const appDir = path.join(projectDir, "app");
+    if (fs.existsSync(appDir)) {
+        fs.rmSync(appDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Merges the veap dependency manifest into the CNA-generated package.json.
+ * CNA-provided entries (next, react, typescript, tailwind, eslint setup)
+ * win for keys they already define; the manifest only fills the gaps and
+ * overrides `@types/node` (Node >= 22 engine) plus adds `engines`.
+ *
+ * `packageName` overrides the generated package name (CNA derives it from
+ * the folder, which loses the scope of names like `@scope/name`).
+ */
+export function injectVeapDependencies(projectDir, packageName) {
+    const pkgPath = path.join(projectDir, "package.json");
+    if (!fs.existsSync(pkgPath)) {
+        throw new Error(`package.json not found in ${projectDir}`);
+    }
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+    const manifest = getManifest();
+    if (packageName) {
+        pkg.name = packageName;
+    }
+    pkg.dependencies = {
+        ...manifest.dependencies,
+        ...pkg.dependencies,
+    };
+    pkg.devDependencies = {
+        ...manifest.devDependencies,
+        ...pkg.devDependencies,
+        // Versions we own (node engine) win over CNA.
+        ...PINNED_DEV_DEPENDENCIES,
+    };
+    if (manifest.scripts) {
+        pkg.scripts = { ...pkg.scripts, ...manifest.scripts };
+    }
+    pkg.engines = { ...pkg.engines, node: ">=22" };
+    fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf-8");
+}
+/**
+ * Builds the starter `.env` content.
+ *
+ * ENCRYPTION_KEY is generated randomly per project (16 bytes, base64 - the
+ * exact contract validated at boot by @veap/framework, which has no fallback
+ * since the fail-fast fix). DATABASE_URL defaults to a local SQLite file;
+ * mail values are left as documented placeholders.
+ */
+export function buildEnvFile() {
+    const encryptionKey = randomBytes(16).toString("base64");
+    return [
+        "# Veap application configuration (generated by create-veap)",
+        "",
+        "# 16-byte base64 key used for AES encryption at rest (recovery codes,",
+        "# TOTP secrets). Regenerate with: openssl rand -base64 16",
+        `ENCRYPTION_KEY="${encryptionKey}"`,
+        "",
+        "# Local SQLite database (swap for a PostgreSQL URL in production)",
+        'DATABASE_URL="sqlite:./storage/veap.sqlite"',
+        "",
+        "# Mail transport: smtp (default) | console | custom",
+        "MAIL_TRANSPORT=smtp",
+        "# MAIL_USERNAME=",
+        "# MAIL_PASSWORD=",
+        "# MAIL_FROM_ADDRESS=",
+        "",
+    ].join("\n");
+}
+/**
+ * Writes the starter `.env`. CNA's generated `.gitignore` ignores `.env*`,
+ * so the file stays local to the new project.
+ */
+export function writeEnvFile(projectDir) {
+    const envPath = path.join(projectDir, ".env");
+    if (fs.existsSync(envPath)) {
+        // Never clobber: CNA does not generate .env, so this only triggers on
+        // re-runs over an existing directory.
+        return;
+    }
+    fs.writeFileSync(envPath, buildEnvFile(), "utf-8");
+}
+/** Entries veap requires in `.gitignore` on top of CNA's output. */
+const GITIGNORE_ENTRIES = ["public/storage/", "storage/", "**/*/dist"];
+/**
+ * Appends the missing veap entries (storage dirs, plugin dist) to the
+ * CNA-generated `.gitignore`. Idempotent: no-op when everything is present.
+ */
+export function appendGitignore(projectDir) {
+    const gitignorePath = path.join(projectDir, ".gitignore");
+    const existing = fs.existsSync(gitignorePath)
+        ? fs.readFileSync(gitignorePath, "utf-8")
+        : "";
+    const present = new Set(existing.split("\n").map((line) => line.trim()));
+    const missing = GITIGNORE_ENTRIES.filter((entry) => !present.has(entry));
+    if (missing.length === 0)
+        return;
+    const block = [
+        "",
+        "# Veap additions (appended by create-veap)",
+        ...missing,
+        "",
+    ].join("\n");
+    const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    fs.writeFileSync(gitignorePath, `${existing}${separator}${block}`, "utf-8");
+}

package/dist/package-manager.d.ts

@@ -0,0 +1,56 @@
+export type PackageManager = "pnpm" | "npm" | "yarn" | "bun";
+export declare const PACKAGE_MANAGERS: PackageManager[];
+export interface PackageManagerDetection {
+    pm: PackageManager;
+    /** Where the default came from: package.json field, a lockfile, or the framework default. */
+    source: "field" | "lockfile" | "default";
+    /** Human-readable detail, e.g. "pnpm@11.9.0" or "pnpm-lock.yaml". */
+    detail?: string;
+}
+/**
+ * Detects the package manager to default to by inspecting `dir` (usually the
+ * directory the scaffolding command was launched from).
+ *
+ * Priority: `packageManager` field in package.json > lockfiles > default (pnpm).
+ */
+export declare function detectPackageManager(dir: string): PackageManagerDetection;
+/**
+ * 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.
+ */
+export declare function promptPackageManager(detection: PackageManagerDetection): Promise<PackageManager>;
+/**
+ * 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).
+ */
+export declare function resolvePackageManager(options?: {
+    pm?: string;
+}): Promise<PackageManager>;
+/**
+ * Applies the chosen package manager to the freshly scaffolded project:
+ *
+ * - pnpm: pins `packageManager` (corepack), writes `pnpm-workspace.yaml`
+ *   only when missing (an existing one is the source of truth)
+ * - yarn: pins `packageManager`, adds `.yarnrc.yml` with `nodeLinker:
+ *   node-modules` (berry's default PnP breaks Next.js)
+ * - npm/bun: removes `packageManager` (not managed by corepack), switches
+ *   workspace definition to the `workspaces` field in package.json
+ */
+export declare function applyPackageManager(projectDir: string, pm: PackageManager): void;
+/** Command prefix for a package-manager-agnostic npm-script invocation. */
+export declare function pmRunCommand(pm: PackageManager, script: string): string;
+/**
+ * Installs dependencies with the chosen package manager (all four use the
+ * same `install` verb).
+ */
+export declare function pmInstall(pm: PackageManager, cwd: string, opts?: {
+    stdio?: "inherit" | "ignore" | "pipe";
+}): void;