@chidchanun/bcp 0.2.0 → 0.2.2

package/docs/environment-validation.md

@@ -0,0 +1,224 @@
+# Environment Validation
+
+BCP Framework `0.2.2` adds an optional typed environment schema for application-specific environment variables.
+
+The schema is separate from `bcp.config.*` and uses the project convention:
+
+```text
+bcp.environment.ts
+bcp.environment.mts
+bcp.environment.js
+bcp.environment.mjs
+```
+
+Keep only one environment schema file in an application.
+
+## Define a schema
+
+```ts
+import {
+    defineEnvironment,
+} from "bcp/config";
+
+export default defineEnvironment({
+    DB_HOST: {
+        type: "string",
+        required: true,
+    },
+
+    DB_PORT: {
+        type: "number",
+        default: 3306,
+        min: 1,
+        max: 65535,
+    },
+
+    SESSION_SECRET: {
+        type: "string",
+        required: true,
+        secret: true,
+        minLength: 32,
+    },
+
+    FEATURE_ENABLED: {
+        type: "boolean",
+        default: false,
+    },
+
+    BCP_PUBLIC_API_URL: {
+        type: "url",
+        required: true,
+    },
+});
+```
+
+Supported types:
+
+```text
+string
+number
+boolean
+url
+```
+
+Supported rule fields:
+
+```text
+type
+required
+secret
+minLength
+maxLength
+min
+max
+default
+description
+```
+
+`minLength` / `maxLength` are intended for string and URL values. `min` / `max` are intended for numbers.
+
+## Validate from the CLI
+
+```bash
+bcp config check
+```
+
+On Windows where another `bcp.exe` may exist:
+
+```powershell
+npm exec -- bcp-framework config check
+```
+
+JSON output:
+
+```powershell
+npm exec -- bcp-framework config check --json
+```
+
+The command validates:
+
+- `bcp.config.*`,
+- `bcp.environment.*`,
+- loaded `.env` files,
+- configured BCP runtime values,
+- application environment-schema values,
+- selected production safety diagnostics.
+
+Development is the default mode.
+
+To inspect production diagnostics from a shell where `NODE_ENV` can be set:
+
+```bash
+NODE_ENV=production bcp config check
+```
+
+PowerShell example:
+
+```powershell
+$env:NODE_ENV = "production"
+npm exec -- bcp-framework config check
+Remove-Item Env:NODE_ENV
+```
+
+## Startup validation
+
+When a project contains `bcp.environment.*`, `bcp dev` and `bcp build` validate the schema before the application starts or a production build is produced.
+
+A missing or invalid required environment variable stops startup/build with a configuration error.
+
+Example:
+
+```text
+BCP Configuration Error:
+- SESSION_SECRET must contain at least 32 character(s).
+```
+
+Changing `bcp.environment.*` while the development supervisor is running automatically restarts the dev worker, the same way changes to `.env*` or `bcp.config.*` do.
+
+## Public variables and secrets
+
+Variables beginning with:
+
+```text
+BCP_PUBLIC_
+```
+
+can be embedded into browser bundles.
+
+Do not use that prefix for credentials, session secrets, access keys or private service tokens.
+
+BCP treats this as an error:
+
+```ts
+export default defineEnvironment({
+    BCP_PUBLIC_TOKEN: {
+        type: "string",
+        required: true,
+        secret: true,
+    },
+});
+```
+
+The `secret: true` flag is metadata used by validation/tooling. It does not encrypt the environment value. Secrets must still be stored in an appropriate environment/secret manager and kept out of public client variables.
+
+## Programmatic validation
+
+The same primitives are public through `bcp/config`:
+
+```ts
+import {
+    defineEnvironment,
+    validateEnvironment,
+} from "bcp/config";
+
+const schema = defineEnvironment({
+    API_URL: {
+        type: "url",
+        required: true,
+    },
+});
+
+const result = validateEnvironment(
+    schema,
+    process.env
+);
+
+if (!result.ok) {
+    console.error(
+        result.issues
+    );
+}
+```
+
+The parsed `result.values` contains only keys declared by the schema. BCP configuration diagnostics do not print raw secret values.
+
+## Production diagnostics
+
+Production configuration checks can emit warnings for potentially risky choices such as:
+
+- production source maps enabled,
+- `security.poweredByHeader` enabled,
+- Content-Security-Policy disabled,
+- trusted proxy mode enabled.
+
+Warnings do not block a build. Environment-schema errors do.
+
+Trusted proxy warnings are informational safety reminders. Enable `BCP_TRUST_PROXY` only when untrusted clients cannot bypass the trusted reverse proxy/load balancer.
+
+## Existing applications
+
+Environment schemas are optional.
+
+Projects without `bcp.environment.*` continue to use the existing `.env` loading and BCP configuration behavior. The `0.2.2` schema system is additive and does not change the established configuration precedence:
+
+```text
+CLI override
+    ↓
+BCP_* environment
+    ↓
+bcp.config.*
+    ↓
+framework defaults
+```
+
+Application-specific variables are validated against `bcp.environment.*` after environment files are loaded.

package/docs/platform-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "releaseState": "unreleased",
   "baseline": "framework-platform",
   "runtime": {
@@ -30,6 +30,7 @@
     "update",
     "db",
     "generate",
+    "config",
     "doctor",
     "inspect",
     "help",
@@ -53,7 +54,12 @@
     "storageEcosystem": true,
     "productionHardening": true,
     "projectGenerators": true,
-    "projectDiagnostics": true
+    "projectDiagnostics": true,
+    "documentationPlatform": true,
+    "apiManifest": true,
+    "typedEnvironmentSchema": true,
+    "configurationDiagnostics": true,
+    "configCheckCli": true
   },
   "storageProviders": [
     "local",
@@ -62,14 +68,19 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.1.29",
+    "previousBaseline": "0.2.1",
     "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",
+    "environmentValidation": "environment-validation.md",
     "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.0.md"
+    "releaseNotes": "releases/0.2.2.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/docs/releases/0.2.2.md

@@ -0,0 +1,118 @@
+# BCP Framework 0.2.2
+
+> **Release state:** unreleased development target.
+
+BCP Framework `0.2.2` is the **Configuration & Environment v2** milestone.
+
+The release keeps the established BCP configuration precedence and adds an optional typed application environment schema, configuration diagnostics and a dedicated CLI validation workflow.
+
+## Highlights
+
+### Typed application environment schema
+
+Projects can add:
+
+```text
+bcp.environment.ts
+```
+
+using the public `bcp/config` API:
+
+```ts
+import {
+    defineEnvironment,
+} from "bcp/config";
+
+export default defineEnvironment({
+    DB_HOST: {
+        type: "string",
+        required: true,
+    },
+    DB_PORT: {
+        type: "number",
+        default: 3306,
+    },
+    SESSION_SECRET: {
+        type: "string",
+        required: true,
+        secret: true,
+        minLength: 32,
+    },
+});
+```
+
+Supported values include string, number, boolean and absolute HTTP(S) URL rules.
+
+### `bcp config check`
+
+New CLI command:
+
+```bash
+bcp config check
+bcp config check --json
+```
+
+It validates project configuration, environment schema values and production diagnostics without printing secret values.
+
+### Startup diagnostics
+
+`bcp dev` and `bcp build` validate `bcp.environment.*` before starting the application/build.
+
+Schema errors fail early. Production configuration warnings are reported without blocking the build.
+
+### Development schema watching
+
+The dev supervisor now watches:
+
+```text
+.env*
+bcp.config.*
+bcp.environment.*
+```
+
+and restarts the worker when any of these configuration sources change.
+
+### Public configuration API
+
+`bcp/config` now exposes additive environment/configuration helpers including:
+
+```text
+defineEnvironment
+validateEnvironment
+loadBcpEnvironmentSchema
+diagnoseBcpConfiguration
+assertConfigurationDiagnostics
+```
+
+## Compatibility
+
+`0.2.2` does not intentionally remove public entrypoints from `0.2.1`.
+
+Existing projects without `bcp.environment.*` continue to work with the previous `.env` and `bcp.config.*` behavior.
+
+The configuration precedence remains:
+
+```text
+CLI > BCP_* environment > bcp.config.* > framework defaults
+```
+
+## Security
+
+A schema variable marked `secret: true` must not use the `BCP_PUBLIC_` prefix. BCP treats that combination as a configuration error because public-prefixed values can be embedded into browser bundles.
+
+`secret: true` is metadata for validation/tooling and does not encrypt environment values.
+
+## Validation
+
+Before tagging/publishing:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:package
+npm run test:e2e
+npm run rc:check
+```
+
+The final release tag must point at the exact commit that passed the complete RC sequence.

package/package.json

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

package/packages/cli/src/args.ts

@@ -9,6 +9,7 @@ export type CliCommand =
   | "update"
   | "db"
   | "generate"
+  | "config"
   | "doctor"
   | "inspect"
   | "help"
@@ -28,6 +29,10 @@ export type GenerateCliKind =
   | "migration"
   | "help";
 
+export type ConfigCliAction =
+  | "check"
+  | "help";
+
 export interface CliOptions {
   command: CliCommand;
 
@@ -54,6 +59,8 @@ export interface CliOptions {
   generateKind?: GenerateCliKind;
 
   generateName?: string;
+
+  configAction?: ConfigCliAction;
 }
 
 export function parseCliArgs(
@@ -97,6 +104,9 @@ export function parseCliArgs(
   let generateName:
     string | undefined;
 
+  let configAction:
+    ConfigCliAction | undefined;
+
   let commandSet = false;
 
   for (
@@ -120,6 +130,11 @@ export function parseCliArgs(
         command === "generate"
       ) {
         generateKind = "help";
+      } else if (
+        commandSet &&
+        command === "config"
+      ) {
+        configAction = "help";
       } else {
         command = "help";
       }
@@ -268,13 +283,6 @@ export function parseCliArgs(
       );
     }
 
-    /**
-     * npm compatibility
-     *
-     * Some npm environments may consume an unknown script
-     * option such as --port and leave only its numeric value
-     * in argv. Accept a bare number for dev/start servers.
-     */
     if (
       isPortShortcut(argument) &&
       (
@@ -374,6 +382,32 @@ export function parseCliArgs(
       );
     }
 
+    if (
+      commandSet &&
+      command === "config"
+    ) {
+      if (
+        configAction === undefined
+      ) {
+        if (
+          argument === "check" ||
+          argument === "help"
+        ) {
+          configAction =
+            argument;
+          continue;
+        }
+
+        throw new Error(
+          `Unknown config command: ${argument}`
+        );
+      }
+
+      throw new Error(
+        `Unexpected argument: ${argument}`
+      );
+    }
+
     if (commandSet) {
       throw new Error(
         `Unexpected argument: ${argument}`
@@ -388,6 +422,7 @@ export function parseCliArgs(
       argument === "update" ||
       argument === "db" ||
       argument === "generate" ||
+      argument === "config" ||
       argument === "doctor" ||
       argument === "inspect" ||
       argument === "help" ||
@@ -418,10 +453,11 @@ export function parseCliArgs(
   if (
     json &&
     command !== "doctor" &&
-    command !== "inspect"
+    command !== "inspect" &&
+    command !== "config"
   ) {
     throw new Error(
-      "Option --json is only valid with `bcp doctor` or `bcp inspect`."
+      "Option --json is only valid with `bcp doctor`, `bcp inspect`, or `bcp config`."
     );
   }
 
@@ -464,6 +500,11 @@ export function parseCliArgs(
           generateName,
         }
       : {}),
+    ...(command === "config"
+      ? {
+          configAction,
+        }
+      : {}),
   };
 }