@chidchanun/bcp 0.1.28 → 0.2.0

package/docs/migration-0.2.md

@@ -0,0 +1,173 @@
+# Migrating to BCP Framework 0.2.0
+
+BCP Framework `0.2.0` establishes the Framework Platform baseline while preserving the public application model from `0.1.29`.
+
+> **Release state:** unreleased development target until RC validation and npm publication complete.
+
+## Compatibility goal
+
+There are no intentional public-entrypoint removals from the `0.1.29` baseline in this milestone.
+
+Applications already running on `0.1.29` should normally be able to move to `0.2.0` without rewriting routing, loaders, guards, actions, middleware, storage or authentication code.
+
+BCP remains pre-1.0, so every application should still validate the upgrade before production deployment.
+
+## 1. Check the current project
+
+From the application root:
+
+```powershell
+npm exec -- bcp-framework doctor
+npm exec -- bcp-framework inspect --json
+```
+
+Resolve blocking `FAIL` results before upgrading, especially duplicate framework dependency declarations or invalid production-hardening settings.
+
+## 2. Check the available framework update
+
+```powershell
+npm exec -- bcp-framework update --check
+```
+
+After `0.2.0` is published, update with:
+
+```powershell
+npm exec -- bcp-framework update 0.2.0
+```
+
+Generated projects can also use:
+
+```powershell
+npm run update -- 0.2.0
+```
+
+## 3. Keep one framework dependency
+
+The recommended project dependency remains:
+
+```json
+{
+  "dependencies": {
+    "bcp": "npm:@chidchanun/bcp@0.2.0"
+  }
+}
+```
+
+Do not keep both `bcp` and a second direct `@chidchanun/bcp` dependency in the same application. Two installed framework copies can produce separate React/framework contexts.
+
+## 4. Preserve server-only boundaries
+
+Continue importing public APIs through supported entrypoints such as:
+
+```ts
+import {
+    Form,
+} from "bcp";
+
+import {
+    auth,
+} from "bcp/auth";
+
+import {
+    db,
+} from "bcp/database";
+
+import {
+    cookies,
+} from "bcp/server";
+```
+
+Do not migrate application imports to framework-internal `packages/...` paths.
+
+The current public entrypoint baseline is listed in `platform-manifest.json` and [Framework Platform Contract](platform-contract.md).
+
+## 5. Validate generated-project metadata
+
+Projects created by `create-bcp-app` `0.1.29` or newer may contain:
+
+```text
+bcp.project.json
+```
+
+This file is optional runtime metadata. Older applications do not need to create it manually to run on `0.2.0`.
+
+If you choose to add it to an older application, keep it non-secret. Credentials, passwords, access keys, session secrets and tokens do not belong in this file.
+
+## 6. Validate production settings
+
+For standalone production, review:
+
+```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
+```
+
+Only enable:
+
+```dotenv
+BCP_TRUST_PROXY=true
+```
+
+when the BCP process is reachable only through a trusted reverse proxy/load balancer.
+
+## 7. Rebuild the standalone artifact
+
+Do not reuse `.bcp-framework/build` from the previous framework version.
+
+Run:
+
+```powershell
+npm run build
+```
+
+Then test:
+
+```powershell
+npm start
+```
+
+The supported `0.2.0` production target remains the standalone Node.js artifact under `.bcp-framework/build/`.
+
+## 8. Application validation checklist
+
+Recommended minimum after upgrading:
+
+```powershell
+npm run typecheck
+npm run build
+npm exec -- bcp-framework routes
+npm exec -- bcp-framework doctor
+```
+
+For applications using authentication, storage or database features, also exercise representative login/session, upload/download and database paths before production deployment.
+
+## Local storage projects
+
+Projects using the Local Server storage preset should keep the scaffold:
+
+```text
+storage/
+├─ .gitkeep
+└─ README.md
+```
+
+Runtime storage objects remain ignored by Git.
+
+## Amazon S3 / Cloudflare R2 projects
+
+No provider migration is required for the `0.2.0` platform baseline. Existing `createS3Storage()` configurations continue using server-only credentials/environment settings.
+
+## What is not part of this migration
+
+`0.2.0` does not introduce native executable compilation, desktop packaging, Android APK output or iOS application output.
+
+The supported build model remains:
+
+```text
+BCP application -> bcp build -> standalone Node.js web application
+```
+
+Future build targets can be added after the platform baseline without redefining the existing standalone contract.

package/docs/platform-contract.md

@@ -0,0 +1,159 @@
+# Framework Platform Contract
+
+BCP Framework `0.2.0` establishes the first explicit framework-platform baseline. The goal is to make public entrypoints, supported runtime targets, CLI capabilities and documentation metadata visible and testable instead of relying on implicit package structure.
+
+> **Release state:** unreleased development target until local RC validation, tagging and npm publication complete.
+
+## What the platform contract covers
+
+The platform contract is represented by `docs/platform-manifest.json` and release/package smoke tests.
+
+It records:
+
+- the framework version and release state,
+- the minimum supported Node.js runtime,
+- the supported production build target,
+- public package entrypoints,
+- documented CLI command families,
+- framework capability groups,
+- built-in/scaffolded storage-provider families,
+- compatibility expectations for the previous baseline,
+- documentation files used by `bcp-docs-web`.
+
+The manifest is metadata. Framework source, package exports and tests remain authoritative for actual runtime behavior.
+
+## Public entrypoints
+
+The `0.2.0` platform baseline recognizes these public application imports:
+
+```text
+bcp
+bcp/island
+bcp/cache
+bcp/config
+bcp/validation
+bcp/error
+bcp/database
+bcp/auth
+bcp/server
+bcp/server-only
+bcp/middleware
+```
+
+Application code should prefer these entrypoints instead of importing internal files under `packages/`.
+
+The release package contract smoke test verifies that the prepared npm artifact still exposes these entrypoints. Accidentally removing one from the publish manifest should fail package validation before release.
+
+## CLI baseline
+
+The framework-platform CLI baseline includes:
+
+```text
+bcp dev
+bcp build
+bcp start
+bcp routes
+bcp update
+bcp db ...
+bcp generate ...
+bcp doctor
+bcp inspect
+bcp help
+bcp version
+```
+
+The Windows-safe `bcp-framework` executable remains an alias for the same CLI.
+
+## Runtime baseline
+
+BCP `0.2.0` continues to target a standalone Node.js web application:
+
+```text
+BCP source application
+        ↓
+     bcp build
+        ↓
+.bcp-framework/build/
+├─ client/
+├─ public/
+└─ server/
+   └─ server.mjs
+```
+
+Minimum runtime:
+
+```text
+Node.js >= 24.11.0
+React 19
+```
+
+The platform baseline does not yet promise native `.exe`, mobile or desktop application compilation. Those remain future build-target work rather than part of `0.2.0`.
+
+## Compatibility policy for 0.2.0
+
+`0.2.0` is intended to preserve applications that already work on `0.1.29`. This milestone does not intentionally remove public entrypoints or change the current standalone runtime model.
+
+Because BCP remains pre-1.0, applications should still validate upgrades through:
+
+```bash
+bcp update --check
+bcp doctor
+npm run typecheck
+npm run build
+```
+
+See [Migrating to 0.2.0](migration-0.2.md).
+
+## Package consistency validation
+
+The `0.2.0` release process adds a platform-contract package smoke check. It verifies the staged npm artifact rather than only source files.
+
+The check covers:
+
+1. framework version consistency,
+2. required public package exports,
+3. both BCP CLI executable aliases,
+4. minimum Node.js engine declaration,
+5. inclusion of platform/docs metadata in the packed framework,
+6. docs-web target/version consistency,
+7. create-bcp-app version parity with the framework release.
+
+This is additive to existing unit, integration, E2E, storage, production-hardening and Developer Experience package smoke checks.
+
+## Docs-web contract
+
+`bcp-docs-web` should use two machine-readable files for different purposes:
+
+```text
+docs/docs-web-manifest.json
+  -> website sections, routes, source Markdown and release navigation
+
+docs/platform-manifest.json
+  -> framework version, public entrypoints, runtime target and capability metadata
+```
+
+Do not duplicate the platform entrypoint list in application code when it can be sourced from `platform-manifest.json`.
+
+## Stability labels
+
+Documentation should distinguish:
+
+- **platform baseline** — public surface covered by the `0.2.0` contract,
+- **supported** — behavior covered by current tests/docs,
+- **experimental/roadmap** — not guaranteed by the current platform manifest,
+- **internal** — not a public application import contract.
+
+## Release validation
+
+Before `0.2.0` is tagged or published:
+
+```bash
+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 is not considered published until both `@chidchanun/bcp@0.2.0` and `create-bcp-app@0.2.0` are visible from npm.

package/docs/platform-manifest.json

@@ -0,0 +1,75 @@
+{
+  "schemaVersion": 1,
+  "framework": "bcp",
+  "version": "0.2.0",
+  "releaseState": "unreleased",
+  "baseline": "framework-platform",
+  "runtime": {
+    "node": ">=24.11.0",
+    "react": "19",
+    "buildTarget": "standalone-node"
+  },
+  "publicEntrypoints": [
+    "bcp",
+    "bcp/island",
+    "bcp/cache",
+    "bcp/config",
+    "bcp/validation",
+    "bcp/error",
+    "bcp/database",
+    "bcp/auth",
+    "bcp/server",
+    "bcp/server-only",
+    "bcp/middleware"
+  ],
+  "cliCommands": [
+    "dev",
+    "build",
+    "start",
+    "routes",
+    "update",
+    "db",
+    "generate",
+    "doctor",
+    "inspect",
+    "help",
+    "version"
+  ],
+  "capabilities": {
+    "routing": true,
+    "ssr": true,
+    "spaNavigation": true,
+    "loaders": true,
+    "routeGuards": true,
+    "formActions": true,
+    "middlewareV2": true,
+    "jwtCookieSessions": true,
+    "databaseMigrations": true,
+    "validation": true,
+    "structuredErrors": true,
+    "logging": true,
+    "responseCaching": true,
+    "streamingUploads": true,
+    "storageEcosystem": true,
+    "productionHardening": true,
+    "projectGenerators": true,
+    "projectDiagnostics": true
+  },
+  "storageProviders": [
+    "local",
+    "amazon-s3",
+    "cloudflare-r2",
+    "s3-compatible"
+  ],
+  "compatibility": {
+    "previousBaseline": "0.1.29",
+    "intentionalBreakingChangesFromPreviousBaseline": false,
+    "migrationGuide": "migration-0.2.md"
+  },
+  "documentation": {
+    "navigationManifest": "docs-web-manifest.json",
+    "platformContract": "platform-contract.md",
+    "migrationGuide": "migration-0.2.md",
+    "releaseNotes": "releases/0.2.0.md"
+  }
+}

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.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.