@chidchanun/bcp 0.1.0

package/docs/releasing.md

@@ -0,0 +1,299 @@
+# Releasing BCP Framework
+
+The source repository is a private npm workspace package for development. Release artifacts are staged separately so monorepo-only paths cannot accidentally become the published package contract.
+
+BCP Framework and `create-bcp-app` are prepared for public release under the MIT License. Normal build and test tooling never performs a real `npm publish` automatically. The dedicated release publish command requires explicit confirmation and a matching Git tag.
+
+The selected public npm identities for the first release are:
+
+```text
+@chidchanun/bcp
+create-bcp-app
+```
+
+Application source continues importing from `bcp`. `create-bcp-app` stores the scoped framework package behind the dependency key `bcp` using an npm alias.
+
+## 1. Synchronize versions
+
+Use the version helper instead of editing package metadata manually:
+
+```bash
+npm run version:set -- 0.1.0
+```
+
+It synchronizes the release version across:
+
+```text
+package.json
+packages/client/package.json
+create-bcp-app/package.json
+package-lock.json
+```
+
+Review `CHANGELOG.md` after changing the version. The BCP CLI reads the framework version from package metadata instead of a duplicated hard-coded constant.
+
+## 2. Run the normal release gate
+
+```bash
+npm run release:check
+```
+
+This runs type checking, the complete unit/integration/E2E/package test suite, then verifies:
+
+- synchronized semver metadata
+- required documentation
+- MIT license metadata and license files
+- staged public package exports
+- public npm access configuration
+- exact `v<version>` matching when the check runs from a Git tag
+
+## 3. Verify npm package names and ownership
+
+Before the first publish, authenticate to npm:
+
+```bash
+npm login
+npm whoami
+```
+
+Then run:
+
+```bash
+npm run release:name-check
+```
+
+The default RC package names are now locked by `scripts/release-env.mjs` to:
+
+```text
+@chidchanun/bcp
+create-bcp-app
+```
+
+The check queries both package names. If a package is not present in the registry, the name is treated as currently available. If it already exists, the current npm account must be listed as an owner or the check fails.
+
+The defaults may still be overridden deliberately for a future rename:
+
+```bash
+BCP_PACKAGE_NAME=@another-scope/bcp npm run release:name-check
+```
+
+PowerShell:
+
+```powershell
+$env:BCP_PACKAGE_NAME="@another-scope/bcp"
+npm run release:name-check
+```
+
+The Release Check workflow also accepts the optional repository variables:
+
+```text
+BCP_PACKAGE_NAME
+BCP_CREATE_PACKAGE_NAME
+```
+
+When those variables are unset or empty, the locked defaults above are used. Package-name availability can change at any time, so treat this check as a point-in-time release gate rather than a permanent reservation.
+
+## 4. Verify the release version against npm
+
+Run:
+
+```bash
+npm run release:version-check
+```
+
+This separately checks the exact local release version against both selected npm package names.
+
+The gate fails when:
+
+- `<package>@<local-version>` already exists and therefore cannot be republished
+- the local version is older than or equal to the registry's current latest version
+
+Because `@chidchanun/bcp` and `create-bcp-app` are new package names at the time of the first RC check, `0.1.0` is valid as their initial release version unless either name/version is published before the release completes.
+
+## 5. Run npm publish dry-run and clean-install smoke
+
+```bash
+npm run release:dry-run
+```
+
+This performs `npm publish --dry-run` for both staged packages, packs fresh tarballs, installs the framework tarball into a temporary clean project, executes the installed BCP CLI, installs the `create-bcp-app` tarball separately, and generates another temporary app from the installed generator.
+
+No package is uploaded to the npm registry.
+
+Artifacts are written to:
+
+```text
+.package/artifacts/
+```
+
+## 6. Run the complete Release Candidate gate
+
+For the final local RC check:
+
+```bash
+npm run rc:check
+```
+
+This is equivalent to:
+
+```bash
+npm run release:check
+npm run release:name-check
+npm run release:version-check
+npm run release:dry-run
+```
+
+Run this immediately before creating the release tag.
+
+## 7. Inspect package contents
+
+Review:
+
+```text
+.package/bcp/package.json
+.package/bcp/LICENSE
+.package/create-bcp-app/package.json
+.package/artifacts/*.tgz
+```
+
+Useful manual checks:
+
+```bash
+npm pack --dry-run .package/bcp
+npm pack --dry-run .package/create-bcp-app
+```
+
+The framework package is published as:
+
+```text
+@chidchanun/bcp
+```
+
+but exposes application import paths through the npm alias key:
+
+```text
+bcp
+bcp/island
+bcp/cache
+bcp/config
+bcp/middleware
+```
+
+and the executable:
+
+```text
+bcp
+```
+
+A generated application's `package.json` should therefore contain a dependency equivalent to:
+
+```json
+{
+  "dependencies": {
+    "bcp": "npm:@chidchanun/bcp@^0.1.0"
+  }
+}
+```
+
+## 8. Create the release tag
+
+Only after `npm run rc:check` passes and `CHANGELOG.md` is ready:
+
+```bash
+git status
+git tag -a v0.1.0 -m "BCP Framework v0.1.0"
+git push origin v0.1.0
+```
+
+Use the actual version from `package.json` in the tag.
+
+The GitHub Release Check workflow validates a `v*` tag, rechecks the npm target version, and uploads the npm tarballs as workflow artifacts. It does not publish them.
+
+## 9. Guarded first publish
+
+After the tag workflow artifacts have been reviewed, publish from an authenticated local npm session with:
+
+```bash
+npm run release:publish -- --yes
+```
+
+The command refuses to publish unless all of these conditions are true:
+
+- `--yes` is supplied
+- the git working tree is clean
+- HEAD has the exact tag `v<package-version>`
+- npm authentication succeeds
+- the RC checks succeed again
+- staged package names and versions match the selected release
+- the target version has not already been published
+
+For `0.x` releases the default npm dist-tag is:
+
+```text
+next
+```
+
+For `1.x` and later it defaults to:
+
+```text
+latest
+```
+
+Override the tag explicitly when needed:
+
+```bash
+BCP_DIST_TAG=beta npm run release:publish -- --yes
+```
+
+PowerShell example:
+
+```powershell
+$env:BCP_DIST_TAG="beta"
+npm run release:publish -- --yes
+```
+
+The framework publishes first. `create-bcp-app` publishes only after the framework publish succeeds and npm confirms that version is visible in the registry.
+
+## 10. Recover from a partial publish
+
+If the framework package was published successfully but publishing `create-bcp-app` failed, fix the external issue without changing the release commit or tag, then use:
+
+```bash
+npm run release:publish -- --yes --resume
+```
+
+`--resume` skips versions that already exist and attempts only the missing package. Do not use `--resume` to overwrite or replace an existing npm version; npm versions are immutable.
+
+## 11. Install the preview release
+
+The recommended path is the generator:
+
+```bash
+npx create-bcp-app@next my-app
+```
+
+For a `0.x` release published with the default `next` dist-tag, a manual install that preserves the `bcp` import name is:
+
+```bash
+npm install bcp@npm:@chidchanun/bcp@next react react-dom
+```
+
+Application code then continues using:
+
+```ts
+import {
+    Link,
+} from "bcp";
+```
+
+The scoped package can also be installed directly as `@chidchanun/bcp@next`, but applications using the framework's documented `bcp` import path should prefer the alias form above.
+
+## 12. Trusted publishing after the initial release
+
+For subsequent releases, prefer npm Trusted Publishing with GitHub Actions instead of a long-lived write token. npm supports GitHub Actions OIDC publishing and recommends trusted publishing for CI-based releases.
+
+The first package version must exist before its npm package settings can be configured for a trusted publisher. After the initial manual release, configure the repository/workflow as a trusted publisher on npm and move the real publish action into the guarded GitHub release workflow.
+
+## License
+
+BCP Framework and `create-bcp-app` use the MIT License. See `LICENSE` and `create-bcp-app/LICENSE`.

package/docs/routing.md

@@ -0,0 +1,103 @@
+# Routing
+
+BCP Framework uses the `app/` directory as the routing source of truth.
+
+## Static routes
+
+```text
+app/page.tsx        /
+app/about/page.tsx  /about
+```
+
+## Dynamic segments
+
+```text
+app/users/[id]/page.tsx
+```
+
+A request to `/users/15` receives:
+
+```ts
+{
+    params: {
+        id: "15",
+    },
+}
+```
+
+## Catch-all segments
+
+```text
+app/docs/[...slug]/page.tsx
+```
+
+`/docs/guides/install` receives:
+
+```ts
+params.slug // ["guides", "install"]
+```
+
+A required catch-all must consume at least one URL segment.
+
+## Optional catch-all segments
+
+```text
+app/catalog/[[...slug]]/page.tsx
+```
+
+Both `/catalog` and `/catalog/hardware/keyboards` match. The base route receives `slug === undefined`; nested paths receive a string array.
+
+## Route groups
+
+```text
+app/(admin)/layout.tsx
+app/(admin)/settings/page.tsx
+```
+
+The public URL is `/settings`. The `(admin)` segment participates in filesystem layout composition but is removed from the public pathname.
+
+## Priority
+
+When multiple patterns can match, BCP prefers:
+
+```text
+static
+→ dynamic
+→ catch-all
+→ optional catch-all
+```
+
+Route discovery rejects ambiguous patterns and duplicate public paths instead of selecting a route nondeterministically.
+
+## Layouts
+
+Layouts are inherited from the app root through nested directories and route groups. Client navigation preserves compatible layout identities so layout state can survive page changes.
+
+## Special files
+
+BCP recognizes route-adjacent special files including:
+
+```text
+layout.tsx
+loading.tsx
+error.tsx
+not-found.tsx
+```
+
+## Navigation
+
+Use `Link`, `navigate` or `useRouter` from `bcp` for client navigation.
+
+```tsx
+import {
+    Link,
+} from "bcp";
+
+export default function Page() {
+    return (
+        <Link href="/about">
+            About
+        </Link>
+    );
+}
+```

package/docs/security.md

@@ -0,0 +1,57 @@
+# Security
+
+BCP Framework applies a security gateway in both development and standalone production modes.
+
+## Default response headers
+
+The default policy includes:
+
+```http
+X-Content-Type-Options: nosniff
+X-Frame-Options: SAMEORIGIN
+Referrer-Policy: strict-origin-when-cross-origin
+Permissions-Policy: camera=(), microphone=(), geolocation=()
+```
+
+`X-Powered-By` is hidden by default.
+
+## Content Security Policy
+
+CSP is configurable but disabled by default:
+
+```ts
+security: {
+    contentSecurityPolicy:
+        "default-src 'self'; script-src 'self' 'unsafe-inline'",
+}
+```
+
+The current client bootstrap still uses inline script content in some runtime paths, so enabling a strict CSP without a compatible nonce/hash policy can block hydration or development tooling. Nonce/hash support is a future hardening area.
+
+## Request body limit
+
+The default request body limit is 1 MiB:
+
+```ts
+server: {
+    bodyLimit: 1024 * 1024,
+}
+```
+
+Requests exceeding the limit are rejected by the outer gateway with HTTP 413 before reaching the API handler.
+
+## Static assets
+
+Public asset resolution decodes the URL, rejects null bytes, resolves the candidate beneath `public/`, resolves filesystem symlinks and verifies the final real path remains inside the public directory. This prevents path and symlink traversal from escaping the public root.
+
+## Middleware URLs
+
+Middleware rewrites must remain same-origin. Redirects and rewrites reject non-HTTP(S) protocols and URLs containing embedded credentials.
+
+## Header validation
+
+Security config values reject carriage return, line feed and null bytes to prevent response-header injection through framework configuration.
+
+## Deployment note
+
+The security gateway is the outer production layer, so security headers and body limits also apply to response-cache hits, middleware responses, static assets and error responses.

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@chidchanun/bcp",
+  "version": "0.1.0",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chidchanun/bcp-freamwork.git"
+  },
+  "homepage": "https://github.com/chidchanun/bcp-freamwork#readme",
+  "bugs": {
+    "url": "https://github.com/chidchanun/bcp-freamwork/issues"
+  },
+  "keywords": [
+    "bcp",
+    "react",
+    "framework",
+    "ssr",
+    "routing",
+    "fullstack"
+  ],
+  "engines": {
+    "node": ">=24.11.0"
+  },
+  "bin": {
+    "bcp": "./packages/cli/bin/bcp.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./packages/client/src/index.tsx",
+      "default": "./packages/client/src/index.tsx"
+    },
+    "./island": {
+      "types": "./packages/client/src/islands.tsx",
+      "default": "./packages/client/src/islands.tsx"
+    },
+    "./cache": {
+      "types": "./packages/client/src/cache.ts",
+      "default": "./packages/client/src/cache.ts"
+    },
+    "./config": {
+      "types": "./packages/client/src/config.ts",
+      "default": "./packages/client/src/config.ts"
+    },
+    "./middleware": {
+      "types": "./packages/server/src/middleware.ts",
+      "default": "./packages/server/src/middleware.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@babel/core": "^8.0.1",
+    "@babel/preset-react": "^8.0.1",
+    "@babel/preset-typescript": "^8.0.1",
+    "chokidar": "^5.0.0",
+    "esbuild": "^0.28.2",
+    "react-refresh": "^0.18.0",
+    "tsx": "^4.23.12"
+  },
+  "peerDependencies": {
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}