@chidchanun/bcp 0.2.1 → 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.1",
+  "version": "0.2.2",
   "releaseState": "unreleased",
   "baseline": "framework-platform",
   "runtime": {
@@ -30,6 +30,7 @@
     "update",
     "db",
     "generate",
+    "config",
     "doctor",
     "inspect",
     "help",
@@ -55,7 +56,10 @@
     "projectGenerators": true,
     "projectDiagnostics": true,
     "documentationPlatform": true,
-    "apiManifest": true
+    "apiManifest": true,
+    "typedEnvironmentSchema": true,
+    "configurationDiagnostics": true,
+    "configCheckCli": true
   },
   "storageProviders": [
     "local",
@@ -64,7 +68,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.0",
+    "previousBaseline": "0.2.1",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -75,7 +79,8 @@
     "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.1.md"
+    "releaseNotes": "releases/0.2.2.md"
   }
 }

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.1",
+  "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,
+        }
+      : {}),
   };
 }
 

package/packages/cli/src/bootstrap.ts

@@ -14,6 +14,9 @@ import {
     getConfigFileNames,
     resolveBcpConfig,
 } from "../../config/src/index.js";
+import {
+    getEnvironmentSchemaFileNames,
+} from "../../config/src/environment-loader.js";
 
 import {
     getEnvironmentFileNames,
@@ -86,12 +89,6 @@ async function runCli(
             );
         }
 
-        /*
-         * A standalone start uses the configuration frozen at build time.
-         * Runtime BCP_* environment variables and CLI server overrides stay
-         * available to server.mjs, but source bcp.config.* must not replace
-         * build-dependent settings after the artifact has been created.
-         */
         if (
             cliOptions.command !==
             "start"
@@ -159,9 +156,20 @@ async function runDevSupervisor(
                     )
             );
 
+    const environmentSchemaFiles =
+        getEnvironmentSchemaFileNames()
+            .map(
+                (fileName) =>
+                    path.join(
+                        rootDirectory,
+                        fileName
+                    )
+            );
+
     const watchedFiles = [
         ...envFiles,
         ...configFiles,
+        ...environmentSchemaFiles,
     ];
 
     const bootstrapFile =
@@ -360,7 +368,11 @@ async function runDevSupervisor(
                     "bcp.config."
                 )
                     ? "Config"
-                    : "Env";
+                    : fileName.startsWith(
+                        "bcp.environment."
+                    )
+                        ? "Environment Schema"
+                        : "Env";
 
             console.log("");
             console.log(
@@ -486,6 +498,9 @@ async function runDevSupervisor(
     console.log(
         `[BCP Config] Watching: ${getConfigFileNames().join(", ")}`
     );
+    console.log(
+        `[BCP Environment Schema] Watching: ${getEnvironmentSchemaFileNames().join(", ")}`
+    );
 
     startChild(
         false