@chidchanun/bcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable framework changes are tracked here before release.
+
+## 0.1.0 - Pre-release
+
+### Framework core
+
+- React SSR and hydration
+- File-based pages and nested layouts
+- Dynamic, catch-all and optional catch-all routes
+- Route groups
+- API route handlers
+- Client navigation and loading state
+- Error and not-found handling
+- Metadata API
+- Environment variables and automatic development env reload
+- Middleware and request interception
+
+### Performance
+
+- Production client build and standalone Node.js server
+- Compression and module preload support
+- Partial hydration and client islands
+- Island hydration and prefetch strategies
+- Route response cache and data cache
+- Cache tag/path invalidation
+
+### Reliability and security
+
+- Unit, integration and production E2E tests
+- Framework configuration with frozen standalone settings
+- Security response headers
+- Request body limits
+- Middleware URL validation
+- Static path traversal protection
+
+### Packaging and Release Candidate
+
+- Publish staging package for BCP Framework
+- Executable `bcp` CLI launcher
+- `create-bcp-app` project generator
+- Package smoke and release metadata checks
+- npm package name/ownership release gate
+- `npm publish --dry-run` verification for framework and generator
+- Clean-install smoke checks from packed tarballs
+- MIT License for BCP Framework and `create-bcp-app`
+- Tag-triggered GitHub Release Check workflow with npm artifact upload
+- Initial framework documentation

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chidchanun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,241 @@
+# BCP Framework
+
+BCP Framework is a React full-stack framework with file-based routing, SSR, client navigation, API routes, middleware, metadata, client islands, cache/revalidation, security defaults and standalone production builds.
+
+> Current status: pre-release `0.1.0`. The repository can produce npm-ready tarballs, validate Release Candidates and run npm publish dry-runs, but publishing to npm is intentionally a separate manual release action.
+
+## Quick start
+
+After the packages are published:
+
+```bash
+npx create-bcp-app my-app
+cd my-app
+npm run dev
+```
+
+Open `http://localhost:3000`.
+
+For local package testing from this repository:
+
+```bash
+npm run package:check
+```
+
+This creates package tarballs under `.package/artifacts` and verifies that `create-bcp-app` can generate a project from the packed BCP Framework artifact.
+
+## Project structure
+
+```text
+app/
+├─ layout.tsx
+├─ page.tsx
+├─ loading.tsx
+├─ error.tsx
+├─ not-found.tsx
+├─ users/
+│  └─ [id]/
+│     └─ page.tsx
+└─ api/
+   └─ hello/
+      └─ route.ts
+
+public/
+bcp.config.ts
+package.json
+tsconfig.json
+```
+
+## Commands
+
+```bash
+bcp dev
+bcp routes
+bcp build
+bcp start
+bcp version
+```
+
+CLI server overrides are available with `--port` and `--hostname`.
+
+## Routing
+
+BCP supports:
+
+```text
+app/page.tsx                     /
+app/about/page.tsx               /about
+app/users/[id]/page.tsx          /users/:id
+app/docs/[...slug]/page.tsx      /docs/*
+app/catalog/[[...slug]]/page.tsx /catalog and /catalog/*
+app/(admin)/settings/page.tsx    /settings
+```
+
+Static routes have priority over dynamic routes, which have priority over catch-all routes.
+
+## API routes
+
+```ts
+// app/api/hello/route.ts
+export function GET() {
+    return Response.json({
+        message: "Hello",
+    });
+}
+```
+
+Supported methods include GET, POST, PUT, PATCH, DELETE, HEAD and OPTIONS. HEAD falls back to GET when no explicit HEAD handler exists, and OPTIONS is generated automatically when appropriate.
+
+## Metadata
+
+```ts
+import type {
+    Metadata,
+} from "bcp";
+
+export const metadata: Metadata = {
+    title: "Dashboard",
+    description: "Dashboard page",
+};
+```
+
+Dynamic routes can export `generateMetadata()` and receive route params.
+
+## Cache and revalidation
+
+```ts
+export const revalidate = 60;
+```
+
+Server data can use:
+
+```ts
+import {
+    cache,
+    dedupe,
+    revalidatePath,
+    revalidateTag,
+} from "bcp/cache";
+```
+
+The current cache implementation is process-local and intentionally does not provide distributed invalidation across multiple Node.js instances.
+
+## Middleware
+
+```ts
+import {
+    next,
+    redirect,
+    type MiddlewareRequest,
+} from "bcp/middleware";
+
+export function middleware(
+    request: MiddlewareRequest
+) {
+    if (
+        request.nextUrl.pathname === "/private" &&
+        !request.cookies.has("session")
+    ) {
+        return redirect("/login");
+    }
+
+    return next();
+}
+```
+
+## Configuration
+
+```ts
+import {
+    defineConfig,
+} from "bcp/config";
+
+export default defineConfig({
+    server: {
+        port: 3000,
+        hostname: "localhost",
+        bodyLimit: 1024 * 1024,
+    },
+    compression: true,
+    build: {
+        minify: true,
+        sourceMaps: false,
+    },
+    cache: {
+        response: true,
+    },
+    security: {
+        poweredByHeader: false,
+        contentSecurityPolicy: false,
+        frameOptions: "SAMEORIGIN",
+        referrerPolicy:
+            "strict-origin-when-cross-origin",
+        permissionsPolicy:
+            "camera=(), microphone=(), geolocation=()",
+    },
+});
+```
+
+Development/build precedence is CLI > `BCP_*` environment > `bcp.config.*` > defaults. Standalone start uses CLI > runtime environment > the config frozen into the production build.
+
+## Production
+
+```bash
+npm run build
+npm start
+```
+
+The standalone output is generated under:
+
+```text
+.bcp-framework/build/
+├─ client/
+├─ public/
+└─ server/
+   ├─ server.mjs
+   ├─ middleware.mjs
+   ├─ cache-manifest.json
+   └─ config.json
+```
+
+## Package preparation
+
+The development monorepo stays private. Publishable artifacts are produced separately:
+
+```bash
+npm run package:prepare
+npm run package:check
+npm run release:check
+```
+
+For the final Release Candidate gate:
+
+```bash
+npm login
+npm run rc:check
+```
+
+`rc:check` validates tests/release metadata, checks npm package-name availability or ownership, performs `npm publish --dry-run`, and clean-installs both generated tarballs into temporary projects.
+
+`package:prepare` stages the framework at `.package/bcp`. The default package name is `bcp`; set `BCP_PACKAGE_NAME` when preparing a scoped or alternate package name.
+
+No real npm publish command is run automatically by the repository.
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md)
+- [Routing](docs/routing.md)
+- [Configuration](docs/configuration.md)
+- [Caching](docs/caching.md)
+- [Middleware](docs/middleware.md)
+- [Security](docs/security.md)
+- [Deployment](docs/deployment.md)
+- [Releasing](docs/releasing.md)
+
+## Requirements
+
+BCP Framework currently targets Node.js 24.11 or newer and React 19.
+
+## License
+
+BCP Framework and `create-bcp-app` are released under the MIT License. See [LICENSE](LICENSE).

package/docs/caching.md

@@ -0,0 +1,76 @@
+# Caching and Revalidation
+
+## Route response cache
+
+A page or API route can opt into production response caching:
+
+```ts
+export const revalidate = 60;
+```
+
+Values:
+
+```text
+number > 0  cache for that many seconds
+false       cache until explicitly invalidated
+0           disable route response caching
+```
+
+BCP returns `X-BCP-Cache` values such as `MISS`, `HIT` and `BYPASS` for cache-enabled production routes.
+
+Requests containing credentials or explicit no-cache directives bypass the shared response cache. Responses that set cookies or are explicitly private/no-store are not stored when the route semantics require respecting the response policy.
+
+## Data cache
+
+```ts
+import {
+    cache,
+} from "bcp/cache";
+
+const loadUser = cache(
+    async (id: string) => {
+        return database.user.find(id);
+    },
+    {
+        key: "user",
+        revalidate: 60,
+        tags: ["users"],
+        paths: ["/users"],
+    }
+);
+```
+
+Concurrent calls for the same cache key share in-flight work.
+
+## Request-scoped dedupe
+
+```ts
+import {
+    dedupe,
+} from "bcp/cache";
+
+const loadSession = dedupe(
+    async () => loadCurrentSession(),
+    "current-session"
+);
+```
+
+`dedupe()` shares work only inside a request context.
+
+## Invalidation
+
+```ts
+import {
+    revalidatePath,
+    revalidateTag,
+} from "bcp/cache";
+
+revalidateTag("users");
+revalidatePath("/dashboard");
+```
+
+Path invalidation clears the matching path and descendants.
+
+## Current deployment limitation
+
+The cache runtime is in-memory and process-local. Restarting the Node.js process clears it, and multiple application instances do not share cache state or invalidation events. A distributed adapter such as Redis is a future extension rather than part of the current release.

package/docs/configuration.md

@@ -0,0 +1,97 @@
+# Configuration
+
+BCP Framework reads one project config file from the project root:
+
+```text
+bcp.config.ts
+bcp.config.mts
+bcp.config.js
+bcp.config.mjs
+```
+
+Only one may exist at a time.
+
+## Example
+
+```ts
+import {
+    defineConfig,
+} from "bcp/config";
+
+export default defineConfig({
+    server: {
+        port: 3000,
+        hostname: "localhost",
+        bodyLimit: 1024 * 1024,
+    },
+    compression: true,
+    build: {
+        minify: true,
+        sourceMaps: false,
+    },
+    cache: {
+        response: true,
+    },
+    experimental: {
+        partialHydration: true,
+        islands: true,
+    },
+    security: {
+        poweredByHeader: false,
+        contentSecurityPolicy: false,
+        frameOptions: "SAMEORIGIN",
+        referrerPolicy:
+            "strict-origin-when-cross-origin",
+        permissionsPolicy:
+            "camera=(), microphone=(), geolocation=()",
+    },
+});
+```
+
+## Precedence
+
+For `dev` and `build`:
+
+```text
+CLI options
+→ BCP_* environment
+→ bcp.config.*
+→ framework defaults
+```
+
+For a standalone production `start`:
+
+```text
+CLI server override
+→ runtime BCP_* environment
+→ configuration frozen at build time
+```
+
+This allows a built artifact to retain build-sensitive settings while still supporting deployment port/hostname overrides.
+
+## Environment overrides
+
+Common framework overrides include:
+
+```text
+BCP_PORT
+BCP_HOSTNAME
+BCP_COMPRESSION
+BCP_BUILD_MINIFY
+BCP_BUILD_SOURCE_MAPS
+BCP_RESPONSE_CACHE
+BCP_BODY_LIMIT
+BCP_POWERED_BY_HEADER
+BCP_SECURITY_CSP
+BCP_SECURITY_FRAME_OPTIONS
+BCP_SECURITY_REFERRER_POLICY
+BCP_SECURITY_PERMISSIONS_POLICY
+BCP_EXPERIMENTAL_PARTIAL_HYDRATION
+BCP_EXPERIMENTAL_ISLANDS
+```
+
+Application environment variables prefixed with `BCP_PUBLIC_` may be embedded into browser bundles. Other application variables remain server-side.
+
+## 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.

package/docs/deployment.md

@@ -0,0 +1,74 @@
+# Deployment
+
+## Build
+
+```bash
+npm run build
+```
+
+BCP writes the production artifact to `.bcp-framework/build`.
+
+```text
+.bcp-framework/build/
+├─ client/
+├─ public/
+├─ manifest.json
+└─ server/
+   ├─ server.mjs
+   ├─ middleware.mjs
+   ├─ cache-manifest.json
+   └─ config.json
+```
+
+## Start
+
+```bash
+npm start
+```
+
+Or run the standalone bundle directly:
+
+```bash
+node .bcp-framework/build/server/server.mjs
+```
+
+## Runtime server overrides
+
+The build retains the configured server defaults. Deployment can override the public bind address with supported runtime variables:
+
+```text
+BCP_PORT
+BCP_HOSTNAME
+```
+
+The CLI also supports:
+
+```bash
+bcp start --port 8080 --hostname 0.0.0.0
+```
+
+## Containers
+
+A minimal deployment image needs the standalone build plus the runtime dependencies required by the generated server bundle, including React/React DOM when they remain external to the bundle.
+
+A typical application image can install production dependencies, copy `.bcp-framework/build`, expose the runtime port and execute `npm start` or `node .bcp-framework/build/server/server.mjs`.
+
+## Reverse proxies
+
+BCP can run behind a reverse proxy or tunnel. Forward the original host correctly when application middleware or absolute URL construction depends on host information.
+
+## Multiple instances
+
+The current response/data cache is process-local. If multiple containers or Node.js processes serve the application, each maintains independent cache entries and invalidation state.
+
+## Production verification
+
+Before deployment:
+
+```bash
+npm run typecheck
+npm test
+npm run build
+```
+
+For framework releases themselves, use `npm run release:check` in the framework repository.

package/docs/getting-started.md

@@ -0,0 +1,82 @@
+# Getting Started
+
+## Create an application
+
+Once `bcp` and `create-bcp-app` are published:
+
+```bash
+npx create-bcp-app my-app
+cd my-app
+npm run dev
+```
+
+The generator creates a React + TypeScript project with a root layout, home page, API example and `bcp.config.ts`.
+
+## Generated scripts
+
+```json
+{
+  "scripts": {
+    "dev": "bcp dev",
+    "build": "bcp build",
+    "start": "bcp start",
+    "routes": "bcp routes",
+    "typecheck": "tsc --noEmit"
+  }
+}
+```
+
+## First page
+
+```tsx
+// app/page.tsx
+export default function HomePage() {
+    return (
+        <main>
+            <h1>Hello BCP</h1>
+        </main>
+    );
+}
+```
+
+## First API route
+
+```ts
+// app/api/hello/route.ts
+export function GET() {
+    return Response.json({
+        message: "Hello",
+    });
+}
+```
+
+## Inspect routes
+
+```bash
+npm run routes
+```
+
+## Production
+
+```bash
+npm run build
+npm start
+```
+
+The production server is standalone and reads build-time configuration from the generated server artifact while still allowing supported runtime environment and CLI server overrides.
+
+## Local tarball testing
+
+Before npm publication, package artifacts can be created from the framework repository:
+
+```bash
+npm run package:check
+```
+
+Then a project can be generated against the local tarball:
+
+```bash
+node create-bcp-app/bin/create-bcp-app.mjs my-app \
+  --no-install \
+  --bcp file:../.package/artifacts/bcp-0.1.0.tgz
+```

package/docs/middleware.md

@@ -0,0 +1,58 @@
+# Middleware
+
+Create `middleware.ts` in the project root.
+
+```ts
+import {
+    next,
+    redirect,
+    rewrite,
+    type MiddlewareConfig,
+    type MiddlewareRequest,
+} from "bcp/middleware";
+
+export const config: MiddlewareConfig = {
+    matcher: [
+        "/dashboard/:path*",
+        "/api/private/:path*",
+    ],
+};
+
+export function middleware(
+    request: MiddlewareRequest
+) {
+    if (
+        !request.cookies.has("session")
+    ) {
+        return redirect("/login");
+    }
+
+    return next();
+}
+```
+
+## Results
+
+Middleware may:
+
+- continue with `next()`
+- rewrite to another same-origin route with `rewrite()`
+- redirect to an HTTP(S) URL with `redirect()`
+- return a `Response` directly
+- mutate request and response headers through middleware options
+
+## Matchers
+
+Matchers support exact paths, dynamic path segments and catch-all patterns such as:
+
+```text
+/dashboard
+/users/:id
+/dashboard/:path*
+```
+
+## Security constraints
+
+Rewrites must stay on the same origin. Redirects and rewrites reject unsupported URL protocols and embedded URL credentials. Header values ultimately pass through Node.js response validation, while framework configuration rejects CR/LF/null-byte injection in security header settings.
+
+Framework-internal `/_bcp/*` requests bypass user middleware execution where required by the runtime.