create-bcp-app 0.1.28 → 0.2.0

package/README.md

@@ -10,9 +10,9 @@ 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.
+`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:
+Generated npm scripts use `bcp` because npm places `node_modules/.bin` on the script `PATH`:
 
 ```json
 {
@@ -21,42 +21,29 @@ Generated npm scripts can use `bcp` directly because npm automatically prepends
     "build": "bcp build",
     "start": "bcp start",
     "routes": "bcp routes",
+    "generate": "bcp generate",
     "update": "bcp update"
   }
 }
 ```
 
-For direct PowerShell usage, invoke the local CLI through `npm exec`:
+For direct PowerShell usage, prefer the collision-free local alias:
 
 ```powershell
 npm exec -- bcp-framework --version
 npm exec -- bcp-framework doctor
 npm exec -- bcp-framework inspect
+npm exec -- bcp-framework generate page dashboard/users
 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.
+Microsoft SQL Server can install another Windows executable named `bcp.exe`, so `bcp-framework` is the recommended interactive Windows command name.
 
-The Windows command shim can also be executed explicitly:
+## Interactive choices
 
-```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:
+The generator asks for optional application presets:
 
 ```text
 Use Tailwind CSS?
@@ -76,52 +63,86 @@ Select storage provider:
   Cloudflare R2
 ```
 
-## Generated application defaults
-
-Generated applications include the project-root `@/` alias:
+Equivalent non-interactive flags are available for CI/scaffolding automation.
 
-```ts
-import {
-    db,
-} from "@/lib/database";
-```
+## Generated project metadata — 0.1.29
 
-The generated TypeScript configuration uses `module: "ESNext"` and `moduleResolution: "Bundler"` so extensionless application aliases match BCP's bundler and development runtime resolution.
+New projects include:
 
-Modules that use React client hooks such as `useState` or `useEffect` must declare `"use client"` at the top of the module.
+```text
+bcp.project.json
+```
 
-The generated BCP dependency is pinned to the exact framework release selected by the generator, and new projects include:
+Example:
 
 ```json
 {
-  "scripts": {
-    "update": "bcp update"
+  "schemaVersion": 1,
+  "framework": "bcp",
+  "projectName": "my-app",
+  "frameworkPackage": "npm:@chidchanun/bcp@0.1.29",
+  "createdWith": {
+    "package": "create-bcp-app",
+    "version": "0.1.29"
+  },
+  "packageManager": "npm",
+  "presets": {
+    "tailwind": true,
+    "database": "mysql",
+    "auth": "jwt-cookie",
+    "storage": "local"
   }
 }
 ```
 
-After a newer stable BCP release is published, update the project with:
+This manifest records scaffold identity only. It is intended for:
+
+- `bcp doctor`,
+- `bcp inspect`,
+- upgrade/migration tooling,
+- project-aware documentation,
+- `bcp-docs-web` examples/tooling.
+
+It must not contain secrets. Never put database passwords, AWS/R2 credentials, JWT/session secrets or tokens in `bcp.project.json`.
+
+The file should normally be committed to source control.
+
+Existing projects created before `0.1.29` remain valid without it.
+
+Read more: `docs/project-metadata.md` in the BCP Framework repository.
+
+## Generated application defaults
+
+Generated applications include the project-root `@/` alias and TypeScript settings compatible with the BCP bundler.
+
+Modules that use React client hooks such as `useState` or `useEffect` must declare `"use client"` at the top of the module.
+
+The generated BCP dependency is pinned to the exact framework release selected by the generator.
+
+Update later with:
 
 ```bash
 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` inside an npm script or `npm exec -- bcp-framework update --check` from PowerShell to inspect an available update without changing files.
+Check without modifying files:
 
-## Generated optional setup
+```powershell
+npm exec -- bcp-framework update --check
+```
 
-### Tailwind CSS
+## Tailwind CSS
 
 When Tailwind is enabled, the project includes:
 
-- `tailwindcss`
-- `@tailwindcss/cli`
-- `concurrently`
-- `app/globals.css`
-- a stylesheet link to `/bcp.css` in `app/layout.tsx`
-- starter Tailwind utility classes in `app/page.tsx`
+- `tailwindcss`,
+- `@tailwindcss/cli`,
+- `concurrently`,
+- `app/globals.css`,
+- `/bcp.css` stylesheet setup,
+- starter utility classes.
 
-The generated npm scripts compile Tailwind directly to `public/bcp.css` before starting BCP and keep Tailwind running in watch mode during development:
+Generated commands include:
 
 ```text
 npm run css:build
@@ -129,11 +150,11 @@ npm run css:watch
 npm run css:build:prod
 ```
 
-`npm run dev` performs an initial CSS build, then runs the Tailwind watcher and `bcp dev` together. BCP serves `/bcp.css` as a normal static asset from `public/`. Starting with BCP 0.1.6, stylesheets at that path are inlined into SSR HTML when they are 8 KiB or smaller and the active Content Security Policy allows inline styles. Larger stylesheets remain external for normal browser caching. `npm run build` creates a minified stylesheet before the BCP production build.
+`npm run build` creates the production stylesheet before the BCP production build.
 
-### Database
+## Database presets
 
-The database choice adds a starter `lib/database.ts`, updates `.env.example`, and installs the matching driver:
+The database choice adds starter configuration and the matching driver:
 
 - MySQL: `mysql2`
 - PostgreSQL: `pg`
@@ -141,17 +162,15 @@ The database choice adds a starter `lib/database.ts`, updates `.env.example`, an
 - MongoDB: `mongodb`
 - None: no database dependency
 
-The generated database helper starts with:
+Server-only database helpers begin with:
 
 ```ts
 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 the BCP database primitives through `bcp/database`.
+For MySQL, the generated helper exposes the BCP database primitives through `bcp/database`.
 
-The generated MySQL `.env.example` uses separate connection settings:
+Generated MySQL environment variables:
 
 ```dotenv
 DB_HOST=localhost
@@ -163,7 +182,7 @@ DB_NAME=bcp_app
 
 The generator intentionally does not force an ORM.
 
-### Storage provider
+## Storage providers
 
 Selecting a storage provider creates:
 
@@ -171,23 +190,42 @@ Selecting a storage provider creates:
 lib/storage.ts
 ```
 
-and adds the provider-specific settings to `.env.example`.
+and adds provider-specific environment settings.
 
-#### Local Server
+### Local Server
 
 ```bash
 npx create-bcp-app my-app --storage local
 ```
 
-Generated environment setting:
+Generated structure:
+
+```text
+lib/
+└─ storage.ts
+
+storage/
+├─ .gitkeep
+└─ README.md
+```
+
+Environment:
 
 ```dotenv
 STORAGE_LOCAL_DIRECTORY=./storage
 ```
 
-The generated helper uses `createLocalStorage()` and adds `storage/` to `.gitignore` so uploaded files are not accidentally committed.
+`.gitignore` keeps the visible scaffold while ignoring runtime objects:
 
-#### Amazon S3
+```gitignore
+storage/*
+!storage/.gitkeep
+!storage/README.md
+```
+
+The generated helper uses `createLocalStorage()`.
+
+### Amazon S3
 
 ```bash
 npx create-bcp-app my-app --storage amazon-s3
@@ -204,9 +242,9 @@ 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.
+The helper uses `createS3Storage()`. Explicit credentials can remain unset when deployment uses the AWS SDK server-side credential chain, such as an IAM role.
 
-#### Cloudflare R2
+### Cloudflare R2
 
 ```bash
 npx create-bcp-app my-app --storage cloudflare-r2
@@ -222,7 +260,7 @@ R2_SECRET_ACCESS_KEY=
 R2_PREFIX=
 ```
 
-The generated helper uses the S3-compatible BCP adapter with:
+The helper configures the S3-compatible adapter with:
 
 ```text
 region: auto
@@ -231,11 +269,11 @@ 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.
+The storage preset is only an initial scaffold; application routes/services can later use another BCP adapter while keeping generic storage APIs.
 
-### JWT Cookie authentication
+## JWT Cookie authentication
 
-Selecting `JWT Cookie` creates a secure-by-default authentication foundation:
+Selecting `JWT Cookie` creates:
 
 ```text
 lib/
@@ -247,32 +285,44 @@ app/api/auth/
 └─ me/route.ts
 ```
 
-The preset uses the session primitives from `bcp/server` and adds this environment variable:
+and adds:
 
 ```dotenv
 BCP_SESSION_SECRET=
 ```
 
-Set `BCP_SESSION_SECRET` to a cryptographically random secret of at least 32 bytes before using authentication.
+Set this to a cryptographically random secret of at least 32 bytes before real authentication use.
 
-The generated `authenticateCredentials(email, password)` intentionally returns `null` until the application connects it to its own user table and password-hash verification. This prevents a newly generated application from accepting unverified credentials or trusting identity data sent directly by the browser.
+The generated `authenticateCredentials(email, password)` returns `null` until the application connects it to its own user store and password-hash verification. This prevents a fresh project from trusting unverified browser identity data.
 
-After implementing credential verification, the generated flow is:
+## Project generators after creation
 
-```text
-POST /api/auth/login
-  -> authenticateCredentials()
-  -> createSession()
-  -> HttpOnly JWT cookie
+BCP `0.1.29+` can scaffold additional framework files after the project has been created:
+
+```bash
+npm run generate -- page dashboard/users
+npm run generate -- api users
+npm run generate -- middleware
+npm run generate -- migration create_users
+```
 
-GET /api/auth/me
-  -> getSession()
-  -> current user
+Equivalent direct CLI:
 
-POST /api/auth/logout
-  -> destroySession()
+```bash
+bcp generate page dashboard/users
+bcp generate api users
+bcp generate middleware
+bcp generate migration create_users
+```
+
+From PowerShell:
+
+```powershell
+npm exec -- bcp-framework generate page dashboard/users
 ```
 
+Use `--force` only when intentionally replacing an existing page/API/middleware scaffold.
+
 ## Options
 
 ```text
@@ -297,8 +347,8 @@ npx create-bcp-app my-app --no-tailwind --database mongodb
 npx create-bcp-app my-app --yes
 ```
 
-The `--bcp` option is primarily useful for prerelease and local package testing, for example:
+The `--bcp` option is mainly for prerelease/local package verification:
 
 ```bash
-npx create-bcp-app my-app --bcp file:../bcp-0.1.27.tgz
+npx create-bcp-app my-app --bcp file:../chidchanun-bcp-0.1.29.tgz
 ```

package/package.json

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

package/src/index.mjs

@@ -55,6 +55,9 @@ export async function createBcpApp(
         normalizeStorageProvider(
             options.storage
         );
+    const packageManager =
+        options.packageManager ??
+        "npm";
 
     ensureTargetDirectory(
         targetDirectory
@@ -99,6 +102,8 @@ export async function createBcpApp(
                 "bcp start",
             routes:
                 "bcp routes",
+            generate:
+                "bcp generate",
             update:
                 "bcp update",
             typecheck:
@@ -164,13 +169,31 @@ export async function createBcpApp(
         "utf8"
     );
 
+    writeProjectMetadata(
+        targetDirectory,
+        {
+            projectName,
+            packageSpecifier,
+            packageManager,
+            createBcpAppVersion:
+                packageMetadata.version,
+            tailwind:
+                selectedOptions.tailwind,
+            database:
+                selectedOptions.database,
+            auth:
+                selectedOptions.auth,
+            storage:
+                selectedStorage,
+        }
+    );
+
     if (
         options.install !== false
     ) {
         await runInstall(
             targetDirectory,
-            options.packageManager ??
-                "npm"
+            packageManager
         );
     }
 
@@ -426,6 +449,53 @@ function configureFrameworkAuthEntry(
     );
 }
 
+function writeProjectMetadata(
+    targetDirectory,
+    metadata
+) {
+    const manifest = {
+        schemaVersion:
+            1,
+        framework:
+            "bcp",
+        projectName:
+            metadata.projectName,
+        frameworkPackage:
+            metadata.packageSpecifier,
+        createdWith: {
+            package:
+                "create-bcp-app",
+            version:
+                metadata.createBcpAppVersion,
+        },
+        packageManager:
+            metadata.packageManager,
+        presets: {
+            tailwind:
+                metadata.tailwind,
+            database:
+                metadata.database,
+            auth:
+                metadata.auth,
+            storage:
+                metadata.storage,
+        },
+    };
+
+    fs.writeFileSync(
+        path.join(
+            targetDirectory,
+            "bcp.project.json"
+        ),
+        `${JSON.stringify(
+            manifest,
+            null,
+            2
+        )}\n`,
+        "utf8"
+    );
+}
+
 function readPackageMetadata() {
     const packageJson =
         JSON.parse(

package/template/README.md

@@ -17,32 +17,66 @@ Generated projects use the project-local BCP Framework CLI through npm scripts:
 ```bash
 npm run dev
 npm run routes
+npm run generate -- page dashboard/users
 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.
+The generated scripts call commands such as `bcp dev`, `bcp generate`, `bcp build` and `bcp start`. npm automatically adds the project's `node_modules/.bin` directory to `PATH` while an npm script is running.
 
-## Direct CLI usage
+## Project metadata
 
-BCP Framework is installed as a **project-local dependency**. It is not installed globally by `create-bcp-app`.
+Projects created with BCP `0.1.29+` include:
 
-Because of that, typing this directly in a normal PowerShell session may not work:
+```text
+bcp.project.json
+```
 
-```powershell
-bcp-framework doctor
+It records non-secret scaffold choices such as Tailwind, database, authentication and storage presets so BCP diagnostics/tooling can understand the project without guessing configuration from source files.
+
+Commit this file with the project. Do not put passwords, access keys, session secrets or tokens in it.
+
+## Generate framework files
+
+BCP `0.1.29+` can generate common project files:
+
+```bash
+npm run generate -- page dashboard/users
+npm run generate -- api users
+npm run generate -- middleware
+npm run generate -- migration create_users
 ```
 
-PowerShell does not automatically add `node_modules/.bin` to its normal command search path.
+Equivalent direct BCP CLI commands are:
 
-Use `npm exec` when you want to invoke the project-local CLI directly:
+```bash
+bcp generate page dashboard/users
+bcp generate api users
+bcp generate middleware
+bcp generate migration create_users
+```
+
+Existing page/API/middleware targets are not replaced unless `--force` is supplied explicitly.
+
+After generating routes, inspect them with:
+
+```bash
+npm run routes
+```
+
+## Direct CLI usage
+
+BCP Framework is installed as a project-local dependency. It is not installed globally by `create-bcp-app`.
+
+PowerShell does not automatically add `node_modules/.bin` to its normal command search path, so use `npm exec` for direct commands:
 
 ```powershell
 npm exec -- bcp-framework --version
 npm exec -- bcp-framework doctor
 npm exec -- bcp-framework inspect
+npm exec -- bcp-framework generate page dashboard/users
 npm exec -- bcp-framework routes
 npm exec -- bcp-framework dev
 npm exec -- bcp-framework build
@@ -54,11 +88,7 @@ You can also execute the Windows command shim explicitly:
 .\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.
+Microsoft SQL Server can install another Windows executable named `bcp.exe`, so the `bcp-framework` alias avoids that command-name collision.
 
 Use this convention:
 
@@ -67,6 +97,24 @@ Inside npm scripts      -> bcp ...
 Direct PowerShell usage -> npm exec -- bcp-framework ...
 ```
 
+## Project diagnostics
+
+Run:
+
+```powershell
+npm exec -- bcp-framework doctor
+npm exec -- bcp-framework inspect
+```
+
+Machine-readable reports:
+
+```powershell
+npm exec -- bcp-framework doctor --json
+npm exec -- bcp-framework inspect --json
+```
+
+Doctor checks common project/runtime problems while Inspect shows the resolved configuration, routes, dependencies and project metadata BCP sees.
+
 ## Production
 
 Create the standalone production build: