@chidchanun/bcp 0.2.0 → 0.2.1

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.2.0",
+  "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,6 +77,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 +86,25 @@
     {
       "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.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" },

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.

package/docs/platform-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "releaseState": "unreleased",
   "baseline": "framework-platform",
   "runtime": {
@@ -53,7 +53,9 @@
     "storageEcosystem": true,
     "productionHardening": true,
     "projectGenerators": true,
-    "projectDiagnostics": true
+    "projectDiagnostics": true,
+    "documentationPlatform": true,
+    "apiManifest": true
   },
   "storageProviders": [
     "local",
@@ -62,14 +64,18 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.1.29",
+    "previousBaseline": "0.2.0",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
   "documentation": {
     "navigationManifest": "docs-web-manifest.json",
+    "platformManifest": "platform-manifest.json",
+    "apiManifest": "api-manifest.json",
     "platformContract": "platform-contract.md",
+    "documentationPlatform": "documentation-platform.md",
+    "apiReference": "api-reference.md",
     "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.0.md"
+    "releaseNotes": "releases/0.2.1.md"
   }
 }

package/docs/releases/0.2.1.md

@@ -0,0 +1,132 @@
+# BCP Framework 0.2.1
+
+> **Milestone:** Documentation Platform
+>
+> **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.2.1` turns the framework documentation repository into a versioned, machine-readable source for `bcp-docs-web`.
+
+## Highlights
+
+### API manifest
+
+New:
+
+```text
+docs/api-manifest.json
+```
+
+The manifest describes every documented public package entrypoint with:
+
+- package name,
+- source ownership,
+- environment boundary,
+- API-reference route,
+- summary,
+- related guide routes.
+
+It complements `docs/platform-manifest.json`, which remains the compatibility/public-entrypoint baseline.
+
+### API reference
+
+New authored guide:
+
+```text
+docs/api-reference.md
+```
+
+It provides one supported reference surface for:
+
+```text
+bcp
+bcp/island
+bcp/cache
+bcp/config
+bcp/validation
+bcp/error
+bcp/database
+bcp/auth
+bcp/server
+bcp/server-only
+bcp/middleware
+```
+
+### Documentation platform contract
+
+New:
+
+```text
+docs/documentation-platform.md
+```
+
+This defines how `bcp-docs-web` should consume:
+
+```text
+docs-web-manifest.json
+platform-manifest.json
+api-manifest.json
+Markdown sources
+```
+
+The website should use manifests for navigation/version/API metadata rather than maintaining a competing hard-coded document list.
+
+### Manifest-driven docs-web synchronization
+
+The matching `bcp-docs-web` update replaces the old manually maintained framework page/category map with a manifest-driven synchronization path.
+
+The sync validates that documentation, platform and API manifests agree on the selected framework version before updating the docs CMS.
+
+### Versioned source foundation
+
+The docs sync continues to accept framework refs such as:
+
+```powershell
+npm run docs:sync -- --ref=v0.2.0
+```
+
+This provides the foundation for historical/versioned documentation without duplicating authored Markdown by hand.
+
+## Compatibility
+
+`0.2.1` is an additive documentation-platform release over the `0.2.0` Framework Platform baseline.
+
+There is no intentional application runtime public-entrypoint removal in this milestone.
+
+Production remains the standalone Node.js target defined by the `0.2.x` platform contract.
+
+## Validation
+
+Before 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
+```
+
+Documentation validation must additionally confirm:
+
+- docs-web routes are unique,
+- every manifest Markdown source exists,
+- API entrypoints are unique,
+- API entrypoints match the platform public-entrypoint set,
+- all manifest versions match the framework package version,
+- prepared npm packages contain all three documentation manifests and new authored guides.
+
+## Next milestone
+
+Planned next:
+
+```text
+0.2.2 — Configuration & Environment v2
+```
+
+Focus:
+
+- typed production configuration improvements,
+- environment validation,
+- startup configuration diagnostics,
+- configuration schema/inspection tooling.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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",