@chidchanun/bcp 0.2.0 → 0.2.2

package/docs/api-reference.md

@@ -0,0 +1,224 @@
+# API Reference
+
+BCP Framework exposes a small set of supported package entrypoints. Import application APIs through these entrypoints instead of private files under `packages/`.
+
+The machine-readable source for this page is `docs/api-manifest.json`.
+
+## `bcp`
+
+Universal React application APIs.
+
+Common exports include:
+
+```ts
+import {
+    Form,
+    Link,
+    createIsland,
+    navigate,
+    notFound,
+    useActionData,
+    useActionError,
+    useFormStatus,
+    useGuardData,
+    useLoaderData,
+    useNavigation,
+    useRouter,
+} from "bcp";
+```
+
+Use this entrypoint for page/client-facing framework APIs, routing, forms, loader/guard data, islands and metadata types.
+
+Related guides: [Routing](routing.md), [Server Data Loaders](server-data-loaders.md), [Route Guards](route-guards.md), [Form Actions](form-actions.md).
+
+## `bcp/island`
+
+Partial-hydration island APIs.
+
+```ts
+import {
+    createIsland,
+} from "bcp/island";
+```
+
+Related guide: [Hydration](hydration.md).
+
+## `bcp/cache`
+
+Caching and revalidation APIs.
+
+```ts
+import {
+    cache,
+    clearCache,
+    dedupe,
+    getCacheStats,
+    revalidatePath,
+    revalidateTag,
+} from "bcp/cache";
+```
+
+Related guide: [Caching](caching.md).
+
+## `bcp/config`
+
+Typed framework configuration, application environment-schema validation and diagnostics APIs.
+
+```ts
+import {
+    applyEnvironmentDefaults,
+    defineConfig,
+    defineEnvironment,
+    diagnoseBcpConfiguration,
+    getEnvironmentSchemaFileNames,
+    loadBcpEnvironmentSchema,
+    readResolvedBcpConfig,
+    resolveBcpConfig,
+    validateEnvironment,
+} from "bcp/config";
+```
+
+Use `defineConfig()` for framework runtime/build settings and `defineEnvironment()` for the optional `bcp.environment.*` application-variable schema.
+
+`validateEnvironment()` returns parsed declared values and structured issues. `applyEnvironmentDefaults()` fills only missing environment keys and does not overwrite values already supplied by the environment/runtime.
+
+Related guides: [Configuration](configuration.md), [Environment Validation](environment-validation.md).
+
+## `bcp/validation`
+
+Typed validation primitives and `ValidationError`.
+
+```ts
+import {
+    array,
+    boolean,
+    literal,
+    nullable,
+    number,
+    object,
+    optional,
+    parse,
+    safeParse,
+    string,
+    union,
+} from "bcp/validation";
+```
+
+Related guide: [Validation](validation.md).
+
+## `bcp/error`
+
+Structured HTTP error helpers.
+
+```ts
+import {
+    HttpError,
+    badRequest,
+    conflict,
+    forbidden,
+    internalServerError,
+    isHttpError,
+    serviceUnavailable,
+    throwHttpError,
+    tooManyRequests,
+    unauthorized,
+    unprocessableEntity,
+} from "bcp/error";
+```
+
+Related guide: [Error Handling](error-handling.md).
+
+## `bcp/database`
+
+Server-only database primitives.
+
+```ts
+import {
+    createDatabase,
+    db,
+} from "bcp/database";
+```
+
+Use the public database helpers instead of importing framework-internal pool/runtime modules.
+
+Related guides: [Database](database.md), [Database Migrations](database-migrations.md).
+
+## `bcp/auth`
+
+Authentication and authorization APIs.
+
+```ts
+import {
+    auth,
+    createAuth,
+    createAuthGuard,
+    createRoleGuard,
+    getGuardAuth,
+    getSession,
+    login,
+    logout,
+    requireAuth,
+    requireRole,
+    rotateSession,
+} from "bcp/auth";
+```
+
+Related guides: [Authentication](authentication.md), [Auth Route Guards](auth-route-guards.md), [JWT Sessions](session-auth.md).
+
+## `bcp/server`
+
+Server request/runtime APIs.
+
+This entrypoint includes request context, cookies, logging, graceful shutdown hooks, multipart upload helpers, storage adapters, file delivery, response helpers and low-level session primitives.
+
+```ts
+import {
+    clientIp,
+    cookies,
+    createLocalStorage,
+    createLogger,
+    createS3Storage,
+    createStorageResponse,
+    getProductionHardeningConfig,
+    headers,
+    json,
+    redirect,
+    registerShutdownHook,
+    requestId,
+    requestMethod,
+    requestUrl,
+    storeMultipartFile,
+} from "bcp/server";
+```
+
+Related guides: [Server Request APIs](server-request-apis.md), [File Upload](file-upload.md), [Storage](storage.md), [Storage Ecosystem](storage-ecosystem.md), [Production Hardening](production-hardening.md).
+
+## `bcp/server-only`
+
+Server-only module boundary marker.
+
+```ts
+import "bcp/server-only";
+```
+
+Place this import in application modules that must never enter a browser bundle.
+
+Related guide: [Application Modules](application-modules.md).
+
+## `bcp/middleware`
+
+Middleware System v2 APIs and types.
+
+```ts
+import type {
+    MiddlewarePipelineHandler,
+} from "bcp/middleware";
+```
+
+Related guide: [Middleware](middleware.md).
+
+## Stability
+
+Only package entrypoints listed in both `docs/platform-manifest.json` and `docs/api-manifest.json` are part of the documented platform surface.
+
+Files under internal `packages/*` paths are framework implementation details unless re-exported through a documented public package entrypoint.

package/docs/configuration.md

@@ -92,6 +92,101 @@ BCP_EXPERIMENTAL_ISLANDS
 
 Application environment variables prefixed with `BCP_PUBLIC_` may be embedded into browser bundles. Other application variables remain server-side.
 
+## Configuration & Environment v2
+
+BCP `0.2.2` adds an optional application environment schema in one of:
+
+```text
+bcp.environment.ts
+bcp.environment.mts
+bcp.environment.js
+bcp.environment.mjs
+```
+
+The schema validates application-specific values after `.env` files are loaded.
+
+Example:
+
+```ts
+import {
+    defineEnvironment,
+} from "bcp/config";
+
+export default defineEnvironment({
+    DATABASE_URL: {
+        type: "string",
+        required: true,
+    },
+    SESSION_SECRET: {
+        type: "string",
+        required: true,
+        secret: true,
+        minLength: 32,
+    },
+    BCP_PUBLIC_API_URL: {
+        type: "url",
+        required: true,
+    },
+});
+```
+
+This schema is additive. Projects without `bcp.environment.*` continue to use the existing environment behavior.
+
+Read more: [Environment Validation](environment-validation.md)
+
+## Configuration check
+
+Validate the current project without starting the application:
+
+```bash
+bcp config check
+```
+
+JSON diagnostics:
+
+```bash
+bcp config check --json
+```
+
+Windows project-local form:
+
+```powershell
+npm exec -- bcp-framework config check
+```
+
+The check reports the selected config file, environment files, environment schema, resolved server/build settings and diagnostics. Raw environment values are not printed.
+
+For production-mode warnings in PowerShell:
+
+```powershell
+$env:NODE_ENV = "production"
+npm exec -- bcp-framework config check
+Remove-Item Env:NODE_ENV
+```
+
+## Startup diagnostics
+
+`bcp dev` and `bcp build` run the environment-schema diagnostics before the application starts/builds.
+
+Schema errors stop startup/build early. Production safety warnings do not fail the build by themselves.
+
+Examples of production warnings include:
+
+- source maps enabled,
+- powered-by header enabled,
+- Content-Security-Policy disabled,
+- trusted proxy mode enabled.
+
+Trusted proxy mode should only be enabled when untrusted clients cannot bypass the trusted proxy/load balancer.
+
 ## Config reload in development
 
-Changes to supported `.env*` files or `bcp.config.*` restart the development worker so the new resolved configuration is applied without restarting the parent CLI manually.
+Changes to these configuration sources restart the development worker automatically:
+
+```text
+.env*
+bcp.config.*
+bcp.environment.*
+```
+
+The parent development supervisor stays running while the worker reloads the new configuration/environment state.

package/docs/docs-web-manifest.json

@@ -1,15 +1,17 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.2.0",
+  "versionTarget": "0.2.2",
   "releaseState": "unreleased",
   "sections": [
     {
       "id": "getting-started",
       "title": "Getting Started",
+      "description": "Create, configure, deploy and update BCP applications.",
       "pages": [
         { "route": "/docs/getting-started", "source": "getting-started.md", "title": "Getting Started" },
         { "route": "/docs/configuration", "source": "configuration.md", "title": "Configuration" },
+        { "route": "/docs/environment-validation", "source": "environment-validation.md", "title": "Environment Validation" },
         { "route": "/docs/application-modules", "source": "application-modules.md", "title": "Application Modules" },
         { "route": "/docs/project-metadata", "source": "project-metadata.md", "title": "Project Metadata" },
         { "route": "/docs/deployment", "source": "deployment.md", "title": "Deployment" },
@@ -19,6 +21,7 @@
     {
       "id": "routing-data",
       "title": "Routing & Data",
+      "description": "Routing, server data, mutations, validation and structured errors.",
       "pages": [
         { "route": "/docs/routing", "source": "routing.md", "title": "Routing" },
         { "route": "/docs/server-data-loaders", "source": "server-data-loaders.md", "title": "Server Data Loaders" },
@@ -32,6 +35,7 @@
     {
       "id": "authentication",
       "title": "Authentication",
+      "description": "Authentication core, auth-aware route guards and JWT cookie sessions.",
       "pages": [
         { "route": "/docs/authentication", "source": "authentication.md", "title": "Authentication" },
         { "route": "/docs/auth-route-guards", "source": "auth-route-guards.md", "title": "Auth Route Guards" },
@@ -41,6 +45,7 @@
     {
       "id": "database",
       "title": "Database",
+      "description": "Database primitives, transactions and migration workflows.",
       "pages": [
         { "route": "/docs/database", "source": "database.md", "title": "Database" },
         { "route": "/docs/database-migrations", "source": "database-migrations.md", "title": "Database Migrations" }
@@ -49,6 +54,7 @@
     {
       "id": "runtime",
       "title": "Runtime & Infrastructure",
+      "description": "Middleware, hydration, logging, caching, security and production hardening.",
       "pages": [
         { "route": "/docs/middleware", "source": "middleware.md", "title": "Middleware" },
         { "route": "/docs/hydration", "source": "hydration.md", "title": "Hydration" },
@@ -61,6 +67,7 @@
     {
       "id": "storage",
       "title": "Storage & Uploads",
+      "description": "Multipart uploads, storage adapters, file delivery and object-storage features.",
       "pages": [
         { "route": "/docs/file-upload", "source": "file-upload.md", "title": "File Upload" },
         { "route": "/docs/storage", "source": "storage.md", "title": "Storage & File Delivery" },
@@ -71,6 +78,7 @@
     {
       "id": "developer-experience",
       "title": "Developer Experience",
+      "description": "Project generators, diagnostics, project metadata and framework maintenance tooling.",
       "pages": [
         { "route": "/docs/generators", "source": "generators.md", "title": "Project Generators" },
         { "route": "/docs/developer-tools", "source": "developer-tools.md", "title": "Doctor & Inspect" }
@@ -79,14 +87,26 @@
     {
       "id": "platform-compatibility",
       "title": "Platform & Compatibility",
+      "description": "Supported platform contracts, documentation integration and migration guidance.",
       "pages": [
         { "route": "/docs/platform-contract", "source": "platform-contract.md", "title": "Framework Platform Contract" },
-        { "route": "/docs/migration-0.2", "source": "migration-0.2.md", "title": "Migrating to 0.2.0" }
+        { "route": "/docs/documentation-platform", "source": "documentation-platform.md", "title": "Documentation Platform" },
+        { "route": "/docs/migration-0.2", "source": "migration-0.2.md", "title": "Migrating to 0.2.x" }
+      ]
+    },
+    {
+      "id": "api-reference",
+      "title": "API Reference",
+      "description": "Supported BCP package entrypoints and their guide ownership.",
+      "pages": [
+        { "route": "/docs/api-reference", "source": "api-reference.md", "title": "API Reference" }
       ]
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.0", "source": "releases/0.2.0.md", "version": "0.2.0", "state": "unreleased" },
+    { "route": "/releases/0.2.2", "source": "releases/0.2.2.md", "version": "0.2.2", "state": "unreleased" },
+    { "route": "/releases/0.2.1", "source": "releases/0.2.1.md", "version": "0.2.1" },
+    { "route": "/releases/0.2.0", "source": "releases/0.2.0.md", "version": "0.2.0" },
     { "route": "/releases/0.1.29", "source": "releases/0.1.29.md", "version": "0.1.29" },
     { "route": "/releases/0.1.28", "source": "releases/0.1.28.md", "version": "0.1.28" },
     { "route": "/releases/0.1.27", "source": "releases/0.1.27.md", "version": "0.1.27" },

package/docs/documentation-platform.md

@@ -0,0 +1,136 @@
+# Documentation Platform
+
+BCP Framework `0.2.1` defines a machine-readable documentation platform so the framework repository remains the source of truth while `bcp-docs-web` acts as the presentation, search and navigation layer.
+
+## Source contracts
+
+The documentation platform uses three manifests:
+
+```text
+docs/docs-web-manifest.json
+    Navigation, routes, page titles and release routes.
+
+docs/platform-manifest.json
+    Framework runtime, public entrypoints, capabilities and compatibility baseline.
+
+docs/api-manifest.json
+    Public package entrypoints, source ownership, environment boundary and guide mapping.
+```
+
+Markdown files under `docs/` remain the authored documentation content.
+
+## Docs-web synchronization
+
+`bcp-docs-web` should read the manifests first and then load the Markdown sources they reference.
+
+Recommended flow:
+
+```text
+Framework repository / selected ref
+        ↓
+docs-web-manifest.json
+platform-manifest.json
+api-manifest.json
+        ↓
+validate matching framework/version
+        ↓
+load Markdown sources
+        ↓
+synchronize CMS/search/navigation
+        ↓
+render docs website
+```
+
+The website must not maintain a competing hard-coded list of framework pages when a page exists in `docs-web-manifest.json`.
+
+## Version and release state
+
+The current documentation target and release state come from the framework manifests.
+
+For an unreleased development target:
+
+```json
+{
+  "version": "0.2.1",
+  "releaseState": "unreleased"
+}
+```
+
+A release note existing in the repository does not mean that version has been published to npm. Release state should only move to a published value after the release workflow succeeds.
+
+## API reference contract
+
+`docs/api-manifest.json` describes supported public package entrypoints.
+
+Each entry records:
+
+```text
+package name
+source file
+environment boundary
+API-reference route
+summary
+related guide routes
+```
+
+The manifest intentionally documents public package boundaries instead of private framework implementation modules.
+
+Public entrypoints are also checked against `docs/platform-manifest.json` and the prepared npm package during release validation.
+
+## Historical versions
+
+The synchronization workflow accepts a Git ref. This allows documentation to be synchronized from a release tag instead of only from `main`.
+
+Example:
+
+```powershell
+npm run docs:sync -- --ref=v0.2.0
+```
+
+A docs website may use this foundation for version snapshots without copying current documentation into a second manually maintained source tree.
+
+## Search
+
+Search should index the synchronized Markdown documents, not the manifest JSON itself. Manifest titles, categories and API entrypoint summaries may be added to the search index as metadata.
+
+## Previous / next navigation
+
+Previous and next document ordering should follow the order in `docs-web-manifest.json`.
+
+This keeps sidebar order and previous/next navigation consistent.
+
+## Security boundary
+
+Documentation synchronization must only read files explicitly referenced by validated manifests.
+
+Source paths must:
+
+- be relative to `docs/`,
+- reject `..` traversal,
+- reject absolute paths,
+- use expected Markdown or JSON source types,
+- never ingest `.env`, credentials or application project secrets.
+
+`bcp.project.json` is intentionally non-secret, but a documentation site should still avoid reading arbitrary application project files.
+
+## Release validation
+
+Before a Documentation Platform release:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:e2e
+npm run test:package
+npm run rc:check
+```
+
+Validation should ensure:
+
+- all docs-web page sources exist,
+- all docs routes are unique,
+- API entrypoints are unique,
+- API entrypoints match the platform public-entrypoint baseline,
+- manifest versions match the framework version,
+- prepared npm artifacts contain the documentation contracts.