@chidchanun/bcp 0.2.0 → 0.2.2

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";
+}

package/packages/cli/src/index.ts

@@ -76,6 +76,11 @@ switch (cliOptions.command) {
     break;
   }
 
+  case "config": {
+    await runConfigCommand();
+    break;
+  }
+
   case "doctor": {
     await runDeveloperCommand(
       "doctor"
@@ -112,6 +117,24 @@ async function runDev() {
       cliOptions.rootDirectory
     );
 
+  const {
+    runStartupConfigurationDiagnostics,
+  } =
+    await import(
+      "./configuration.js"
+    );
+
+  await runStartupConfigurationDiagnostics(
+    rootDirectory,
+    "development",
+    {
+      port:
+        cliOptions.port,
+      hostname:
+        cliOptions.hostname,
+    }
+  );
+
   installApplicationModuleAlias(
     rootDirectory
   );
@@ -185,6 +208,24 @@ async function runBuild() {
       cliOptions.rootDirectory
     );
 
+  const {
+    runStartupConfigurationDiagnostics,
+  } =
+    await import(
+      "./configuration.js"
+    );
+
+  await runStartupConfigurationDiagnostics(
+    rootDirectory,
+    "production",
+    {
+      port:
+        cliOptions.port,
+      hostname:
+        cliOptions.hostname,
+    }
+  );
+
   const appDirectory =
     path.join(
       rootDirectory,
@@ -518,6 +559,36 @@ async function runGenerateCommand(): Promise<void> {
   });
 }
 
+async function runConfigCommand(): Promise<void> {
+  const action =
+    cliOptions.configAction;
+
+  if (
+    action === undefined ||
+    action === "help"
+  ) {
+    printConfigHelp();
+    return;
+  }
+
+  const rootDirectory =
+    resolveProjectRoot(
+      cliOptions.rootDirectory
+    );
+  const {
+    runConfigurationCheck,
+  } =
+    await import(
+      "./configuration.js"
+    );
+
+  await runConfigurationCheck({
+    rootDirectory,
+    json:
+      cliOptions.json,
+  });
+}
+
 async function runDeveloperCommand(
   command:
     "doctor" |
@@ -759,6 +830,32 @@ Examples:
 `);
 }
 
+function printConfigHelp() {
+  console.log(`
+BCP Configuration & Environment
+
+Usage:
+  bcp config <command> [options]
+
+Commands:
+  check               Validate bcp.config.*, bcp.environment.* and loaded environment values
+  help                Show configuration command help
+
+Options:
+  --root <path>        Project root directory
+  --json               Emit the configuration diagnostics report as JSON
+
+Environment mode:
+  NODE_ENV=production bcp config check
+  NODE_ENV=test bcp config check
+  bcp config check     (development by default)
+
+Examples:
+  bcp config check
+  bcp config check --json
+`);
+}
+
 function printHelp() {
   console.log(`
 BCP Framework v${FRAMEWORK_VERSION}
@@ -774,6 +871,7 @@ Commands:
   update [target]    Update BCP Framework (default target: latest)
   db <command>       Manage database migrations
   generate <kind>    Generate pages, API routes, middleware or migrations
+  config <command>   Validate project configuration and environment schema
   doctor             Run project/runtime health diagnostics
   inspect            Print resolved env, config, dependencies and routes
   help               Show this help message
@@ -786,7 +884,7 @@ Options:
   --host <host>         Alias for --hostname
   --check               Check for a BCP update without changing files
   --dry-run             Preview a BCP update without changing files
-  --json                JSON output for doctor/inspect
+  --json                JSON output for doctor/inspect/config
   --force               Replace existing generated scaffold files
   -h, --help            Show help
   -v, --version         Show version
@@ -803,6 +901,8 @@ Examples:
   bcp generate page dashboard/users
   bcp generate api users
   bcp generate middleware
+  bcp config check
+  bcp config check --json
   bcp doctor
   bcp doctor --json
   bcp inspect

package/packages/client/src/config.ts

@@ -16,3 +16,29 @@ export {
     type ResolveBcpConfigOverrides,
     type ResolvedBcpConfig,
 } from "../../config/src/index.js";
+
+export {
+    applyEnvironmentDefaults,
+    defineEnvironment,
+    validateEnvironment,
+    type BcpEnvironmentSchema,
+    type BcpEnvironmentValidationIssue,
+    type BcpEnvironmentValidationResult,
+    type BcpEnvironmentValueType,
+    type BcpEnvironmentVariableRule,
+} from "../../config/src/environment-schema.js";
+
+export {
+    getEnvironmentSchemaFileNames,
+    loadBcpEnvironmentSchema,
+    type LoadedBcpEnvironmentSchema,
+} from "../../config/src/environment-loader.js";
+
+export {
+    assertConfigurationDiagnostics,
+    diagnoseBcpConfiguration,
+    type BcpConfigurationDiagnostic,
+    type BcpConfigurationDiagnosticSeverity,
+    type BcpConfigurationDiagnosticsReport,
+    type DiagnoseBcpConfigurationOptions,
+} from "../../config/src/diagnostics.js";

package/packages/config/src/diagnostics.ts

@@ -0,0 +1,226 @@
+import path from "node:path";
+
+import {
+    resolveBcpConfig,
+    type ResolveBcpConfigOverrides,
+    type ResolvedBcpConfig,
+} from "./index.js";
+import {
+    loadBcpEnvironmentSchema,
+} from "./environment-loader.js";
+import {
+    validateEnvironment,
+    type BcpEnvironmentValidationResult,
+} from "./environment-schema.js";
+
+export type BcpConfigurationDiagnosticSeverity =
+    | "error"
+    | "warning";
+
+export interface BcpConfigurationDiagnostic {
+    severity: BcpConfigurationDiagnosticSeverity;
+    code: string;
+    message: string;
+}
+
+export interface BcpConfigurationDiagnosticsReport {
+    ok: boolean;
+    mode: string;
+    configFile: string | null;
+    environmentSchemaFile: string | null;
+    resolvedConfig: ResolvedBcpConfig;
+    environment: {
+        checked: number;
+        present: number;
+        defaults: number;
+    };
+    diagnostics: BcpConfigurationDiagnostic[];
+}
+
+export interface DiagnoseBcpConfigurationOptions {
+    rootDirectory: string;
+    mode: string;
+    environment?: NodeJS.ProcessEnv;
+    overrides?: ResolveBcpConfigOverrides;
+}
+
+export async function diagnoseBcpConfiguration(
+    options: DiagnoseBcpConfigurationOptions
+): Promise<BcpConfigurationDiagnosticsReport> {
+    const environment =
+        options.environment ??
+        process.env;
+    const resolved =
+        await resolveBcpConfig(
+            options.rootDirectory,
+            options.overrides ?? {},
+            environment
+        );
+    const loadedSchema =
+        await loadBcpEnvironmentSchema(
+            options.rootDirectory
+        );
+    const environmentValidation =
+        validateEnvironment(
+            loadedSchema.schema,
+            environment
+        );
+    const diagnostics:
+        BcpConfigurationDiagnostic[] = [];
+
+    appendEnvironmentDiagnostics(
+        diagnostics,
+        environmentValidation
+    );
+    appendRuntimeDiagnostics(
+        diagnostics,
+        options.mode,
+        resolved.config,
+        environment
+    );
+
+    return {
+        ok:
+            !diagnostics.some(
+                (diagnostic) =>
+                    diagnostic.severity ===
+                    "error"
+            ),
+        mode:
+            options.mode,
+        configFile:
+            resolved.file
+                ? path.basename(
+                    resolved.file
+                )
+                : null,
+        environmentSchemaFile:
+            loadedSchema.file
+                ? path.basename(
+                    loadedSchema.file
+                )
+                : null,
+        resolvedConfig:
+            resolved.config,
+        environment: {
+            checked:
+                environmentValidation.checked,
+            present:
+                environmentValidation.present,
+            defaults:
+                environmentValidation.defaults,
+        },
+        diagnostics,
+    };
+}
+
+export function assertConfigurationDiagnostics(
+    report: BcpConfigurationDiagnosticsReport
+): void {
+    if (
+        report.ok
+    ) {
+        return;
+    }
+
+    const errors =
+        report.diagnostics
+            .filter(
+                (diagnostic) =>
+                    diagnostic.severity ===
+                    "error"
+            )
+            .map(
+                (diagnostic) =>
+                    diagnostic.message
+            );
+
+    throw new Error(
+        `BCP Configuration Error:\n${errors.map((message) => `- ${message}`).join("\n")}`
+    );
+}
+
+function appendEnvironmentDiagnostics(
+    diagnostics: BcpConfigurationDiagnostic[],
+    validation: BcpEnvironmentValidationResult
+): void {
+    for (
+        const issue
+        of validation.issues
+    ) {
+        diagnostics.push({
+            severity:
+                issue.severity,
+            code:
+                `environment.${issue.code}`,
+            message:
+                issue.message,
+        });
+    }
+}
+
+function appendRuntimeDiagnostics(
+    diagnostics: BcpConfigurationDiagnostic[],
+    mode: string,
+    config: ResolvedBcpConfig,
+    environment: NodeJS.ProcessEnv
+): void {
+    if (
+        mode !== "production"
+    ) {
+        return;
+    }
+
+    if (
+        config.build.sourceMaps
+    ) {
+        diagnostics.push({
+            severity: "warning",
+            code: "production.source_maps",
+            message:
+                "Production source maps are enabled. Confirm that exposing source information is intentional.",
+        });
+    }
+
+    if (
+        config.security.poweredByHeader
+    ) {
+        diagnostics.push({
+            severity: "warning",
+            code: "production.powered_by",
+            message:
+                "security.poweredByHeader is enabled in production.",
+        });
+    }
+
+    if (
+        config.security.contentSecurityPolicy ===
+        false
+    ) {
+        diagnostics.push({
+            severity: "warning",
+            code: "production.csp_disabled",
+            message:
+                "Content-Security-Policy is disabled. Configure a policy when the application can support one.",
+        });
+    }
+
+    const trustProxy =
+        environment.BCP_TRUST_PROXY
+            ?.trim()
+            .toLowerCase();
+
+    if (
+        trustProxy === "true" ||
+        trustProxy === "1" ||
+        trustProxy === "yes" ||
+        trustProxy === "on"
+    ) {
+        diagnostics.push({
+            severity: "warning",
+            code: "production.trust_proxy",
+            message:
+                "BCP_TRUST_PROXY is enabled. Ensure untrusted clients cannot bypass the trusted reverse proxy/load balancer.",
+        });
+    }
+}