@chidchanun/bcp 0.1.29 → 0.2.1

package/docs/api-manifest.json

@@ -0,0 +1,129 @@
+{
+  "schemaVersion": 1,
+  "framework": "bcp",
+  "version": "0.2.1",
+  "releaseState": "unreleased",
+  "coverage": "public-entrypoints",
+  "entrypoints": [
+    {
+      "package": "bcp",
+      "source": "packages/client/src/index.tsx",
+      "environment": "universal",
+      "route": "/docs/api-reference#bcp",
+      "summary": "React application APIs for routing, links, forms, loader/guard data, islands, metadata and route error handling.",
+      "guides": [
+        "/docs/routing",
+        "/docs/server-data-loaders",
+        "/docs/route-guards",
+        "/docs/form-actions"
+      ]
+    },
+    {
+      "package": "bcp/island",
+      "source": "packages/client/src/islands.tsx",
+      "environment": "universal",
+      "route": "/docs/api-reference#bcp-island",
+      "summary": "Partial-hydration island creation and island loading strategy types.",
+      "guides": [
+        "/docs/hydration"
+      ]
+    },
+    {
+      "package": "bcp/cache",
+      "source": "packages/client/src/cache.ts",
+      "environment": "server-preferred",
+      "route": "/docs/api-reference#bcp-cache",
+      "summary": "Cache, deduplication, statistics and path/tag revalidation primitives.",
+      "guides": [
+        "/docs/caching"
+      ]
+    },
+    {
+      "package": "bcp/config",
+      "source": "packages/client/src/config.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-config",
+      "summary": "Typed BCP configuration definition, loading and resolution APIs.",
+      "guides": [
+        "/docs/configuration"
+      ]
+    },
+    {
+      "package": "bcp/validation",
+      "source": "packages/client/src/validation.ts",
+      "environment": "universal",
+      "route": "/docs/api-reference#bcp-validation",
+      "summary": "Typed validators, parse helpers and structured validation errors.",
+      "guides": [
+        "/docs/validation"
+      ]
+    },
+    {
+      "package": "bcp/error",
+      "source": "packages/client/src/http-error.ts",
+      "environment": "universal",
+      "route": "/docs/api-reference#bcp-error",
+      "summary": "Structured HTTP error creation, classification and response helpers.",
+      "guides": [
+        "/docs/error-handling"
+      ]
+    },
+    {
+      "package": "bcp/database",
+      "source": "packages/client/src/database.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-database",
+      "summary": "Database pool, prepared query/execute helpers and transaction primitives.",
+      "guides": [
+        "/docs/database",
+        "/docs/database-migrations"
+      ]
+    },
+    {
+      "package": "bcp/auth",
+      "source": "packages/client/src/auth.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-auth",
+      "summary": "Authentication, login/logout/session rotation and route authorization guards.",
+      "guides": [
+        "/docs/authentication",
+        "/docs/auth-route-guards",
+        "/docs/session-auth"
+      ]
+    },
+    {
+      "package": "bcp/server",
+      "source": "packages/client/src/server.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-server",
+      "summary": "Request context, cookies, logging, production hardening, upload, storage, response and session APIs.",
+      "guides": [
+        "/docs/server-request-apis",
+        "/docs/file-upload",
+        "/docs/storage",
+        "/docs/storage-ecosystem",
+        "/docs/production-hardening"
+      ]
+    },
+    {
+      "package": "bcp/server-only",
+      "source": "packages/client/src/server-only.mjs",
+      "environment": "server-marker",
+      "route": "/docs/api-reference#bcp-server-only",
+      "summary": "Server-only module boundary marker that prevents accidental browser inclusion.",
+      "guides": [
+        "/docs/application-modules"
+      ]
+    },
+    {
+      "package": "bcp/middleware",
+      "source": "packages/server/src/middleware.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-middleware",
+      "summary": "Middleware System v2 request/response pipeline types and helpers.",
+      "guides": [
+        "/docs/middleware"
+      ]
+    }
+  ]
+}

package/docs/api-reference.md

@@ -0,0 +1,214 @@
+# 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 configuration APIs.
+
+```ts
+import {
+    defineConfig,
+    readResolvedBcpConfig,
+    resolveBcpConfig,
+} from "bcp/config";
+```
+
+Related guide: [Configuration](configuration.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/docs-web-manifest.json

@@ -1,12 +1,13 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.1.29",
+  "versionTarget": "0.2.1",
   "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" },
@@ -19,6 +20,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 +34,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 +44,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 +53,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 +66,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,14 +77,35 @@
     {
       "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" }
       ]
+    },
+    {
+      "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/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.1.29", "source": "releases/0.1.29.md", "version": "0.1.29", "state": "unreleased" },
+    { "route": "/releases/0.2.1", "source": "releases/0.2.1.md", "version": "0.2.1", "state": "unreleased" },
+    { "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" },
     { "route": "/releases/0.1.26", "source": "releases/0.1.26.md", "version": "0.1.26" },

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.