@chidchanun/bcp 0.2.18 → 0.2.19

package/docs/releasing.md

@@ -1,27 +1,31 @@
 # 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 is developed in a private npm workspace layout and staged into separate publish artifacts so monorepo-only paths cannot accidentally become the public 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 are:
+The public npm identities 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.
+Application source continues importing through the dependency key `bcp`.
 
 ## 1. Synchronize versions
 
-Use the version helper instead of editing package metadata manually:
+Use the version helper:
+
+```bash
+npm run version:set -- <version>
+```
+
+For the current development target:
 
 ```bash
-npm run version:set -- 0.1.10
+npm run version:set -- 0.2.19
 ```
 
-It synchronizes the release version across:
+It synchronizes:
 
 ```text
 package.json
@@ -30,113 +34,129 @@ 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.
+Review release notes/changelog after changing the version.
+
+## 2. Stability/API compatibility gate
 
-## 2. Run the normal release gate
+`0.2.19` freezes the current `0.2.x` public contract in:
+
+```text
+docs/api-freeze-snapshot.json
+```
+
+Validate it with:
 
 ```bash
-npm run release:check
+npm run api:check
 ```
 
-This runs type checking, the complete unit/integration/E2E/package test suite, then verifies:
+The checker prepares the exact publish staging package and compares its public exports/browser boundaries plus CLI/API ownership to the committed freeze snapshot.
+
+Do not use this as a routine way to make the check pass:
 
-- synchronized semver metadata
-- required documentation
-- MIT license metadata and license files
-- staged public package exports and executable metadata
-- public npm access configuration
-- exact `v<version>` matching when the check runs from a Git tag
+```bash
+npm run api:snapshot
+```
 
-The package smoke test performs clean installs from packed tarballs and verifies that npm actually creates the `bcp` and `create-bcp-app` executables in `node_modules/.bin`.
+Snapshot regeneration is for an explicitly reviewed platform-baseline change. Intentional public API changes should normally move to `0.3.0` rather than silently changing the frozen `0.2.19` surface.
 
-## 3. Verify npm package names and ownership
+## 3. Release-readiness metadata
 
-Authenticate to npm before publishing:
+Run:
 
 ```bash
-npm login
-npm whoami
+npm run release:readiness
 ```
 
-Then run:
+For a local machine-readable report:
 
 ```bash
-npm run release:name-check
+npm run release:readiness:report
 ```
 
-The default RC package names are locked by `scripts/release-env.mjs` to:
+Output:
 
 ```text
-@chidchanun/bcp
-create-bcp-app
+.bcp-framework/release-readiness.json
 ```
 
-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 readiness check covers package/lock/manifests version parity, previous-baseline metadata, release docs, public entrypoint parity, CLI parity and stability capability flags.
 
-The defaults may still be overridden deliberately for a future rename:
+## 4. Run the normal release gate
 
 ```bash
-BCP_PACKAGE_NAME=@another-scope/bcp npm run release:name-check
+npm run release:check
 ```
 
-PowerShell:
+For `0.2.19`, this runs:
+
+```text
+typecheck
+full unit/integration/E2E/package test suite
+API compatibility gate
+release-readiness gate
+release metadata validation
+```
 
-```powershell
-$env:BCP_PACKAGE_NAME="@another-scope/bcp"
+The package smoke suite performs real `npm pack` operations, clean installs and executable checks. Stability package smoke also verifies the prepared package against the freeze snapshot.
+
+## 5. Verify npm package names and ownership
+
+Authenticate first:
+
+```bash
+npm login
+npm whoami
+```
+
+Then:
+
+```bash
 npm run release:name-check
 ```
 
-The Release Check workflow also accepts the optional repository variables:
+Defaults are locked by `scripts/release-env.mjs` to:
 
 ```text
-BCP_PACKAGE_NAME
-BCP_CREATE_PACKAGE_NAME
+@chidchanun/bcp
+create-bcp-app
 ```
 
-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.
+A deliberate future rename may override `BCP_PACKAGE_NAME` / `BCP_CREATE_PACKAGE_NAME`.
 
-## 4. Verify the release version against npm
-
-Run:
+## 6. Verify version availability
 
 ```bash
 npm run release:version-check
 ```
 
-This separately checks the exact local release version against both selected npm package names.
-
-The gate fails when:
+The gate fails if the exact version already exists or if the local stable version cannot advance the selected registry release.
 
-- `<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
+Published npm versions are immutable; use a new patch version for a post-publication fix.
 
-A published npm version is immutable. If a packaging defect is discovered after publication, increment the patch version instead of trying to replace the existing version.
-
-## 5. Run npm publish dry-run and clean-install smoke
+## 7. 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, verifies the installed `bcp` executable, installs the `create-bcp-app` tarball separately, and verifies its generated executable.
-
-No package is uploaded to the npm registry.
+This performs npm publish dry-runs, packs fresh tarballs and validates clean installs without uploading a package.
 
-Artifacts are written to:
+Artifacts are written under:
 
 ```text
 .package/artifacts/
 ```
 
-## 6. Run the complete Release Candidate gate
+## 8. Complete Release Candidate gate
 
-For the final local RC check:
+Immediately before tagging:
 
 ```bash
 npm run rc:check
 ```
 
-This is equivalent to:
+Equivalent high-level sequence:
 
 ```bash
 npm run release:check
@@ -145,15 +165,16 @@ npm run release:version-check
 npm run release:dry-run
 ```
 
-Run this immediately before creating the release tag.
+The exact commit that passes this sequence must be the release-tag commit.
 
-## 7. Inspect package contents
+## 9. Inspect prepared package contents
 
 Review:
 
 ```text
 .package/bcp/package.json
 .package/bcp/LICENSE
+.package/bcp/docs/api-freeze-snapshot.json
 .package/create-bcp-app/package.json
 .package/artifacts/*.tgz
 ```
@@ -165,156 +186,60 @@ npm pack --dry-run .package/bcp
 npm pack --dry-run .package/create-bcp-app
 ```
 
-The framework package is published as:
+## 10. Create the release tag
 
-```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 newly generated application's `package.json` pins the selected framework release exactly so a later plain package-manager install cannot silently move BCP to a different release:
-
-```json
-{
-  "scripts": {
-    "update": "bcp update"
-  },
-  "dependencies": {
-    "bcp": "npm:@chidchanun/bcp@0.1.10"
-  }
-}
-```
-
-The explicit updater is responsible for resolving and installing later framework releases.
-
-## 8. Create the release tag
-
-Only after `npm run rc:check` passes and `CHANGELOG.md` is ready:
+For `0.2.19`:
 
 ```bash
 git status
-git tag -a v0.1.10 -m "BCP Framework v0.1.10"
-git push origin v0.1.10
+git tag -a v0.2.19 -m "BCP Framework v0.2.19"
+git push origin v0.2.19
 ```
 
-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.
+Always use the exact version in `package.json`.
 
-## 9. Guarded publish
+## 11. Guarded publish
 
-After the tag workflow artifacts have been reviewed, publish from an authenticated local npm session with:
+After reviewing the tag/RC result:
 
 ```bash
 npm run release:publish:yes
 ```
 
-This explicit script is preferred over forwarding `--yes` through `npm run`, because npm CLI argument forwarding can vary by npm/platform version.
-
-The command refuses to publish unless all of these conditions are true:
+The publish command requires a clean working tree, the exact `v<version>` tag at HEAD, npm authentication, successful release gates and an unpublished target version.
 
-- explicit publish confirmation is present
-- 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 accepted by npm
-
-Stable BCP releases use this npm dist-tag by default, including stable `0.x` releases:
+Stable BCP releases publish to:
 
 ```text
 latest
 ```
 
-Use `BCP_DIST_TAG` only when intentionally publishing a separate channel such as `next` or `beta`:
-
-```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. After `npm publish` succeeds, the release script accepts either normal version visibility or the selected dist-tag pointing at the new version. This prevents npm registry/security-processing delays from being misclassified as a failed publish.
-
-Using `latest` for stable releases is also part of the updater contract: `bcp update` resolves `@chidchanun/bcp@latest` by default.
-
-## 10. Recover from a partial publish
+Use `BCP_DIST_TAG` only for intentionally separate channels such as `next` or `beta`.
 
-If the framework package was accepted by npm but publishing `create-bcp-app` failed, fix the external issue without changing that release commit or tag, then use:
+If a partial publish occurs after one package succeeds, resume with:
 
 ```bash
 npm run release:resume
 ```
 
-Resume mode intentionally does not run `release:version-check` or `npm publish --dry-run` for the already-published version. It still runs the complete local release checks and package smoke tests, verifies package ownership, skips package versions already accepted by npm, and attempts only the missing package.
-
-Do not use resume mode to overwrite or replace an existing npm version; npm versions are immutable.
-
-## 11. Install or update the stable release
-
-The recommended new-project path is:
-
-```bash
-npx create-bcp-app@latest my-app
-```
-
-A generated application keeps the documented `bcp` import name through an npm alias and pins the selected framework version exactly.
-
-For an existing project already on an updater-capable release:
-
-```bash
-npm run update
-```
-
-For a project on BCP 0.1.9 or older, bootstrap the updater once with:
+## 0.2.19 release checklist
 
 ```bash
-npx @chidchanun/bcp@latest update
+npm run version:set -- 0.2.19
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:e2e
+npm run test:package
+npm run api:check
+npm run release:readiness
+npm run rc:check
 ```
 
-A manual install that preserves the `bcp` import name is:
+Only after all checks pass:
 
 ```bash
-npm install bcp@npm:@chidchanun/bcp@latest react react-dom
-```
-
-Application code then continues using:
-
-```ts
-import {
-    Link,
-} from "bcp";
+git tag -a v0.2.19 -m "BCP Framework v0.2.19"
+git push origin v0.2.19
+npm run release:publish:yes
 ```
-
-The scoped package can also be installed directly as `@chidchanun/bcp@latest`, but applications using the framework's documented `bcp` import path should prefer the alias form above.
-
-## 12. Trusted publishing
-
-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.
-
-After the npm package settings are available, configure the repository/workflow as a trusted publisher 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/stability-api-freeze.md

@@ -0,0 +1,179 @@
+# Stability & API Freeze — 0.2.19
+
+BCP Framework `0.2.19` is the final stabilization milestone for the `0.2.x` platform before the next `0.3.0` application-platform baseline.
+
+This release intentionally does **not** add a new application subsystem. Its purpose is to freeze the supported public package/CLI contract, strengthen release gates and catch accidental compatibility regressions before publication.
+
+## Frozen contract
+
+The committed source of truth is:
+
+```text
+docs/api-freeze-snapshot.json
+```
+
+It records:
+
+- the supported `bcp/*` public entrypoint set;
+- the supported CLI command set;
+- prepared npm `exports` including `types`, `default` and `browser` targets;
+- API source/environment ownership from `docs/api-manifest.json`;
+- the compatibility baseline (`0.2.18`);
+- the no-intentional-breaking-change policy for `0.2.19`.
+
+The frozen public package entrypoints are:
+
+```text
+bcp
+bcp/island
+bcp/cache
+bcp/config
+bcp/validation
+bcp/error
+bcp/database
+bcp/auth
+bcp/jobs
+bcp/workflow
+bcp/events
+bcp/realtime
+bcp/testing
+bcp/plugins
+bcp/observability
+bcp/deployment
+bcp/server
+bcp/server-only
+bcp/middleware
+```
+
+`./package.json` is also frozen as a package export, although it is not an application API entrypoint.
+
+## API compatibility gate
+
+Run:
+
+```bash
+npm run api:check
+```
+
+The compatibility checker prepares the exact npm staging package, generates the current contract and compares it to `docs/api-freeze-snapshot.json`.
+
+The check fails when, for example:
+
+- a public entrypoint is removed or added;
+- a CLI command changes without an explicit new platform baseline;
+- `bcp/server` stops resolving to `server.mjs` in the prepared package;
+- a server-only browser poison target disappears;
+- an entrypoint changes API source/environment ownership;
+- the current version/baseline no longer matches the committed freeze.
+
+This prevents source metadata, prepared npm metadata and documentation metadata from drifting independently.
+
+## Snapshot regeneration
+
+To intentionally regenerate the contract:
+
+```bash
+npm run api:snapshot
+```
+
+That command rewrites:
+
+```text
+docs/api-freeze-snapshot.json
+```
+
+For `0.2.19`, snapshot changes require explicit review because the milestone promises no intentional breaking changes from `0.2.18`.
+
+Large or breaking public-surface changes should normally be deferred to `0.3.0` rather than silently updating the `0.2.19` snapshot.
+
+## Release readiness
+
+Run:
+
+```bash
+npm run release:readiness
+```
+
+The readiness report checks:
+
+- root/client/create-app version parity;
+- `package-lock.json` version parity;
+- platform/API/docs-web version parity;
+- `unreleased` release state;
+- `0.2.18` previous-baseline metadata;
+- no intentional breaking changes;
+- API freeze snapshot version/baseline;
+- public entrypoint parity;
+- CLI freeze parity;
+- current release notes and docs route;
+- stability capability flags.
+
+To also persist a local machine-readable report:
+
+```bash
+npm run release:readiness:report
+```
+
+The report is written to:
+
+```text
+.bcp-framework/release-readiness.json
+```
+
+It is a local build artifact and is not the release source of truth.
+
+## RC integration
+
+`0.2.19` strengthens the release pipeline:
+
+```text
+npm run typecheck
+npm test
+  -> unit
+  -> integration
+  -> e2e
+  -> prepared-package smoke
+      -> Stability & API Freeze smoke
+npm run api:check
+npm run release:readiness
+release metadata check
+npm name/version checks
+npm publish dry-run
+```
+
+`npm run rc:check` must pass on the exact commit that will be tagged.
+
+## Lifecycle stabilization
+
+The stability suite adds explicit idempotency coverage for Deployment Platform v2:
+
+- concurrent/repeated `start()` calls must start a resource once;
+- concurrent/repeated `shutdown()` calls must stop a resource once;
+- shutdown remains reverse ordered;
+- a stopped runtime cannot be restarted.
+
+Existing subsystem-specific suites remain authoritative for jobs, workflows, outbox/events, realtime, cache, plugins and deployment behavior.
+
+## Compatibility policy
+
+`0.2.19` declares:
+
+```text
+previous baseline: 0.2.18
+intentional breaking changes: false
+freeze state: frozen
+```
+
+Bug fixes may still change incorrect implementation behavior, but they must not silently remove documented public entrypoints or change their package-resolution contract.
+
+## Moving to 0.3.0
+
+`0.3.0` is the next platform baseline. That milestone may intentionally revise the frozen surface, but changes should be accompanied by:
+
+1. a reviewed API snapshot update;
+2. explicit compatibility/breaking-change metadata;
+3. migration documentation;
+4. updated package/docs manifests;
+5. regression and prepared-package coverage.
+
+The `0.2.19` snapshot therefore becomes the comparison point for the next platform-generation work.

package/package.json

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