@chidchanun/bcp 0.1.27 → 0.1.29

package/README.md

@@ -2,9 +2,9 @@
 
 BCP Framework is a React full-stack framework focused on file-based routing, SSR, server data loading, guarded application flows, API routes, authentication, database access, validation, logging, uploads, storage and standalone production deployment.
 
-> **Development target:** `0.1.27`
+> **Development target:** `0.1.29`
 >
-> BCP is pre-1.0. The `0.1.27` source adds the Storage Ecosystem and remains an unreleased development target until local validation, RC checks, tagging and npm publication complete.
+> BCP is pre-1.0. The `0.1.29` source adds the Developer Experience milestone and remains an unreleased development target until local validation, RC checks, tagging and npm publication complete.
 
 ## Current capabilities
 
@@ -24,8 +24,9 @@ BCP Framework is a React full-stack framework focused on file-based routing, SSR
 | Uploads | Buffered multipart helpers and production multipart streaming |
 | Storage | Local + S3-compatible adapters, streaming, listing, copy/move, metadata, bulk delete and signed S3 URLs |
 | Caching | Response cache and revalidation primitives |
-| Developer tools | `doctor`, `inspect`, updater and route inspection |
-| Production | Standalone server build with production middleware pipeline |
+| Developer tools | Project generators, `doctor` / `inspect` v2, updater, route inspection and project metadata |
+| Production | Standalone build, hardening gateway, graceful shutdown, trusted-proxy controls and HTTP timeouts |
+| Documentation | Markdown source map plus `docs/docs-web-manifest.json` for `bcp-docs-web` |
 
 ## Requirements
 
@@ -115,6 +116,37 @@ app/api/users/[id]/route.ts      /api/users/:id
 
 Read more: [Routing](docs/routing.md)
 
+## Project generators — 0.1.29
+
+BCP `0.1.29` adds generators for common framework files:
+
+```bash
+bcp generate page dashboard/users
+bcp generate page users/[id]
+bcp generate api users
+bcp generate middleware
+bcp generate migration create_users
+```
+
+Generated targets:
+
+```text
+page       -> app/<route>/page.tsx
+api        -> app/api/<route>/route.ts
+middleware -> middleware.ts
+migration  -> migrations/<timestamp>_<name>.ts
+```
+
+Page/API/middleware generators do not overwrite existing files unless `--force` is explicitly supplied:
+
+```bash
+bcp generate page dashboard/users --force
+```
+
+Migration generation reuses the existing database migration implementation so migration naming and format remain centralized.
+
+Read more: [Project Generators](docs/generators.md)
+
 ## Server data, guards and actions
 
 Server loaders live next to their route in `loader.ts`. Route authorization can be defined in `guard.ts`, while route-owned mutations live in `actions.ts`.
@@ -229,6 +261,8 @@ const storage =
     });
 ```
 
+`create-bcp-app --storage local` creates `lib/storage.ts` plus a visible `storage/README.md` / `.gitkeep` scaffold. Runtime objects remain ignored by Git.
+
 ### S3 / R2 / MinIO
 
 ```ts
@@ -268,7 +302,7 @@ Read more: [Storage and File Delivery](docs/storage.md)
 
 ### Storage Ecosystem — 0.1.27
 
-BCP `0.1.27` adds a richer, additive object-storage API without invalidating older `StorageAdapter` implementations:
+BCP `0.1.27` added a richer, additive object-storage API without invalidating older `StorageAdapter` implementations:
 
 ```ts
 import {
@@ -284,72 +318,9 @@ import {
 } from "bcp/server";
 ```
 
-Listing supports prefix filtering, limits and opaque cursors:
-
-```ts
-const page =
-    await listStorageObjects(
-        storage,
-        {
-            prefix: "documents/",
-            limit: 50,
-        }
-    );
-```
-
-Copy and move use native adapter operations when available, with portable fallback behavior where practical:
+Listing supports prefix filtering, limits and opaque cursors. Copy and move use native adapter operations when available, with portable fallback behavior where practical. Portable user metadata is string-to-string metadata and is distinct from authorization/business state.
 
-```ts
-await copyStorageObject(
-    storage,
-    "incoming/report.pdf",
-    "archive/report.pdf"
-);
-
-await moveStorageObject(
-    storage,
-    "tmp/avatar.webp",
-    "users/42/avatar.webp"
-);
-```
-
-Portable user metadata is string-to-string metadata and is distinct from application authorization/business state:
-
-```ts
-await setStorageMetadata(
-    storage,
-    "archive/report.pdf",
-    {
-        owner: "user-42",
-        status: "approved",
-    }
-);
-```
-
-S3-compatible storage also supports short-lived presigned direct-transfer URLs:
-
-```ts
-const downloadUrl =
-    await createStorageSignedReadUrl(
-        storage,
-        "videos/demo.mp4",
-        {
-            expiresIn: 300,
-        }
-    );
-
-const uploadUrl =
-    await createStorageSignedWriteUrl(
-        storage,
-        "uploads/demo.mp4",
-        {
-            expiresIn: 300,
-            contentType: "video/mp4",
-        }
-    );
-```
-
-Local storage intentionally does not emulate signed URLs. Signed URLs are temporary credentials and should only be generated after application authorization.
+S3-compatible storage also supports short-lived presigned direct-transfer URLs. Local storage intentionally does not emulate signed URLs.
 
 Read more: [Storage Ecosystem](docs/storage-ecosystem.md)
 
@@ -401,7 +372,85 @@ Standalone output is written under:
    └─ server.mjs
 ```
 
-Read more: [Deployment](docs/deployment.md)
+### Production Hardening — 0.1.28
+
+The standalone runtime is wrapped by a public hardening gateway with configurable HTTP and shutdown behavior:
+
+```dotenv
+BCP_REQUEST_TIMEOUT_MS=120000
+BCP_HEADERS_TIMEOUT_MS=66000
+BCP_KEEP_ALIVE_TIMEOUT_MS=65000
+BCP_SHUTDOWN_TIMEOUT_MS=10000
+BCP_TRUST_PROXY=false
+```
+
+Standalone production handles `SIGTERM` and `SIGINT`, drains the public listener, runs application cleanup hooks and then stops internal runtime layers.
+
+```ts
+import {
+    registerShutdownHook,
+} from "bcp/server";
+
+registerShutdownHook(
+    () => {
+        storage.destroy();
+    },
+    {
+        name: "storage",
+    }
+);
+```
+
+Trusted proxy mode is disabled by default. Enable `BCP_TRUST_PROXY=true` only when direct untrusted traffic cannot bypass the trusted reverse proxy/load balancer.
+
+Read more: [Production Hardening](docs/production-hardening.md)
+
+## Doctor and Inspect v2 — 0.1.29
+
+`bcp doctor` now includes additional project/runtime diagnostics for:
+
+```text
+lockfile / package manager
+multiple framework dependency declarations
+standalone production artifact
+Docker + reproducible install guidance
+storage provider
+production-hardening environment validity
+```
+
+`bcp inspect` keeps its existing fields and adds a machine-readable `project` object with project metadata, selected presets and runtime/deployment information.
+
+```powershell
+npm exec -- bcp-framework doctor --json
+npm exec -- bcp-framework inspect --json
+```
+
+Read more: [Developer Tools](docs/developer-tools.md)
+
+## Project metadata — 0.1.29
+
+New `create-bcp-app` projects include `bcp.project.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "framework": "bcp",
+  "projectName": "my-app",
+  "packageManager": "npm",
+  "presets": {
+    "tailwind": true,
+    "database": "mysql",
+    "auth": "jwt-cookie",
+    "storage": "local"
+  }
+}
+```
+
+This file stores only non-secret scaffold metadata. Credentials, database passwords, access keys, JWT/session secrets and tokens stay in environment/server-only configuration.
+
+Existing projects without the file continue to work; diagnostic tooling falls back to project files where practical.
+
+Read more: [Project Metadata](docs/project-metadata.md)
 
 ## Windows CLI
 
@@ -416,6 +465,7 @@ npm exec -- bcp-framework --version
 npm exec -- bcp-framework doctor
 npm exec -- bcp-framework inspect
 npm exec -- bcp-framework routes
+npm exec -- bcp-framework generate page dashboard/users
 npm exec -- bcp-framework dev
 npm exec -- bcp-framework build
 ```
@@ -428,7 +478,7 @@ Read more: [Developer Tools](docs/developer-tools.md)
 bcp update
 bcp update --check
 bcp update --dry-run
-bcp update 0.1.27
+bcp update 0.1.29
 bcp update next
 ```
 
@@ -450,16 +500,39 @@ A version must not be tagged or published until its RC and packed-package verifi
 
 Read more: [Releasing](docs/releasing.md)
 
-## Documentation source
+## Documentation source and `bcp-docs-web`
 
 The `docs/` directory is the authored source for **`bcp-docs-web`**.
 
+Starting with `0.1.29`, docs-web should consume:
+
+```text
+docs/docs-web-manifest.json
+```
+
+for sidebar/navigation and route mapping. Markdown files remain the documentation content source of truth.
+
+The manifest contains:
+
+```text
+section id/title
+website route
+Markdown source file
+page title
+version target
+release state
+release routes
+```
+
 Recommended starting points:
 
+- [Docs-Web Manifest](docs/docs-web-manifest.json)
 - [Documentation Source Map](docs/README.md)
 - [Getting Started](docs/getting-started.md)
 - [Configuration](docs/configuration.md)
+- [Project Metadata](docs/project-metadata.md)
 - [Routing](docs/routing.md)
+- [Project Generators](docs/generators.md)
 - [Server Data Loaders](docs/server-data-loaders.md)
 - [Route Guards](docs/route-guards.md)
 - [Form Actions](docs/form-actions.md)
@@ -468,6 +541,7 @@ Recommended starting points:
 - [Storage and File Delivery](docs/storage.md)
 - [Storage Ecosystem](docs/storage-ecosystem.md)
 - [S3-Compatible Storage](docs/s3-storage.md)
+- [Production Hardening](docs/production-hardening.md)
 - [Authentication](docs/authentication.md)
 - [Database](docs/database.md)
 - [Middleware](docs/middleware.md)
@@ -487,20 +561,22 @@ Recommended starting points:
 | `0.1.25` | Storage Adapters and File Delivery |
 | `0.1.26` | S3-Compatible Storage and Production Streaming |
 | `0.1.27` | Storage Ecosystem |
+| `0.1.28` | Production Hardening |
+| `0.1.29` | Developer Experience |
 
 ## Next direction
 
-After `0.1.27`, the planned milestone is **`0.1.28 — Production Hardening`**:
+After `0.1.29`, the planned major milestone is **`0.2.0 — Framework Platform`**.
+
+The focus should be consolidation rather than unrelated feature growth:
 
-1. graceful HTTP shutdown and active-request draining,
-2. database/S3 resource cleanup,
-3. trusted proxy and forwarded-header handling,
-4. request/server timeout controls,
-5. security hardening,
-6. Docker and standalone-runtime regression coverage,
-7. stronger startup/runtime diagnostics.
+1. public API consistency and compatibility expectations,
+2. production-runtime stabilization across supported deployment paths,
+3. documentation completeness and docs-web integration,
+4. migration guidance for pre-`0.2.0` applications,
+5. a documented platform baseline for routing, data, auth, database, storage and runtime APIs.
 
-These are roadmap items, not `0.1.27` guarantees.
+These are roadmap goals, not `0.1.29` guarantees.
 
 ## License