@chidchanun/bcp 0.1.28 → 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.28`
+> **Development target:** `0.1.29`
 >
-> BCP is pre-1.0. The `0.1.28` source adds Production Hardening 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 |
+| 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`.
@@ -270,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 {
@@ -373,6 +405,53 @@ Trusted proxy mode is disabled by default. Enable `BCP_TRUST_PROXY=true` only wh
 
 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
 
 Microsoft SQL Server can install another executable named `bcp.exe`. BCP publishes the collision-free alias `bcp-framework`.
@@ -386,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
 ```
@@ -398,7 +478,7 @@ Read more: [Developer Tools](docs/developer-tools.md)
 bcp update
 bcp update --check
 bcp update --dry-run
-bcp update 0.1.28
+bcp update 0.1.29
 bcp update next
 ```
 
@@ -420,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)
@@ -459,18 +562,21 @@ Recommended starting points:
 | `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.28`, the planned milestone is **`0.1.29 — Developer Experience`**:
+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. route/API/middleware/migration generators,
-2. richer `doctor` and `inspect` diagnostics,
-3. clearer build/runtime error messages,
-4. improved create-app presets and automation flags,
-5. production configuration 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.28` guarantees.
+These are roadmap goals, not `0.1.29` guarantees.
 
 ## License
 

package/docs/README.md

@@ -1,10 +1,10 @@
 # BCP Framework Documentation Source
 
-The `docs/` directory is the documentation source of truth for BCP Framework and is intentionally organized for the **`bcp-docs-web`** website.
+The `docs/` directory is the documentation source of truth for BCP Framework and is intentionally organized for **`bcp-docs-web`**.
 
-> **Documentation target:** BCP Framework `0.1.28`
+> **Documentation target:** BCP Framework `0.1.29`
 >
-> **Release state:** unreleased development target. Do not label `0.1.28` as published until RC validation and npm publication complete.
+> **Release state:** unreleased development target. Do not label `0.1.29` as published until RC validation, tagging and npm publication complete.
 
 ## Documentation flow
 
@@ -13,10 +13,45 @@ BCP Framework source/tests
         ↓
       docs/
         ↓
+Markdown content + docs-web manifest
+        ↓
    bcp-docs-web
 ```
 
-Framework source and tests are authoritative for behavior. Markdown under `docs/` is the authored documentation layer. `bcp-docs-web` should render, organize and search these sources instead of becoming a competing source of truth.
+Framework source and tests are authoritative for behavior. Markdown under `docs/` is the authored documentation layer. `bcp-docs-web` should render, organize and search these sources rather than becoming a competing source of truth.
+
+## Docs-web navigation contract — 0.1.29
+
+`docs/docs-web-manifest.json` is the explicit navigation and route contract for the docs website.
+
+It defines:
+
+```text
+schema version
+framework/version target
+release state
+section IDs/titles
+website routes
+Markdown source files
+page titles
+release routes
+```
+
+Recommended docs-web workflow:
+
+```text
+read docs/docs-web-manifest.json
+          ↓
+generate sidebar + route map
+          ↓
+load referenced Markdown file
+          ↓
+render content/search/prev-next
+```
+
+Do not duplicate this mapping in a second hard-coded sidebar unless the website needs a temporary bootstrap fallback.
+
+Markdown remains the content source; the manifest contains navigation metadata only.
 
 ## Update rule
 
@@ -24,12 +59,15 @@ When framework behavior changes:
 
 1. Update framework source.
 2. Add/update regression tests.
-3. Update the matching file under `docs/`.
-4. Update `docs/releases/<version>.md`.
-5. Change release state to published only after npm publication succeeds.
+3. Update the matching Markdown file under `docs/`.
+4. Update `docs/docs-web-manifest.json` when routes/navigation change.
+5. Update `docs/releases/<version>.md`.
+6. Change release state to published only after npm publication succeeds.
 
 ## Recommended `bcp-docs-web` navigation
 
+The current manifest groups documentation into:
+
 ```text
 Getting Started
 Routing & Data
@@ -37,7 +75,7 @@ Authentication
 Database
 Runtime & Infrastructure
 Storage & Uploads
-API Reference
+Developer Experience
 Releases
 ```
 
@@ -48,6 +86,7 @@ Releases
 | `/docs/getting-started` | `getting-started.md` | Create and run a BCP application |
 | `/docs/configuration` | `configuration.md` | Framework configuration/environment |
 | `/docs/application-modules` | `application-modules.md` | Client/server boundaries |
+| `/docs/project-metadata` | `project-metadata.md` | `bcp.project.json` schema and security boundary |
 | `/docs/deployment` | `deployment.md` | Standalone production deployment |
 | `/docs/updating` | `updating.md` | Framework upgrades |
 
@@ -84,11 +123,10 @@ Releases
 | --- | --- | --- |
 | `/docs/middleware` | `middleware.md` | Middleware System v2 |
 | `/docs/hydration` | `hydration.md` | SSR/client hydration parity |
-| `/docs/developer-tools` | `developer-tools.md` | `doctor` / `inspect` |
 | `/docs/development-logging` | `development-logging.md` | Logging/observability |
 | `/docs/caching` | `caching.md` | Cache/revalidation |
 | `/docs/security` | `security.md` | Security/body limits |
-| `/docs/production-hardening` | `production-hardening.md` | Graceful shutdown, trusted proxy and production timeouts |
+| `/docs/production-hardening` | `production-hardening.md` | Graceful shutdown, trusted proxy and timeouts |
 
 ### Storage & Uploads
 
@@ -99,6 +137,13 @@ Releases
 | `/docs/storage-ecosystem` | `storage-ecosystem.md` | Listing, copy/move, metadata, bulk delete, signed URLs |
 | `/docs/s3-storage` | `s3-storage.md` | S3/R2/MinIO adapter and direct object access |
 
+### Developer Experience
+
+| Website route | Markdown source | Purpose |
+| --- | --- | --- |
+| `/docs/generators` | `generators.md` | Page/API/middleware/migration generators |
+| `/docs/developer-tools` | `developer-tools.md` | Doctor/Inspect v2 and diagnostics |
+
 ## API Reference ownership
 
 Recommended entrypoint groups:
@@ -156,16 +201,16 @@ bcp/middleware
 
 ### Storage & Uploads
 
-- buffered multipart `FormData` upload APIs
+- buffered multipart upload APIs
 - production streaming multipart upload (`storeMultipartFile()`)
 - backward-compatible `StorageAdapter` contract
 - local filesystem storage
-- S3/R2/MinIO-compatible storage
+- Amazon S3 / Cloudflare R2 / MinIO-compatible storage
 - streaming reads/writes and byte ranges
 - ETag/Last-Modified file delivery
 - upload/storage limits and abort cleanup
 - object listing with cursors
-- native/fallback copy and move
+- copy and move
 - portable user metadata
 - bulk deletion
 - S3 presigned read/write URLs
@@ -179,66 +224,61 @@ bcp/middleware
 - transactions
 - migrations/status/rollback
 
-### Developer Experience
+### Developer Experience — 0.1.29
 
 - `create-bcp-app`
+- non-secret `bcp.project.json`
+- `bcp generate page`
+- `bcp generate api`
+- `bcp generate middleware`
+- `bcp generate migration`
 - `bcp update`
-- `bcp doctor`
-- `bcp inspect`
+- Doctor/Inspect v2
+- lockfile/package-manager diagnostics
+- duplicate framework declaration checks
+- storage/provider diagnostics
+- production-build/Docker/hardening diagnostics
 - Windows-safe `bcp-framework` alias
-- standalone production build
-- unit/integration/E2E/package/RC checks
+- `docs/docs-web-manifest.json`
 
-## BCP 0.1.28 documentation focus
+## BCP 0.1.29 documentation focus
 
-### Production hardening
+### Project generators
 
-Public cleanup API:
-
-```ts
-import {
-    getProductionHardeningConfig,
-    registerShutdownHook,
-} from "bcp/server";
+```bash
+bcp generate page dashboard/users
+bcp generate api users
+bcp generate middleware
+bcp generate migration create_users
 ```
 
-Production environment controls:
+Page/API/middleware generation requires `--force` before replacing existing target files.
 
-```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
-```
+See `generators.md`.
 
-Document these boundaries clearly:
+### Doctor / Inspect v2
 
-- trusted proxy mode is off by default,
-- forwarding headers are sanitized when trust is disabled,
-- enable trust only behind a trusted reverse proxy/load balancer,
-- Docker/process-manager `SIGTERM` triggers graceful shutdown,
-- shutdown hooks are process-lifetime resource cleanup, not request cleanup,
-- shutdown force-closes remaining public connections after the configured timeout.
+Doctor adds deployment/project-health checks without removing previous checks. Inspect keeps its previous JSON fields and adds a `project` object containing lockfile, package manager, project metadata/presets, build presence, Dockerfile, framework declarations, storage provider and hardening status.
 
-See `production-hardening.md`.
+See `developer-tools.md`.
 
-### Local Server generator fix
+### Project metadata
 
-`create-bcp-app --storage local` now generates:
+New `create-bcp-app` projects receive:
 
 ```text
-lib/storage.ts
-storage/
-├─ .gitkeep
-└─ README.md
+bcp.project.json
 ```
 
-Runtime objects remain ignored while the scaffold stays visible/tracked.
+The file records scaffold choices only and must never contain credentials/secrets.
+
+See `project-metadata.md`.
+
+### Docs-web contract
 
-### 0.1.27 storage ecosystem remains supported
+`docs/docs-web-manifest.json` is intended to be consumed directly by `bcp-docs-web` for navigation and route generation.
 
-The storage ecosystem continues to include listing, copy/move, portable metadata, bulk deletion and S3 signed URLs. `0.1.28` hardens deployment/runtime behavior rather than replacing those APIs.
+The website should still read the Markdown source referenced by each manifest page entry.
 
 ## CLI commands
 
@@ -247,6 +287,10 @@ bcp dev
 bcp routes
 bcp build
 bcp start
+bcp generate page dashboard/users
+bcp generate api users
+bcp generate middleware
+bcp generate migration create_users
 bcp doctor
 bcp doctor --json
 bcp inspect
@@ -265,6 +309,7 @@ On Windows, direct project-local commands should prefer:
 ```powershell
 npm exec -- bcp-framework doctor
 npm exec -- bcp-framework inspect
+npm exec -- bcp-framework generate page dashboard/users
 npm exec -- bcp-framework dev
 npm exec -- bcp-framework build
 ```
@@ -279,9 +324,10 @@ Release notes live under:
 docs/releases/
 ```
 
-Recommended routes:
+The docs-web manifest currently maps:
 
 ```text
+/releases/0.1.29
 /releases/0.1.28
 /releases/0.1.27
 /releases/0.1.26
@@ -299,25 +345,49 @@ unreleased development target
 
 The existence of a release note alone does not mean the npm version is published.
 
-## Suggested website model
+## Suggested docs-web implementation
+
+A simple implementation can model the manifest like:
 
 ```ts
-interface DocPage {
-    title: string;
-    slug: string;
-    section: string;
-    sourceFile: string;
-    versionTarget?: string;
-    releaseState?:
-        | "published"
-        | "rc"
-        | "unreleased";
+interface DocsWebManifest {
+    schemaVersion: number;
+    framework: string;
+    versionTarget: string;
+    releaseState: string;
+    sections: Array<{
+        id: string;
+        title: string;
+        pages: Array<{
+            route: string;
+            source: string;
+            title: string;
+        }>;
+    }>;
+    releases: Array<{
+        route: string;
+        source: string;
+        version: string;
+        state?: string;
+    }>;
 }
 ```
 
+Recommended website behavior:
+
+1. Load/validate `docs-web-manifest.json` at build/startup.
+2. Build the sidebar in manifest order.
+3. Resolve each route to its referenced Markdown source.
+4. Generate previous/next links from manifest order.
+5. Index rendered Markdown headings/content for search.
+6. Use `versionTarget` / `releaseState` for the site banner.
+7. Use release entries for the release navigation.
+
+Do not expose `bcp.project.json` secrets because the project metadata format is intentionally non-secret; runtime `.env` files should never be ingested into public docs output.
+
 ## Suggested website features
 
-1. Sidebar navigation from this source map.
+1. Sidebar from `docs-web-manifest.json`.
 2. Markdown rendering + syntax highlighting.
 3. Previous/next navigation.
 4. Version/release-state banner.
@@ -359,35 +429,48 @@ npm run test:package
 npm run rc:check
 ```
 
-For `0.1.28`, package validation must confirm the staged artifact includes the production hardening runtime/gateway, shutdown APIs, Local Server generator fix, and the existing S3 runtime dependencies.
+For `0.1.29`, validation should cover project generators, Doctor/Inspect v2, create-app project metadata, the existing production hardening runtime and package preparation.
 
-A representative Docker app should also be built and stopped with `docker stop` to verify graceful `SIGTERM` shutdown.
+The release lockfile must be synchronized to `0.1.29` before the final tag.
 
 ## Documentation QA checklist
 
-- linked Markdown files exist,
-- examples use public exports,
+- every manifest Markdown source exists,
+- every manifest route is unique,
+- examples use public exports/CLI commands,
 - version/release states are current,
 - Windows direct CLI examples use `npm exec -- bcp-framework`,
 - upload/storage/auth security caveats are present,
 - release notes match the framework version,
 - S3 credentials are never shown as public browser variables,
-- signed URLs are documented as temporary credentials,
-- proxy trust is documented as opt-in,
-- roadmap APIs are not presented as published guarantees.
+- project metadata remains non-secret,
+- proxy trust remains documented as opt-in,
+- roadmap APIs are not presented as release guarantees.
 
-## Next direction after 0.1.28
+## Next direction after 0.1.29
 
-Planned `0.1.29 — Developer Experience` focus:
+Planned **`0.2.0 — Framework Platform`** focus:
 
-- generators for common framework files,
-- richer `doctor` and `inspect`,
-- improved build/runtime diagnostics,
-- create-app preset improvements,
-- production configuration diagnostics.
+- consolidate public API naming/behavior,
+- document compatibility expectations,
+- stabilize supported production deployment paths,
+- complete docs-web integration and documentation coverage,
+- publish migration guidance for pre-`0.2.0` applications,
+- establish a platform baseline before broader feature expansion.
 
-These remain roadmap items until their source/tests land.
+These remain roadmap goals until their source/tests land.
 
 ## Repository authority
 
-The framework repository remains authoritative for source, public exports, tests, docs and release notes. `bcp-docs-web` is the presentation/search/navigation layer for this content.
+The framework repository remains authoritative for:
+
+```text
+source
+public exports
+tests
+Markdown docs
+docs-web manifest
+release notes
+```
+
+`bcp-docs-web` is the presentation/search/navigation layer for this content.