@chidchanun/bcp 0.2.1 → 0.2.3

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/docs/releases/0.2.3.md

@@ -0,0 +1,77 @@
+# BCP Framework 0.2.3
+
+## Database Platform v2
+
+BCP `0.2.3` turns the framework database layer into a provider-neutral SQL platform while preserving the existing `bcp/database` application API.
+
+### Database adapter contract
+
+- `BcpDatabase` delegates connection, query, execute, transaction and disconnect behavior through `DatabaseAdapter`.
+- Custom adapters can be injected directly or through lazy factories.
+- Provider implementations are separated into MySQL, PostgreSQL and SQLite runtime modules.
+- Provider drivers remain optional dependencies and are loaded lazily.
+
+### PostgreSQL
+
+- Added built-in PostgreSQL support through `pg`.
+- `DATABASE_URL=postgresql://...` selects PostgreSQL automatically.
+- `DB_DRIVER=postgresql`, `postgres` and `pg` are supported provider names.
+- Query parameters use PostgreSQL `$1`, `$2`, ... placeholders.
+- Transactions use dedicated pool clients with `BEGIN`, `COMMIT`, `ROLLBACK` and guaranteed client release.
+
+### SQLite
+
+- Added built-in SQLite support through `better-sqlite3`.
+- Supports file paths, `:memory:`, `sqlite:` and `file:` database locations.
+- Common `.sqlite`, `.sqlite3` and `.db` `DATABASE_URL` values infer SQLite automatically.
+- File-backed databases create missing parent directories before opening the native database.
+- Adapter operations are serialized so async transaction callbacks do not interleave unrelated operations on one SQLite connection.
+
+### Connection lifecycle
+
+- Added explicit `database.connect()`.
+- Added explicit `database.disconnect()`.
+- Existing `database.close()` remains backward compatible and aliases the disconnect lifecycle.
+- Disconnecting resets the facade so a later operation can initialize a fresh provider connection.
+- Failed adapter initialization resets cleanly and can be retried.
+- `close()` is safe after failed adapter initialization.
+
+### Migration consistency
+
+The existing CLI remains unchanged:
+
+```bash
+bcp db create create_users
+bcp db migrate
+bcp db status
+bcp db rollback
+```
+
+Migration bookkeeping now selects its internal SQL dialect from the active database provider:
+
+- MySQL uses `AUTO_INCREMENT` and `?` placeholders.
+- PostgreSQL uses `BIGSERIAL` and `$1`, `$2` placeholders.
+- SQLite uses `INTEGER PRIMARY KEY AUTOINCREMENT` and `?` placeholders.
+
+BCP only makes the internal `_bcp_migrations` bookkeeping provider-aware. Application migration SQL is intentionally not translated between SQL dialects.
+
+### Packaging and validation
+
+- Added Database Platform v2 package smoke coverage.
+- Packed framework validation checks provider modules, bundled optional-driver references, lifecycle APIs and migration dialect support.
+- Added unit coverage for SQLite option resolution, provider inference, lifecycle reconnect behavior, failed adapter initialization and migration dialects.
+
+## Compatibility
+
+`0.2.3` does not intentionally remove public application entrypoints from the `0.2.2` baseline.
+
+Existing MySQL applications can continue using:
+
+```ts
+import {
+    db,
+    createDatabase,
+} from "bcp/database";
+```
+
+without changing their application-facing database calls.

package/package.json

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

package/packages/cli/src/configuration.ts

@@ -0,0 +1,235 @@
+import {
+    loadEnvironment,
+} from "../../env/src/index.js";
+import {
+    type ResolveBcpConfigOverrides,
+} from "../../config/src/index.js";
+import {
+    loadBcpEnvironmentSchema,
+} from "../../config/src/environment-loader.js";
+import {
+    applyEnvironmentDefaults,
+} from "../../config/src/environment-schema.js";
+import {
+    assertConfigurationDiagnostics,
+    diagnoseBcpConfiguration,
+    type BcpConfigurationDiagnosticsReport,
+} from "../../config/src/diagnostics.js";
+
+export interface RunConfigurationCheckOptions {
+    rootDirectory: string;
+    mode?: "development" | "production" | "test";
+    json?: boolean;
+}
+
+export async function runConfigurationCheck(
+    options: RunConfigurationCheckOptions
+): Promise<BcpConfigurationDiagnosticsReport> {
+    const mode =
+        options.mode ??
+        resolveCheckMode();
+    const loadedEnvironment =
+        loadEnvironment(
+            options.rootDirectory,
+            mode
+        );
+    const schema =
+        await loadBcpEnvironmentSchema(
+            options.rootDirectory
+        );
+    const appliedDefaults =
+        applyEnvironmentDefaults(
+            schema.schema,
+            process.env
+        );
+    const report =
+        await diagnoseBcpConfiguration({
+            rootDirectory:
+                options.rootDirectory,
+            mode,
+            environment:
+                process.env,
+        });
+
+    if (
+        options.json
+    ) {
+        console.log(
+            JSON.stringify(
+                {
+                    ...report,
+                    environmentFiles:
+                        loadedEnvironment.files,
+                    appliedDefaults,
+                },
+                null,
+                2
+            )
+        );
+
+        if (
+            !report.ok
+        ) {
+            process.exitCode =
+                1;
+
+            return report;
+        }
+    } else {
+        printConfigurationReport(
+            report,
+            loadedEnvironment.files,
+            appliedDefaults
+        );
+    }
+
+    assertConfigurationDiagnostics(
+        report
+    );
+
+    return report;
+}
+
+export async function runStartupConfigurationDiagnostics(
+    rootDirectory: string,
+    mode: "development" | "production",
+    overrides: ResolveBcpConfigOverrides = {}
+): Promise<BcpConfigurationDiagnosticsReport> {
+    const schema =
+        await loadBcpEnvironmentSchema(
+            rootDirectory
+        );
+    const appliedDefaults =
+        applyEnvironmentDefaults(
+            schema.schema,
+            process.env
+        );
+    const report =
+        await diagnoseBcpConfiguration({
+            rootDirectory,
+            mode,
+            environment:
+                process.env,
+            overrides,
+        });
+
+    if (
+        report.environmentSchemaFile
+    ) {
+        console.log(
+            `[BCP Config] Environment schema: ${report.environmentSchemaFile} (${report.environment.checked} variable(s), ${appliedDefaults} default(s) applied)`
+        );
+    }
+
+    for (
+        const diagnostic
+        of report.diagnostics
+    ) {
+        if (
+            diagnostic.severity ===
+            "warning"
+        ) {
+            console.warn(
+                `[BCP Config] Warning: ${diagnostic.message}`
+            );
+        }
+    }
+
+    assertConfigurationDiagnostics(
+        report
+    );
+
+    return report;
+}
+
+function printConfigurationReport(
+    report: BcpConfigurationDiagnosticsReport,
+    environmentFiles: string[],
+    appliedDefaults: number
+): void {
+    const errors =
+        report.diagnostics.filter(
+            (diagnostic) =>
+                diagnostic.severity ===
+                "error"
+        );
+    const warnings =
+        report.diagnostics.filter(
+            (diagnostic) =>
+                diagnostic.severity ===
+                "warning"
+        );
+
+    console.log("");
+    console.log(
+        `BCP Configuration Check (${report.mode})`
+    );
+    console.log("");
+    console.log(
+        `  Config: ${report.configFile ?? "defaults"}`
+    );
+    console.log(
+        `  Environment files: ${environmentFiles.length > 0 ? environmentFiles.join(", ") : "(none)"}`
+    );
+    console.log(
+        `  Environment schema: ${report.environmentSchemaFile ?? "(none)"}`
+    );
+    console.log(
+        `  Variables: ${report.environment.present}/${report.environment.checked} provided | ${appliedDefaults} default(s) applied`
+    );
+    console.log(
+        `  Server: ${report.resolvedConfig.server.hostname}:${report.resolvedConfig.server.port}`
+    );
+    console.log(
+        `  Build: minify=${report.resolvedConfig.build.minify} sourceMaps=${report.resolvedConfig.build.sourceMaps}`
+    );
+    console.log(
+        `  Diagnostics: ${errors.length} error(s), ${warnings.length} warning(s)`
+    );
+
+    if (
+        report.diagnostics.length >
+        0
+    ) {
+        console.log("");
+
+        for (
+            const diagnostic
+            of report.diagnostics
+        ) {
+            console.log(
+                `  ${diagnostic.severity === "error" ? "✖" : "⚠"} ${diagnostic.message}`
+            );
+        }
+    }
+
+    if (
+        report.ok
+    ) {
+        console.log("");
+        console.log(
+            "[BCP Config] Configuration check passed."
+        );
+    }
+
+    console.log("");
+}
+
+function resolveCheckMode():
+    "development" | "production" | "test" {
+    if (
+        process.env.NODE_ENV ===
+        "production"
+    ) {
+        return "production";
+    }
+
+    if (
+        process.env.NODE_ENV ===
+        "test"
+    ) {
+        return "test";
+    }
+
+    return "development";
+}