@chidchanun/bcp 0.1.27 → 0.1.29

package/docs/production-hardening.md

@@ -0,0 +1,152 @@
+# Production Hardening
+
+BCP Framework `0.1.28` adds a production hardening gateway around the standalone runtime.
+
+The gateway is the public HTTP listener. Existing security, cache, critical CSS, page/API and SSR runtimes remain bound to internal loopback ports behind it.
+
+## Default production behavior
+
+The hardening gateway configures Node HTTP timeouts and graceful shutdown defaults:
+
+```text
+Request timeout:    120000 ms
+Headers timeout:     66000 ms
+Keep-alive timeout:  65000 ms
+Shutdown timeout:    10000 ms
+Trust proxy:         false
+```
+
+Override them with server-only environment variables:
+
+```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
+```
+
+`BCP_HEADERS_TIMEOUT_MS` must be greater than `BCP_KEEP_ALIVE_TIMEOUT_MS`.
+
+## Graceful shutdown
+
+Standalone production now handles `SIGTERM` and `SIGINT`.
+
+This is especially important for Docker, Kubernetes and process managers that send `SIGTERM` before stopping a process.
+
+Shutdown order:
+
+```text
+stop accepting public traffic
+        ↓
+drain/close public HTTP connections
+        ↓
+run application shutdown hooks
+        ↓
+stop internal BCP runtime layers
+        ↓
+process exits naturally
+```
+
+If the public server does not close before `BCP_SHUTDOWN_TIMEOUT_MS`, BCP force-closes remaining connections.
+
+## Application shutdown hooks
+
+Register cleanup work through `bcp/server`:
+
+```ts
+import {
+    registerShutdownHook,
+} from "bcp/server";
+
+const unregister =
+    registerShutdownHook(
+        async () => {
+            await closeApplicationResources();
+        },
+        {
+            name: "application-resources",
+        }
+    );
+```
+
+Hooks run in reverse registration order. Calling the returned function unregisters the hook.
+
+For S3-compatible storage, an application can register the adapter client cleanup when it owns the adapter for the lifetime of the process:
+
+```ts
+registerShutdownHook(
+    () => {
+        storage.destroy();
+    },
+    {
+        name: "s3-storage",
+    }
+);
+```
+
+Do not register request-scoped resources as process shutdown hooks.
+
+## Trusted proxy mode
+
+The hardening gateway sanitizes forwarding headers by default.
+
+```dotenv
+BCP_TRUST_PROXY=false
+```
+
+This prevents a direct client from spoofing headers such as:
+
+```text
+Forwarded
+X-Forwarded-For
+X-Forwarded-Host
+X-Forwarded-Proto
+X-Real-IP
+```
+
+When BCP is deployed only behind a trusted reverse proxy such as Nginx, Cloudflare Tunnel or a trusted load balancer, enable:
+
+```dotenv
+BCP_TRUST_PROXY=true
+```
+
+BCP then preserves the trusted proxy forwarding chain and appends the immediate peer address where appropriate.
+
+Only enable trusted proxy mode when direct untrusted traffic cannot bypass the trusted proxy.
+
+## Docker
+
+A production compose service can use:
+
+```yaml
+services:
+  app:
+    init: true
+    restart: unless-stopped
+    environment:
+      NODE_ENV: production
+      BCP_HOSTNAME: 0.0.0.0
+      BCP_PORT: 3000
+      BCP_SHUTDOWN_TIMEOUT_MS: 10000
+      BCP_TRUST_PROXY: "true"
+```
+
+Set `BCP_TRUST_PROXY=true` only when the container receives requests exclusively from a trusted reverse proxy/network path.
+
+Docker's stop grace period should be longer than `BCP_SHUTDOWN_TIMEOUT_MS` so BCP gets time to drain connections and cleanup resources.
+
+## Local Server storage scaffold
+
+`create-bcp-app --storage local` now creates:
+
+```text
+lib/storage.ts
+storage/
+├─ .gitkeep
+└─ README.md
+```
+
+Runtime objects inside `storage/` are ignored while the scaffold files remain tracked. The generated README explains that BCP writes objects and `.bcp-storage-meta` metadata there at runtime.
+
+The directory therefore no longer appears as an unexplained empty folder before the first upload.

package/docs/project-metadata.md

@@ -0,0 +1,112 @@
+# Project Metadata
+
+BCP Framework `0.1.29` makes generated project presets explicit through `bcp.project.json`.
+
+`create-bcp-app` writes this file after applying the selected project options.
+
+Example:
+
+```json
+{
+  "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": "cloudflare-r2"
+  }
+}
+```
+
+## Purpose
+
+The metadata file records scaffold choices without requiring later tools to infer them from source code.
+
+It is intended for:
+
+- `bcp doctor`,
+- `bcp inspect`,
+- project migration/update tooling,
+- documentation tooling,
+- `bcp-docs-web` examples and project-aware guidance,
+- future framework upgrade diagnostics.
+
+## Security boundary
+
+`bcp.project.json` must not contain credentials or runtime secrets.
+
+It records only non-secret configuration identities such as:
+
+```text
+Tailwind enabled/disabled
+Database preset name
+Auth preset name
+Storage provider name
+Package manager
+Framework package specifier
+create-bcp-app version
+```
+
+Do not add values such as:
+
+```text
+AWS_ACCESS_KEY_ID
+AWS_SECRET_ACCESS_KEY
+R2_ACCESS_KEY_ID
+R2_SECRET_ACCESS_KEY
+DATABASE_URL
+passwords
+JWT secrets
+session tokens
+```
+
+Runtime configuration stays in environment variables and server-only configuration.
+
+## Schema version
+
+The initial format uses:
+
+```json
+{
+  "schemaVersion": 1
+}
+```
+
+Consumers should check `schemaVersion` before relying on optional metadata fields.
+
+Unknown future fields should normally be ignored so newer `create-bcp-app` versions remain compatible with older tooling where practical.
+
+## Storage provider metadata
+
+Storage choices currently include:
+
+```text
+none
+local
+amazon-s3
+cloudflare-r2
+```
+
+`bcp inspect` can use the metadata first and fall back to inspecting `lib/storage.ts` for older projects without `bcp.project.json`.
+
+## Existing projects
+
+Projects created before `0.1.29` do not need this file to keep running.
+
+The metadata file is additive. Doctor/inspect can still infer core project information from `package.json`, lockfiles, routes and generated source where possible.
+
+If an older project wants to adopt the file manually, keep the schema minimal and do not invent preset values that are not actually in use.
+
+## Source control
+
+`bcp.project.json` should normally be committed to source control because it contains project structure metadata, not secrets.
+
+This allows CI and documentation tooling to read the same preset identity as local developer tooling.

package/docs/releases/0.1.28.md

@@ -0,0 +1,134 @@
+# BCP Framework 0.1.28
+
+BCP Framework `0.1.28` is the **Production Hardening** milestone.
+
+> Release state: unreleased development target until local validation, RC checks, tagging and npm publication complete.
+
+## Highlights
+
+- Added a public production hardening gateway around the existing standalone runtime.
+- Added configurable request, header, keep-alive and shutdown timeouts.
+- Added graceful `SIGTERM` / `SIGINT` handling for Docker and process managers.
+- Added application shutdown hooks through `registerShutdownHook()`.
+- Added trusted-proxy forwarding-header sanitization with secure default `BCP_TRUST_PROXY=false`.
+- Added force-close fallback after the configured graceful shutdown timeout.
+- Fixed `create-bcp-app --storage local` so generated projects no longer contain an unexplained empty storage directory.
+- Added `storage/README.md` and `storage/.gitkeep` while continuing to ignore runtime storage objects.
+- Added regression coverage for production hardening primitives and Local Server scaffolding.
+
+## Production environment controls
+
+```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
+```
+
+Defaults are production-safe and require no configuration for ordinary direct HTTP deployments.
+
+`BCP_HEADERS_TIMEOUT_MS` must be greater than `BCP_KEEP_ALIVE_TIMEOUT_MS`.
+
+## Graceful shutdown
+
+The standalone production runtime now handles:
+
+```text
+SIGTERM
+SIGINT
+```
+
+The runtime first stops/drains the public hardening gateway, then runs application shutdown hooks, then stops internal BCP runtime layers.
+
+After `BCP_SHUTDOWN_TIMEOUT_MS`, remaining public connections are force-closed.
+
+## Public API addition
+
+```ts
+import {
+    getProductionHardeningConfig,
+    registerShutdownHook,
+} from "bcp/server";
+```
+
+Example:
+
+```ts
+registerShutdownHook(
+    () => {
+        storage.destroy();
+    },
+    {
+        name: "storage",
+    }
+);
+```
+
+Hooks run in reverse registration order and can be unregistered with the cleanup function returned by `registerShutdownHook()`.
+
+## Trusted proxy behavior
+
+Trusted proxy mode is disabled by default.
+
+When disabled, BCP strips spoofable incoming forwarding headers at the public hardening gateway and writes forwarding information from the actual connection.
+
+When the application is intentionally deployed behind a trusted reverse proxy/load balancer, enable:
+
+```dotenv
+BCP_TRUST_PROXY=true
+```
+
+Only enable it when direct untrusted traffic cannot bypass the trusted proxy.
+
+## Local Server storage fix
+
+Before `0.1.28`, selecting Local Server generated `lib/storage.ts` and configured `./storage`, but the runtime directory had no explanatory scaffold before the first upload.
+
+`0.1.28` generates:
+
+```text
+storage/
+├─ .gitkeep
+└─ README.md
+```
+
+and uses Git ignore rules:
+
+```gitignore
+storage/*
+!storage/.gitkeep
+!storage/README.md
+```
+
+Runtime uploads and `.bcp-storage-meta` remain untracked while the directory structure is visible in a fresh project.
+
+## Testing
+
+`0.1.28` adds coverage for:
+
+- production timeout parsing,
+- invalid timeout relationships,
+- applying Node HTTP server timeout settings,
+- graceful HTTP server close,
+- shutdown hook ordering/unregistration,
+- generated Local Server storage directory scaffold,
+- generated Local Server Git ignore behavior.
+
+## Remaining release work
+
+Before publication:
+
+1. sync `package-lock.json` to `0.1.28`,
+2. run `npm run typecheck`,
+3. run unit/integration/E2E/package tests,
+4. run `npm run rc:check`,
+5. build a representative BCP application,
+6. run the standalone artifact in Docker,
+7. verify `docker stop` produces graceful shutdown logs,
+8. create the `v0.1.28` tag only after the final release commit is known,
+9. publish and verify npm visibility.
+
+## Next milestone
+
+The planned next milestone is `0.1.29 — Developer Experience`, focused on generators, richer `doctor` / `inspect`, improved diagnostics and create-app workflow improvements.

package/docs/releases/0.1.29.md

@@ -0,0 +1,170 @@
+# BCP Framework 0.1.29
+
+> **Milestone:** Developer Experience
+>
+> **Release state:** unreleased development target. Do not mark this version as published until local validation, RC checks, tagging and npm publication complete.
+
+BCP Framework `0.1.29` focuses on reducing repetitive project setup and making project diagnostics easier to consume locally, in CI and in `bcp-docs-web`.
+
+## Highlights
+
+### Project generators
+
+New CLI command:
+
+```bash
+bcp generate <kind>
+```
+
+Supported generators:
+
+```bash
+bcp generate page dashboard/users
+bcp generate api users
+bcp generate middleware
+bcp generate migration create_users
+```
+
+Page, API and middleware generators refuse to replace existing files unless `--force` is explicitly supplied.
+
+Migration generation reuses the existing database migration implementation so timestamp/file naming has a single source of truth.
+
+### Doctor / Inspect v2
+
+`bcp doctor` now adds project/runtime checks for:
+
+- supported dependency lockfiles,
+- duplicate `bcp` / `@chidchanun/bcp` dependency declarations,
+- production hardening environment validity,
+- standalone production build presence,
+- Docker + lockfile reproducibility guidance,
+- configured storage provider detection.
+
+`bcp inspect` keeps its previous report fields and adds a `project` section with:
+
+```text
+package manager
+lockfile
+bcp.project.json metadata
+selected create-bcp-app presets
+production build presence
+Dockerfile presence
+framework dependency declarations
+storage provider
+production hardening state
+```
+
+The new fields are additive so existing consumers of the previous JSON fields can continue reading them.
+
+### `bcp.project.json`
+
+New projects created by `create-bcp-app` receive a non-secret metadata manifest:
+
+```json
+{
+  "schemaVersion": 1,
+  "framework": "bcp",
+  "projectName": "my-app",
+  "createdWith": {
+    "package": "create-bcp-app",
+    "version": "0.1.29"
+  },
+  "packageManager": "npm",
+  "presets": {
+    "tailwind": true,
+    "database": "mysql",
+    "auth": "jwt-cookie",
+    "storage": "local"
+  }
+}
+```
+
+The manifest records scaffold identity only. Credentials, passwords, access keys, session secrets and tokens must remain outside this file.
+
+Older projects without `bcp.project.json` continue to work. Doctor/inspect fall back to project files where practical.
+
+### Docs-web manifest
+
+`docs/docs-web-manifest.json` is now the explicit navigation contract for `bcp-docs-web`.
+
+It maps:
+
+```text
+section
+website route
+Markdown source
+title
+release routes
+version target
+release state
+```
+
+The Markdown files under `docs/` remain the authored documentation source of truth. The JSON manifest is navigation/routing metadata, not a competing content source.
+
+New authored guides include:
+
+- `docs/generators.md`
+- `docs/project-metadata.md`
+
+## Compatibility
+
+`0.1.29` is intended to be additive.
+
+- Existing page/API routing remains unchanged.
+- Existing database migration commands remain supported.
+- `bcp doctor` retains its existing report structure and adds checks.
+- `bcp inspect` retains its existing fields and adds `project`.
+- Existing projects do not require `bcp.project.json`.
+- `--force` is opt-in and never silently overwrites existing generated files.
+
+## Out of scope
+
+The following are not guarantees of `0.1.29`:
+
+- generated symbol/API reference documentation,
+- interactive documentation playgrounds,
+- source-code merge behavior for generators,
+- automatic conversion of old projects into `bcp.project.json`,
+- the `0.2.0` API/platform stability baseline.
+
+## Documentation sources
+
+Primary documentation for this milestone:
+
+```text
+docs/generators.md
+docs/developer-tools.md
+docs/project-metadata.md
+docs/docs-web-manifest.json
+docs/README.md
+```
+
+## Validation
+
+Before tagging or publishing `0.1.29`, run:
+
+```powershell
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:package
+npm run test:e2e
+npm run rc:check
+```
+
+The release lockfile must also be synchronized to `0.1.29` before the final tag.
+
+Recommended generator smoke checks:
+
+```powershell
+npm exec -- bcp-framework generate page dx-test --root examples/basic-app
+npm exec -- bcp-framework routes --root examples/basic-app
+```
+
+Use a disposable project for destructive `--force` testing.
+
+## Next direction
+
+After `0.1.29`, the planned major milestone is **`0.2.0 — Framework Platform`**.
+
+The `0.2.0` work should focus on consolidating the existing `0.1.x` surface into a documented platform baseline: API consistency, production stabilization, documentation completeness, migration guidance and compatibility expectations rather than adding unrelated large feature areas.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",