create-bcp-app 0.1.25 → 0.1.27

package/README.md

@@ -8,19 +8,72 @@ cd my-app
 npm run dev
 ```
 
+## Project-local BCP CLI
+
+`create-bcp-app` installs BCP Framework as a **project-local dependency**. It does not install the framework CLI globally.
+
+Generated npm scripts can use `bcp` directly because npm automatically prepends the project's `node_modules/.bin` directory to `PATH` while scripts are running:
+
+```json
+{
+  "scripts": {
+    "dev": "bcp dev",
+    "build": "bcp build",
+    "start": "bcp start",
+    "routes": "bcp routes",
+    "update": "bcp update"
+  }
+}
+```
+
+For direct PowerShell usage, invoke the local CLI through `npm exec`:
+
+```powershell
+npm exec -- bcp-framework --version
+npm exec -- bcp-framework doctor
+npm exec -- bcp-framework inspect
+npm exec -- bcp-framework routes
+npm exec -- bcp-framework dev
+npm exec -- bcp-framework build
+```
+
+Typing `bcp-framework` directly in a normal PowerShell session may return `CommandNotFoundException` because PowerShell does not automatically add `node_modules/.bin` to its normal command search path.
+
+The Windows command shim can also be executed explicitly:
+
+```powershell
+.\node_modules\.bin\bcp-framework.cmd --version
+```
+
+BCP Framework publishes the `bcp-framework` alias because Microsoft SQL Server can install another Windows executable named `bcp.exe`.
+
+Recommended convention:
+
+```text
+Inside npm scripts      -> bcp ...
+Direct PowerShell usage -> npm exec -- bcp-framework ...
+```
+
+Using the project-local CLI also keeps the CLI version aligned with the exact BCP Framework dependency installed by the project.
+
 When running interactively, the generator asks:
 
 ```text
-Use Tailwind CSS? (Y/n)
+Use Tailwind CSS?
 Select a database:
-  1) None
-  2) MySQL
-  3) PostgreSQL
-  4) SQLite
-  5) MongoDB
+  None
+  MySQL
+  PostgreSQL
+  SQLite
+  MongoDB
 Select authentication:
-  1) None
-  2) JWT Cookie
+  None
+  JWT Cookie
+Select storage provider:
+  None
+  Local Server
+  Amazon S3
+  Cloudflare R2
 ```
 
 ## Generated application defaults
@@ -53,7 +106,7 @@ After a newer stable BCP release is published, update the project with:
 npm run update
 ```
 
-This resolves the npm `latest` release through BCP's updater, updates the exact framework dependency and refreshes the active package-manager lockfile. Use `bcp update --check` to inspect an available update without changing files.
+This resolves the npm `latest` release through BCP's updater, updates the exact framework dependency and refreshes the active package-manager lockfile. Use `bcp update --check` inside an npm script or `npm exec -- bcp-framework update --check` from PowerShell to inspect an available update without changing files.
 
 ## Generated optional setup
 
@@ -96,18 +149,7 @@ import "bcp/server-only";
 
 This prevents database code from being used in a page/client module graph. Query the database from an API route or a route-level server data loader and consume only serializable results from hydrated pages.
 
-For MySQL, the generated helper exports a reusable `db` pool and caches that pool on `globalThis` during development so hot reloads do not create a new connection pool every time:
-
-```ts
-import {
-    db,
-} from "@/lib/database";
-
-const [rows] =
-    await db.query(
-        "SELECT 1"
-    );
-```
+For MySQL, the generated helper exports the BCP database primitives through `bcp/database`.
 
 The generated MySQL `.env.example` uses separate connection settings:
 
@@ -119,7 +161,77 @@ DB_PASSWORD=
 DB_NAME=bcp_app
 ```
 
-The generator intentionally installs database drivers directly and does not force an ORM.
+The generator intentionally does not force an ORM.
+
+### Storage provider
+
+Selecting a storage provider creates:
+
+```text
+lib/storage.ts
+```
+
+and adds the provider-specific settings to `.env.example`.
+
+#### Local Server
+
+```bash
+npx create-bcp-app my-app --storage local
+```
+
+Generated environment setting:
+
+```dotenv
+STORAGE_LOCAL_DIRECTORY=./storage
+```
+
+The generated helper uses `createLocalStorage()` and adds `storage/` to `.gitignore` so uploaded files are not accidentally committed.
+
+#### Amazon S3
+
+```bash
+npx create-bcp-app my-app --storage amazon-s3
+```
+
+Generated environment settings:
+
+```dotenv
+AWS_S3_BUCKET=
+AWS_REGION=ap-southeast-1
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+AWS_SESSION_TOKEN=
+AWS_S3_PREFIX=
+```
+
+The generated helper uses `createS3Storage()`. Explicit credentials can be left unset when the deployment uses the AWS SDK server-side credential provider chain, such as an IAM role.
+
+#### Cloudflare R2
+
+```bash
+npx create-bcp-app my-app --storage cloudflare-r2
+```
+
+Generated environment settings:
+
+```dotenv
+R2_ACCOUNT_ID=
+R2_BUCKET=
+R2_ACCESS_KEY_ID=
+R2_SECRET_ACCESS_KEY=
+R2_PREFIX=
+```
+
+The generated helper uses the S3-compatible BCP adapter with:
+
+```text
+region: auto
+endpoint: https://<account-id>.r2.cloudflarestorage.com
+```
+
+Storage credentials are server-only. Do not expose them through `BCP_PUBLIC_*` variables.
+
+The selected preset only scaffolds the initial provider configuration. Application code can later switch to another BCP storage adapter without changing the generic storage APIs used by routes and services.
 
 ### JWT Cookie authentication
 
@@ -169,7 +281,8 @@ POST /api/auth/logout
 --no-tailwind             Disable Tailwind CSS without prompting
 --database <database>     none | mysql | postgresql | sqlite | mongodb
 --auth <preset>           none | jwt-cookie
--y, --yes                 Accept defaults (Tailwind enabled, no database, no auth)
+--storage <provider>      none | local | amazon-s3 | cloudflare-r2
+-y, --yes                 Accept defaults (Tailwind enabled, no database, no auth, no storage)
 --bcp <specifier>         Override dependencies.bcp
 -h, --help                Show help
 ```
@@ -177,14 +290,15 @@ POST /api/auth/logout
 Examples:
 
 ```bash
-npx create-bcp-app my-app --tailwind --database mysql --auth jwt-cookie
+npx create-bcp-app my-app --tailwind --database mysql --auth jwt-cookie --storage local
+npx create-bcp-app my-app --storage amazon-s3
+npx create-bcp-app my-app --storage cloudflare-r2
 npx create-bcp-app my-app --no-tailwind --database mongodb
-npx create-bcp-app my-app --auth jwt-cookie
 npx create-bcp-app my-app --yes
 ```
 
 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.9.tgz
+npx create-bcp-app my-app --bcp file:../bcp-0.1.27.tgz
 ```

package/bin/create-bcp-app.mjs

@@ -18,6 +18,11 @@ import {
     normalizeAuth,
     normalizeDatabase,
 } from "../src/project-options.mjs";
+import {
+    formatStorageProvider,
+    normalizeStorageProvider,
+    STORAGE_CHOICES,
+} from "../src/storage-options.mjs";
 
 const ANSI = {
     reset: "\u001B[0m",
@@ -71,6 +76,7 @@ async function main() {
             tailwind: resolved.tailwind,
             database: resolved.database,
             auth: resolved.auth,
+            storage: resolved.storage,
             packageManager: "npm",
         });
 
@@ -87,6 +93,7 @@ function parseArguments(args) {
     let tailwind = undefined;
     let database = undefined;
     let auth = undefined;
+    let storage = undefined;
     let acceptDefaults = false;
 
     for (
@@ -147,6 +154,20 @@ function parseArguments(args) {
             continue;
         }
 
+        if (value === "--storage") {
+            const nextValue = args[index + 1];
+
+            if (!nextValue) {
+                throw new Error(
+                    "--storage requires a value."
+                );
+            }
+
+            storage = normalizeStorageProvider(nextValue);
+            index++;
+            continue;
+        }
+
         if (value === "--bcp") {
             const nextValue = args[index + 1];
 
@@ -183,6 +204,7 @@ function parseArguments(args) {
         tailwind,
         database,
         auth,
+        storage,
         acceptDefaults,
     };
 }
@@ -191,11 +213,13 @@ async function resolveOptions({
     tailwind: selectedTailwind,
     database: selectedDatabase,
     auth: selectedAuth,
+    storage: selectedStorage,
     acceptDefaults,
 }) {
     let tailwind = selectedTailwind;
     let database = selectedDatabase;
     let auth = selectedAuth;
+    let storage = selectedStorage;
 
     if (acceptDefaults) {
         return {
@@ -206,6 +230,9 @@ async function resolveOptions({
             auth: normalizeAuth(
                 auth ?? "none"
             ),
+            storage: normalizeStorageProvider(
+                storage ?? "none"
+            ),
         };
     }
 
@@ -223,6 +250,9 @@ async function resolveOptions({
             auth: normalizeAuth(
                 auth ?? "none"
             ),
+            storage: normalizeStorageProvider(
+                storage ?? "none"
+            ),
         };
     }
 
@@ -242,10 +272,15 @@ async function resolveOptions({
         auth = await askAuth();
     }
 
+    if (storage === undefined) {
+        storage = await askStorage();
+    }
+
     return {
         tailwind: Boolean(tailwind),
         database: normalizeDatabase(database),
         auth: normalizeAuth(auth),
+        storage: normalizeStorageProvider(storage),
     };
 }
 
@@ -302,6 +337,21 @@ function askAuth() {
     );
 }
 
+function askStorage() {
+    return askTerminalSelect(
+        "Select storage provider:",
+        STORAGE_CHOICES.map(
+            (value) => ({
+                value,
+                label:
+                    formatStorageProvider(
+                        value
+                    ),
+            })
+        )
+    );
+}
+
 function askTerminalSelect(
     label,
     choices
@@ -486,6 +536,9 @@ function printSuccess(
     console.log(
         `Authentication: ${formatAuthName(result.auth)}`
     );
+    console.log(
+        `Storage: ${formatStorageProvider(result.storage)}`
+    );
     console.log("");
     console.log("Next steps:");
     console.log(
@@ -496,6 +549,10 @@ function printSuccess(
         console.log("  npm install");
     }
 
+    if (result.storage !== "none") {
+        console.log("  Copy .env.example to .env and configure storage credentials");
+    }
+
     console.log("  npm run dev");
     console.log("");
 }
@@ -533,6 +590,7 @@ Interactive setup:
   - Choose Tailwind CSS: Yes or No
   - Choose a database: None, MySQL, PostgreSQL, SQLite or MongoDB
   - Choose authentication: None or JWT Cookie
+  - Choose storage: None, Local Server, Amazon S3 or Cloudflare R2
 
 Options:
   --no-install              Create files without running npm install
@@ -540,14 +598,16 @@ Options:
   --no-tailwind             Disable Tailwind CSS without prompting
   --database <database>     none | mysql | postgresql | sqlite | mongodb
   --auth <preset>           none | jwt-cookie
-  -y, --yes                 Accept defaults (Tailwind enabled, no database, no auth)
+  --storage <provider>      none | local | amazon-s3 | cloudflare-r2
+  -y, --yes                 Accept defaults (Tailwind enabled, no database, no auth, no storage)
   --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 --tailwind --database mysql --auth jwt-cookie
-  npx create-bcp-app my-app --no-tailwind --database mongodb
+  npx create-bcp-app my-app --tailwind --database mysql --auth jwt-cookie --storage local
+  npx create-bcp-app my-app --storage amazon-s3
+  npx create-bcp-app my-app --storage cloudflare-r2
   npx create-bcp-app my-app --yes
   npx create-bcp-app my-app --no-install
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bcp-app",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "Create a new BCP Framework application.",
   "type": "module",
   "license": "MIT",

package/src/index.d.mts

@@ -9,6 +9,12 @@ export type BcpAuthPreset =
     | "none"
     | "jwt-cookie";
 
+export type BcpStorageProvider =
+    | "none"
+    | "local"
+    | "amazon-s3"
+    | "cloudflare-r2";
+
 export interface CreateBcpAppOptions {
     projectDirectory: string;
     install?: boolean;
@@ -16,6 +22,7 @@ export interface CreateBcpAppOptions {
     tailwind?: boolean;
     database?: BcpDatabase;
     auth?: BcpAuthPreset;
+    storage?: BcpStorageProvider;
     packageManager?: "npm";
 }
 
@@ -26,6 +33,7 @@ export interface CreateBcpAppResult {
     tailwind: boolean;
     database: BcpDatabase;
     auth: BcpAuthPreset;
+    storage: BcpStorageProvider;
 }
 
 export interface ResolveNpmInvocationOptions {

package/src/index.mjs

@@ -12,6 +12,10 @@ import {
     normalizeAuth,
     normalizeDatabase,
 } from "./project-options.mjs";
+import {
+    applyStorageOption,
+    normalizeStorageProvider,
+} from "./storage-options.mjs";
 
 const packageRoot =
     path.resolve(
@@ -47,6 +51,10 @@ export async function createBcpApp(
         normalizeAuth(
             options.auth
         );
+    const storage =
+        normalizeStorageProvider(
+            options.storage
+        );
 
     ensureTargetDirectory(
         targetDirectory
@@ -128,6 +136,11 @@ export async function createBcpApp(
             database,
             auth,
         });
+    const selectedStorage =
+        applyStorageOption({
+            targetDirectory,
+            storage,
+        });
 
     configureFrameworkDatabaseEntry(
         targetDirectory,
@@ -171,6 +184,8 @@ export async function createBcpApp(
             selectedOptions.database,
         auth:
             selectedOptions.auth,
+        storage:
+            selectedStorage,
     };
 }
 

package/src/storage-options.mjs

@@ -0,0 +1,341 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const STORAGE_CHOICES = [
+    "none",
+    "local",
+    "amazon-s3",
+    "cloudflare-r2",
+];
+
+const STORAGE_PRESETS = {
+    local: {
+        env: [
+            "STORAGE_LOCAL_DIRECTORY=./storage",
+        ],
+        gitIgnore: [
+            "storage/",
+        ],
+        source: `import "bcp/server-only";
+
+import {
+    createLocalStorage,
+} from "bcp/server";
+
+export const storage =
+    createLocalStorage({
+        directory:
+            process.env.STORAGE_LOCAL_DIRECTORY ??
+            "./storage",
+    });
+`,
+    },
+    "amazon-s3": {
+        env: [
+            "AWS_S3_BUCKET=",
+            "AWS_REGION=ap-southeast-1",
+            "AWS_ACCESS_KEY_ID=",
+            "AWS_SECRET_ACCESS_KEY=",
+            "AWS_SESSION_TOKEN=",
+            "AWS_S3_PREFIX=",
+        ],
+        gitIgnore: [],
+        source: `import "bcp/server-only";
+
+import {
+    createS3Storage,
+} from "bcp/server";
+
+const bucket =
+    requireEnvironmentVariable(
+        "AWS_S3_BUCKET"
+    );
+
+export const storage =
+    createS3Storage({
+        bucket,
+        region:
+            process.env.AWS_REGION ??
+            "ap-southeast-1",
+        prefix:
+            optionalEnvironmentVariable(
+                "AWS_S3_PREFIX"
+            ),
+        accessKeyId:
+            optionalEnvironmentVariable(
+                "AWS_ACCESS_KEY_ID"
+            ),
+        secretAccessKey:
+            optionalEnvironmentVariable(
+                "AWS_SECRET_ACCESS_KEY"
+            ),
+        sessionToken:
+            optionalEnvironmentVariable(
+                "AWS_SESSION_TOKEN"
+            ),
+    });
+
+function requireEnvironmentVariable(
+    name: string
+): string {
+    const value =
+        process.env[name]
+            ?.trim();
+
+    if (!value) {
+        throw new Error(
+            \`BCP storage: \${name} is required.\`
+        );
+    }
+
+    return value;
+}
+
+function optionalEnvironmentVariable(
+    name: string
+): string | undefined {
+    const value =
+        process.env[name]
+            ?.trim();
+
+    return value || undefined;
+}
+`,
+    },
+    "cloudflare-r2": {
+        env: [
+            "R2_ACCOUNT_ID=",
+            "R2_BUCKET=",
+            "R2_ACCESS_KEY_ID=",
+            "R2_SECRET_ACCESS_KEY=",
+            "R2_PREFIX=",
+        ],
+        gitIgnore: [],
+        source: `import "bcp/server-only";
+
+import {
+    createS3Storage,
+} from "bcp/server";
+
+const accountId =
+    requireEnvironmentVariable(
+        "R2_ACCOUNT_ID"
+    );
+const bucket =
+    requireEnvironmentVariable(
+        "R2_BUCKET"
+    );
+
+export const storage =
+    createS3Storage({
+        bucket,
+        region:
+            "auto",
+        endpoint:
+            \`https://\${accountId}.r2.cloudflarestorage.com\`,
+        prefix:
+            optionalEnvironmentVariable(
+                "R2_PREFIX"
+            ),
+        accessKeyId:
+            requireEnvironmentVariable(
+                "R2_ACCESS_KEY_ID"
+            ),
+        secretAccessKey:
+            requireEnvironmentVariable(
+                "R2_SECRET_ACCESS_KEY"
+            ),
+    });
+
+function requireEnvironmentVariable(
+    name: string
+): string {
+    const value =
+        process.env[name]
+            ?.trim();
+
+    if (!value) {
+        throw new Error(
+            \`BCP storage: \${name} is required.\`
+        );
+    }
+
+    return value;
+}
+
+function optionalEnvironmentVariable(
+    name: string
+): string | undefined {
+    const value =
+        process.env[name]
+            ?.trim();
+
+    return value || undefined;
+}
+`,
+    },
+};
+
+export function normalizeStorageProvider(
+    value
+) {
+    const normalized =
+        String(
+            value ?? "none"
+        )
+            .trim()
+            .toLowerCase();
+
+    if (
+        !STORAGE_CHOICES.includes(
+            normalized
+        )
+    ) {
+        throw new Error(
+            `Unsupported storage provider: ${normalized}. Choose one of: ${STORAGE_CHOICES.join(", ")}.`
+        );
+    }
+
+    return normalized;
+}
+
+export function applyStorageOption({
+    targetDirectory,
+    storage = "none",
+}) {
+    const selectedStorage =
+        normalizeStorageProvider(
+            storage
+        );
+
+    if (
+        selectedStorage === "none"
+    ) {
+        return selectedStorage;
+    }
+
+    const preset =
+        STORAGE_PRESETS[
+            selectedStorage
+        ];
+
+    writeFile(
+        targetDirectory,
+        "lib/storage.ts",
+        preset.source
+    );
+    appendEnvExample(
+        targetDirectory,
+        preset.env,
+        `Storage (${formatStorageProvider(selectedStorage)})`
+    );
+
+    for (const entry of preset.gitIgnore) {
+        appendGitIgnore(
+            targetDirectory,
+            entry
+        );
+    }
+
+    return selectedStorage;
+}
+
+export function formatStorageProvider(
+    value
+) {
+    const names = {
+        none: "None",
+        local: "Local Server",
+        "amazon-s3": "Amazon S3",
+        "cloudflare-r2": "Cloudflare R2",
+    };
+
+    return names[value] ?? value;
+}
+
+function appendEnvExample(
+    targetDirectory,
+    lines,
+    section
+) {
+    const filePath =
+        path.join(
+            targetDirectory,
+            ".env.example"
+        );
+    const current =
+        fs.existsSync(
+            filePath
+        )
+            ? fs.readFileSync(
+                filePath,
+                "utf8"
+            ).trimEnd()
+            : "";
+
+    fs.writeFileSync(
+        filePath,
+        `${current}${current ? "\n\n" : ""}# ${section}\n${lines.join("\n")}\n`,
+        "utf8"
+    );
+}
+
+function appendGitIgnore(
+    targetDirectory,
+    entry
+) {
+    const filePath =
+        path.join(
+            targetDirectory,
+            ".gitignore"
+        );
+    const current =
+        fs.existsSync(
+            filePath
+        )
+            ? fs.readFileSync(
+                filePath,
+                "utf8"
+            ).trimEnd()
+            : "";
+    const lines =
+        new Set(
+            current
+                .split(/\r?\n/)
+                .filter(Boolean)
+        );
+
+    lines.add(entry);
+
+    fs.writeFileSync(
+        filePath,
+        `${Array.from(lines).join("\n")}\n`,
+        "utf8"
+    );
+}
+
+function writeFile(
+    targetDirectory,
+    relativePath,
+    content
+) {
+    const filePath =
+        path.join(
+            targetDirectory,
+            relativePath
+        );
+
+    fs.mkdirSync(
+        path.dirname(
+            filePath
+        ),
+        {
+            recursive: true,
+        }
+    );
+    fs.writeFileSync(
+        filePath,
+        content,
+        "utf8"
+    );
+}

package/template/README.md

@@ -10,7 +10,9 @@ npm run dev
 
 Open `http://localhost:3000`.
 
-## Commands
+## Project commands
+
+Generated projects use the project-local BCP Framework CLI through npm scripts:
 
 ```bash
 npm run dev
@@ -18,6 +20,65 @@ npm run routes
 npm run typecheck
 npm run build
 npm start
+npm run update
+```
+
+The generated scripts call commands such as `bcp dev`, `bcp build` and `bcp start`. This works because npm automatically adds the project's `node_modules/.bin` directory to `PATH` while an npm script is running.
+
+## Direct CLI usage
+
+BCP Framework is installed as a **project-local dependency**. It is not installed globally by `create-bcp-app`.
+
+Because of that, typing this directly in a normal PowerShell session may not work:
+
+```powershell
+bcp-framework doctor
+```
+
+PowerShell does not automatically add `node_modules/.bin` to its normal command search path.
+
+Use `npm exec` when you want to invoke the project-local CLI directly:
+
+```powershell
+npm exec -- bcp-framework --version
+npm exec -- bcp-framework doctor
+npm exec -- bcp-framework inspect
+npm exec -- bcp-framework routes
+npm exec -- bcp-framework dev
+npm exec -- bcp-framework build
+```
+
+You can also execute the Windows command shim explicitly:
+
+```powershell
+.\node_modules\.bin\bcp-framework.cmd --version
+```
+
+Using the project-local CLI is recommended because it guarantees that the CLI version matches the BCP Framework version installed by this application.
+
+### Why `bcp-framework` instead of `bcp` in PowerShell?
+
+Microsoft SQL Server can install another Windows executable named `bcp.exe`. To avoid that command-name collision, BCP Framework publishes the additional `bcp-framework` alias.
+
+Use this convention:
+
+```text
+Inside npm scripts      -> bcp ...
+Direct PowerShell usage -> npm exec -- bcp-framework ...
+```
+
+## Production
+
+Create the standalone production build:
+
+```bash
+npm run build
+```
+
+Start it with:
+
+```bash
+npm start
 ```
 
 The production build is written to `.bcp-framework/build` and runs as a standalone Node.js server.