create-bcp-app 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chidchanun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# create-bcp-app
+
+Create a new BCP Framework project.
+
+```bash
+npx create-bcp-app my-app
+cd my-app
+npm run dev
+```
+
+## Options
+
+```text
+--no-install       Create files without running npm install
+--bcp <specifier>  Override dependencies.bcp
+-h, --help         Show help
+```
+
+The `--bcp` option is primarily useful for prerelease and local package testing, for example:
+
+```bash
+npx create-bcp-app my-app --bcp file:../bcp-0.1.0.tgz
+```

package/bin/create-bcp-app.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+
+import {
+    createBcpApp,
+} from "../src/index.mjs";
+
+const args =
+    process.argv.slice(2);
+
+if (
+    args.includes("--help") ||
+    args.includes("-h")
+) {
+    printHelp();
+    process.exit(0);
+}
+
+let projectDirectory =
+    null;
+let install =
+    true;
+let bcpPackage =
+    undefined;
+
+for (
+    let index = 0;
+    index < args.length;
+    index++
+) {
+    const value =
+        args[index];
+
+    if (
+        value === "--no-install"
+    ) {
+        install =
+            false;
+        continue;
+    }
+
+    if (
+        value === "--bcp"
+    ) {
+        const nextValue =
+            args[
+                index + 1
+            ];
+
+        if (!nextValue) {
+            fail(
+                "--bcp requires a package specifier."
+            );
+        }
+
+        bcpPackage =
+            nextValue;
+        index++;
+        continue;
+    }
+
+    if (
+        value.startsWith("-")
+    ) {
+        fail(
+            `Unknown option: ${value}`
+        );
+    }
+
+    if (
+        projectDirectory !==
+        null
+    ) {
+        fail(
+            "Only one project directory may be provided."
+        );
+    }
+
+    projectDirectory =
+        value;
+}
+
+if (!projectDirectory) {
+    printHelp();
+    process.exitCode =
+        1;
+} else {
+    try {
+        const result =
+            await createBcpApp({
+                projectDirectory,
+                install,
+                bcpPackage,
+                packageManager:
+                    "npm",
+            });
+
+        const relative =
+            path.relative(
+                process.cwd(),
+                result.targetDirectory
+            ) || ".";
+
+        console.log("");
+        console.log(
+            `Created BCP app: ${result.projectName}`
+        );
+        console.log(
+            `Location: ${result.targetDirectory}`
+        );
+        console.log("");
+        console.log(
+            "Next steps:"
+        );
+        console.log(
+            `  cd ${quoteIfNeeded(relative)}`
+        );
+
+        if (!install) {
+            console.log(
+                "  npm install"
+            );
+        }
+
+        console.log(
+            "  npm run dev"
+        );
+        console.log("");
+    } catch (error) {
+        fail(
+            error instanceof Error
+                ? error.message
+                : String(error)
+        );
+    }
+}
+
+function printHelp() {
+    console.log(`
+create-bcp-app
+
+Usage:
+  npx create-bcp-app <project-name> [options]
+
+Options:
+  --no-install       Create files without running npm install
+  --bcp <specifier>  Override the package specifier stored under dependencies.bcp
+  -h, --help         Show this help message
+
+Examples:
+  npx create-bcp-app my-app
+  npx create-bcp-app my-app --no-install
+  npx create-bcp-app my-app --bcp file:../bcp-0.1.0.tgz
+`);
+}
+
+function quoteIfNeeded(
+    value
+) {
+    return /\s/.test(
+        value
+    )
+        ? JSON.stringify(
+            value
+        )
+        : value;
+}
+
+function fail(
+    message
+) {
+    console.error(
+        `create-bcp-app: ${message}`
+    );
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "create-bcp-app",
+  "version": "0.1.1",
+  "description": "Create a new BCP Framework application.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "create-bcp-app": "bin/create-bcp-app.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "template",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=24.11.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chidchanun/bcp-freamwork.git",
+    "directory": "create-bcp-app"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bcpFrameworkPackage": "@chidchanun/bcp"
+}

package/src/index.mjs

@@ -0,0 +1,405 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+    spawn,
+} from "node:child_process";
+import {
+    fileURLToPath,
+} from "node:url";
+
+const packageRoot =
+    path.resolve(
+        path.dirname(
+            fileURLToPath(
+                import.meta.url
+            )
+        ),
+        ".."
+    );
+
+export async function createBcpApp(
+    options
+) {
+    const targetDirectory =
+        path.resolve(
+            options.projectDirectory
+        );
+
+    const projectName =
+        validateProjectName(
+            path.basename(
+                targetDirectory
+            )
+        );
+
+    ensureTargetDirectory(
+        targetDirectory
+    );
+
+    const templateDirectory =
+        path.join(
+            packageRoot,
+            "template"
+        );
+
+    copyTemplate(
+        templateDirectory,
+        targetDirectory
+    );
+
+    const packageMetadata =
+        readPackageMetadata();
+
+    const packageSpecifier =
+        options.bcpPackage ??
+        createDefaultBcpPackageSpecifier(
+            packageMetadata.frameworkPackage,
+            packageMetadata.version
+        );
+
+    const packageJson = {
+        name:
+            projectName,
+        version:
+            "0.1.0",
+        private:
+            true,
+        type:
+            "module",
+        scripts: {
+            dev:
+                "bcp dev",
+            build:
+                "bcp build",
+            start:
+                "bcp start",
+            routes:
+                "bcp routes",
+            typecheck:
+                "tsc --noEmit",
+        },
+        dependencies: {
+            bcp:
+                packageSpecifier,
+            react:
+                "^19.2.8",
+            "react-dom":
+                "^19.2.8",
+        },
+        devDependencies: {
+            "@types/node":
+                "^24.13.3",
+            "@types/react":
+                "^19.2.18",
+            "@types/react-dom":
+                "^19.2.4",
+            typescript:
+                "^5.9.3",
+        },
+        engines: {
+            node:
+                ">=24.11.0",
+        },
+    };
+
+    fs.writeFileSync(
+        path.join(
+            targetDirectory,
+            "package.json"
+        ),
+        `${JSON.stringify(
+            packageJson,
+            null,
+            2
+        )}\n`,
+        "utf8"
+    );
+
+    if (
+        options.install !== false
+    ) {
+        await runInstall(
+            targetDirectory,
+            options.packageManager ??
+                "npm"
+        );
+    }
+
+    return {
+        targetDirectory,
+        projectName,
+        packageSpecifier,
+    };
+}
+
+export function validateProjectName(
+    value
+) {
+    const name =
+        String(
+            value ?? ""
+        ).trim();
+
+    if (
+        !name ||
+        name === "." ||
+        name === ".."
+    ) {
+        throw new Error(
+            "Project name is required."
+        );
+    }
+
+    if (
+        name !==
+        name.toLowerCase()
+    ) {
+        throw new Error(
+            "Project name must use lowercase characters."
+        );
+    }
+
+    if (
+        !/^[a-z0-9][a-z0-9._-]*$/.test(
+            name
+        )
+    ) {
+        throw new Error(
+            "Project name may contain lowercase letters, numbers, dots, underscores and hyphens."
+        );
+    }
+
+    if (
+        name === "node_modules" ||
+        name === "favicon.ico"
+    ) {
+        throw new Error(
+            `Project name "${name}" is reserved.`
+        );
+    }
+
+    return name;
+}
+
+function ensureTargetDirectory(
+    targetDirectory
+) {
+    if (
+        fs.existsSync(
+            targetDirectory
+        )
+    ) {
+        const entries =
+            fs.readdirSync(
+                targetDirectory
+            );
+
+        if (
+            entries.length > 0
+        ) {
+            throw new Error(
+                `Target directory is not empty: ${targetDirectory}`
+            );
+        }
+
+        return;
+    }
+
+    fs.mkdirSync(
+        targetDirectory,
+        {
+            recursive: true,
+        }
+    );
+}
+
+function copyTemplate(
+    sourceDirectory,
+    targetDirectory
+) {
+    fs.cpSync(
+        sourceDirectory,
+        targetDirectory,
+        {
+            recursive: true,
+        }
+    );
+
+    const gitignoreTemplate =
+        path.join(
+            targetDirectory,
+            "gitignore"
+        );
+
+    if (
+        fs.existsSync(
+            gitignoreTemplate
+        )
+    ) {
+        fs.renameSync(
+            gitignoreTemplate,
+            path.join(
+                targetDirectory,
+                ".gitignore"
+            )
+        );
+    }
+}
+
+function readPackageMetadata() {
+    const packageJson =
+        JSON.parse(
+            fs.readFileSync(
+                path.join(
+                    packageRoot,
+                    "package.json"
+                ),
+                "utf8"
+            )
+        );
+
+    if (
+        typeof packageJson.version !==
+            "string" ||
+        packageJson.version.trim() ===
+            ""
+    ) {
+        throw new Error(
+            "create-bcp-app package version is missing."
+        );
+    }
+
+    const frameworkPackage =
+        typeof packageJson.bcpFrameworkPackage ===
+            "string" &&
+        packageJson.bcpFrameworkPackage.trim() !==
+            ""
+            ? packageJson.bcpFrameworkPackage.trim()
+            : "bcp";
+
+    return {
+        version:
+            packageJson.version,
+        frameworkPackage,
+    };
+}
+
+function createDefaultBcpPackageSpecifier(
+    frameworkPackage,
+    version
+) {
+    if (
+        frameworkPackage === "bcp"
+    ) {
+        return `^${version}`;
+    }
+
+    return `npm:${frameworkPackage}@^${version}`;
+}
+
+function runInstall(
+    targetDirectory,
+    packageManager
+) {
+    if (
+        packageManager !== "npm"
+    ) {
+        throw new Error(
+            `Unsupported package manager: ${packageManager}. Only npm is supported in this release.`
+        );
+    }
+
+    const invocation =
+        resolveNpmInvocation([
+            "install",
+        ]);
+
+    return new Promise(
+        (
+            resolve,
+            reject
+        ) => {
+            const child =
+                spawn(
+                    invocation.command,
+                    invocation.args,
+                    {
+                        cwd:
+                            targetDirectory,
+                        stdio:
+                            "inherit",
+                        env:
+                            process.env,
+                    }
+                );
+
+            child.once(
+                "error",
+                reject
+            );
+            child.once(
+                "exit",
+                (
+                    code,
+                    signal
+                ) => {
+                    if (
+                        code === 0
+                    ) {
+                        resolve();
+                        return;
+                    }
+
+                    reject(
+                        new Error(
+                            signal
+                                ? `npm install stopped by ${signal}.`
+                                : `npm install exited with code ${code ?? 1}.`
+                        )
+                    );
+                }
+            );
+        }
+    );
+}
+
+function resolveNpmInvocation(
+    args
+) {
+    const npmExecPath =
+        process.env.npm_execpath;
+
+    if (npmExecPath) {
+        return {
+            command:
+                process.execPath,
+            args: [
+                npmExecPath,
+                ...args,
+            ],
+        };
+    }
+
+    if (
+        process.platform === "win32"
+    ) {
+        return {
+            command:
+                process.env.ComSpec ??
+                "cmd.exe",
+            args: [
+                "/d",
+                "/s",
+                "/c",
+                "npm",
+                ...args,
+            ],
+        };
+    }
+
+    return {
+        command:
+            "npm",
+        args,
+    };
+}

package/template/.env.example

@@ -0,0 +1,2 @@
+BCP_PUBLIC_APP_NAME=BCP App
+BCP_SERVER_LABEL=local

package/template/README.md

@@ -0,0 +1,23 @@
+# BCP App
+
+This project was created with `create-bcp-app`.
+
+## Development
+
+```bash
+npm run dev
+```
+
+Open `http://localhost:3000`.
+
+## Commands
+
+```bash
+npm run dev
+npm run routes
+npm run typecheck
+npm run build
+npm start
+```
+
+The production build is written to `.bcp-framework/build` and runs as a standalone Node.js server.

package/template/app/api/hello/route.ts

@@ -0,0 +1,6 @@
+export function GET() {
+    return Response.json({
+        message:
+            "Hello from BCP Framework",
+    });
+}

package/template/app/layout.tsx

@@ -0,0 +1,47 @@
+import type {
+    ReactNode,
+} from "react";
+
+import {
+    Link,
+    type Metadata,
+} from "bcp";
+
+export const metadata:
+    Metadata = {
+    title:
+        "BCP App",
+    description:
+        "Created with BCP Framework.",
+};
+
+export default function RootLayout(
+    {
+        children,
+    }: {
+        children:
+            ReactNode;
+    }
+) {
+    return (
+        <div>
+            <header>
+                <strong>
+                    BCP App
+                </strong>
+
+                {" · "}
+
+                <Link href="/">
+                    Home
+                </Link>
+            </header>
+
+            <hr />
+
+            <main>
+                {children}
+            </main>
+        </div>
+    );
+}

package/template/app/page.tsx

@@ -0,0 +1,37 @@
+import type {
+    Metadata,
+} from "bcp";
+
+export const metadata:
+    Metadata = {
+    title:
+        "Home | BCP App",
+};
+
+export default function HomePage() {
+    return (
+        <section>
+            <h1>
+                Welcome to BCP Framework
+            </h1>
+
+            <p>
+                Edit
+                {" "}
+                <code>
+                    app/page.tsx
+                </code>
+                {" "}
+                to get started.
+            </p>
+
+            <p>
+                API example:
+                {" "}
+                <a href="/api/hello">
+                    /api/hello
+                </a>
+            </p>
+        </section>
+    );
+}

package/template/bcp.config.ts

@@ -0,0 +1,37 @@
+import {
+    defineConfig,
+} from "bcp/config";
+
+export default defineConfig({
+    server: {
+        port: 3000,
+        hostname:
+            "localhost",
+        bodyLimit:
+            1024 * 1024,
+    },
+
+    compression: true,
+
+    build: {
+        minify: true,
+        sourceMaps: false,
+    },
+
+    cache: {
+        response: true,
+    },
+
+    security: {
+        poweredByHeader:
+            false,
+        contentSecurityPolicy:
+            false,
+        frameOptions:
+            "SAMEORIGIN",
+        referrerPolicy:
+            "strict-origin-when-cross-origin",
+        permissionsPolicy:
+            "camera=(), microphone=(), geolocation=()",
+    },
+});

package/template/gitignore

@@ -0,0 +1,9 @@
+node_modules/
+.bcp-framework/
+dist/
+.env
+.env.local
+.env.development.local
+.env.production.local
+npm-debug.log*
+.DS_Store

package/template/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true,
+    "types": [
+      "node",
+      "react",
+      "react-dom"
+    ]
+  },
+  "include": [
+    "app/**/*.ts",
+    "app/**/*.tsx",
+    "bcp.config.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    ".bcp-framework"
+  ]
+}