@chidchanun/bcp 0.2.17 → 0.2.19

package/docs/releases/0.2.18.md

@@ -0,0 +1,136 @@
+# BCP Framework 0.2.18 — Deployment Platform v2
+
+Status: **unreleased**
+
+`0.2.18` adds a framework-native deployment lifecycle and hardens prepared npm runtime entrypoints for standalone Node production use.
+
+## Highlights
+
+### New `bcp/deployment` entrypoint
+
+```ts
+import {
+    createDeploymentRuntime,
+} from "bcp/deployment";
+```
+
+Deployment runtime provides:
+
+- ordered resource startup;
+- reverse-order graceful shutdown;
+- startup rollback;
+- readiness checks;
+- deployment/process diagnostics;
+- deployment/instance/release metadata;
+- `SIGTERM` / `SIGINT` handling;
+- integration with existing BCP shutdown hooks.
+
+### Readiness endpoints
+
+```ts
+return createDeploymentReadinessResponse(
+    deployment
+);
+```
+
+Ready runtime returns `200`; non-ready/draining/failed runtime returns `503`.
+
+### Diagnostics
+
+```ts
+return createDeploymentDiagnosticsResponse(
+    deployment
+);
+```
+
+Diagnostics include process/runtime identity, uptime and resource lifecycle state plus optional resource diagnostics.
+
+### Runtime identity
+
+Supported runtime environment values:
+
+```text
+BCP_DEPLOYMENT_ID
+BCP_INSTANCE_ID
+BCP_RELEASE
+NODE_ENV
+BCP_SHUTDOWN_TIMEOUT_MS
+```
+
+### Compiled production entrypoints
+
+Prepared framework packages now use compiled ESM runtime files for additional server-side entrypoints:
+
+```text
+bcp/config       -> config.mjs
+bcp/auth         -> auth.mjs
+bcp/deployment   -> deployment.mjs
+bcp/server       -> server.mjs
+bcp/middleware   -> middleware.mjs
+```
+
+Existing compiled server runtimes such as cache/database/jobs/workflow/events/realtime/testing/plugins/observability remain compiled as before.
+
+This closes a packaging gap where several server entrypoints still resolved directly to TypeScript in the published package.
+
+## Public API additions
+
+```text
+createDeploymentRuntime
+createDeploymentReadinessResponse
+createDeploymentDiagnosticsResponse
+
+DeploymentRuntime
+DeploymentRuntimeOptions
+DeploymentRuntimeState
+DeploymentResource
+DeploymentResourceContext
+DeploymentResourceStatus
+DeploymentReadinessResult
+DeploymentReadinessReport
+DeploymentDiagnosticsReport
+DeploymentMetadata
+DeploymentSignalOptions
+DeploymentShutdownOptions
+```
+
+## Lifecycle model
+
+```text
+idle
+  ↓
+starting
+  ↓
+ready
+  ↓
+draining
+  ↓
+stopped
+```
+
+Failures move the runtime to `failed`.
+
+## Compatibility
+
+There are no intentional breaking changes from `0.2.17`.
+
+Existing production hardening APIs, shutdown hooks, `bcp build`, `bcp package` and application package manifests remain supported.
+
+`bcp/deployment` is additive.
+
+## Validation
+
+Before tagging/publishing:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:e2e
+npm run test:package
+npm run rc:check
+```
+
+The `0.2.18` package smoke validates the compiled deployment runtime plus compiled config/auth/server/middleware entrypoints from the prepared `.package/bcp` staging directory.
+
+Do not tag/publish until the final commit passes the complete RC sequence.

package/docs/releases/0.2.19.md

@@ -0,0 +1,125 @@
+# BCP Framework 0.2.19
+
+Status: **unreleased**
+
+Milestone: **Stability & API Freeze**
+
+`0.2.19` is the final `0.2.x` stabilization milestone before the next `0.3.0` application-platform baseline.
+
+## Highlights
+
+- freezes the documented `bcp/*` public entrypoint set;
+- freezes the supported CLI command set;
+- freezes prepared npm export resolution including browser boundaries;
+- adds deterministic API snapshot generation;
+- adds an API compatibility gate to RC validation;
+- adds a release-readiness report;
+- adds prepared-package Stability & API Freeze smoke coverage;
+- adds deployment lifecycle idempotency regression coverage;
+- keeps compatibility with `0.2.18` with no intentional breaking changes.
+
+## API freeze snapshot
+
+New source of truth:
+
+```text
+docs/api-freeze-snapshot.json
+```
+
+Generate intentionally with:
+
+```bash
+npm run api:snapshot
+```
+
+Validate without changing the snapshot:
+
+```bash
+npm run api:check
+```
+
+The compatibility check prepares the publish package and compares the current package/CLI/API ownership contract against the committed snapshot.
+
+## Release readiness
+
+New commands:
+
+```bash
+npm run release:readiness
+npm run release:readiness:report
+```
+
+The persisted report is written locally to:
+
+```text
+.bcp-framework/release-readiness.json
+```
+
+Readiness includes package/lock/manifests version parity, freeze/baseline metadata, release-note/docs presence and public API parity.
+
+## RC pipeline
+
+`release:check` now includes:
+
+```text
+typecheck
+full test suite
+API compatibility check
+release readiness check
+release metadata check
+```
+
+`test:package` / `package:check` also include `stability-api-freeze-package-smoke.mjs`.
+
+## Compatibility
+
+```text
+previous baseline: 0.2.18
+intentional breaking changes: false
+freeze state: frozen
+```
+
+The existing public package surface remains unchanged from `0.2.18`:
+
+```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
+```
+
+## Validation before release
+
+Run on the exact release commit:
+
+```bash
+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
+```
+
+Do not tag or publish until the complete RC sequence passes.
+
+## Next baseline
+
+`0.3.0` is the next planned BCP Application Platform baseline. Intentional public API changes should be made there with explicit migration and compatibility metadata rather than silently changing the frozen `0.2.19` contract.

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`.