@beignet/cli 0.0.31 → 0.0.32

package/src/preflight.ts

@@ -0,0 +1,596 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { parseProviderPackageMetadata } from "@beignet/core/providers";
+import { createJiti } from "jiti";
+import {
+  type InspectDiagnostic,
+  inspectApp,
+  productionHardeningDiagnosticCodes,
+} from "./inspect.js";
+import {
+  installedPackageNames,
+  type ProviderPackageJson,
+  providerDoctorRulesForInstalledPackages,
+  readProviderPackageMetadataSource,
+} from "./provider-audit.js";
+
+/**
+ * One preflight finding. Errors fail the gate; warnings and notes do not.
+ */
+export interface PreflightFinding {
+  severity: "error" | "warning" | "note";
+  code: string;
+  message: string;
+}
+
+export interface PreflightOptions {
+  cwd: string;
+  /**
+   * Environment to validate. Defaults to `process.env` so the command checks
+   * the environment the deploy pipeline actually runs with.
+   */
+  env?: Record<string, string | undefined>;
+  /**
+   * Optional dotenv-style file merged under the environment (existing env
+   * keys win) for local rehearsal of a deploy environment.
+   */
+  envFile?: string;
+  /**
+   * App env module validated by importing it (default `lib/env.ts`). The
+   * module's `createEnv(...)` call performs the validation.
+   */
+  envModule?: string;
+  /**
+   * Fold doctor's production hardening diagnostics into the gate. Defaults
+   * to `true`.
+   */
+  doctor?: boolean;
+  /**
+   * Boot the app server and run every port's `checkHealth()`. Needs network
+   * access and real credentials, so it is opt-in.
+   */
+  connect?: boolean;
+  /**
+   * Module exporting `getServer` (or `server`), used by `connect`. Defaults
+   * to `server/index.ts`.
+   */
+  serverModule?: string;
+  /**
+   * Per-dependency health check timeout in milliseconds. Defaults to 5000.
+   */
+  connectTimeoutMs?: number;
+}
+
+export interface PreflightResult {
+  findings: PreflightFinding[];
+  /**
+   * Provider packages whose manifests were checked.
+   */
+  checkedProviders: string[];
+  /**
+   * Whether the app env module was found and imported.
+   */
+  envModuleChecked: boolean;
+  /**
+   * Whether doctor's production hardening diagnostics were folded in.
+   */
+  doctorChecked: boolean;
+  /**
+   * Ports whose `checkHealth()` ran during a `connect` pass.
+   */
+  checkedDependencies: string[];
+}
+
+/**
+ * Map doctor diagnostics to preflight findings: only production hardening
+ * codes are kept, and their severities are promoted for the deploy gate —
+ * doctor errors and warnings both fail preflight; hints become warnings.
+ */
+export function productionFindingsFromDiagnostics(
+  diagnostics: readonly InspectDiagnostic[],
+): PreflightFinding[] {
+  return diagnostics
+    .filter((diagnostic) =>
+      productionHardeningDiagnosticCodes.has(diagnostic.code),
+    )
+    .map((diagnostic) => ({
+      severity: diagnostic.severity === "hint" ? "warning" : "error",
+      code: diagnostic.code,
+      message: diagnostic.message,
+    }));
+}
+
+const SECRET_KEY_PATTERN = /SECRET|TOKEN|KEY|PASS|PASSWORD|DSN/i;
+
+const PLACEHOLDER_VALUE_PATTERN =
+  /^(changeme|change-me|todo|placeholder|xxx+)$|replace-with|replace-me|dev-placeholder|your-[a-z]/i;
+
+/**
+ * Parse a dotenv-style file: KEY=VALUE lines, `#` comments, optional single
+ * or double quotes around the value.
+ */
+export function parseEnvFile(source: string): Record<string, string> {
+  const values: Record<string, string> = {};
+  for (const rawLine of source.split("\n")) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq <= 0) continue;
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    values[key] = value;
+  }
+  return values;
+}
+
+async function readFileIfExists(filePath: string): Promise<string | undefined> {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+async function readPackageJson(
+  cwd: string,
+): Promise<ProviderPackageJson | undefined> {
+  const source = await readFileIfExists(path.join(cwd, "package.json"));
+  if (!source) return undefined;
+  try {
+    return JSON.parse(source) as ProviderPackageJson;
+  } catch {
+    return undefined;
+  }
+}
+
+function isSecretish(key: string): boolean {
+  return SECRET_KEY_PATTERN.test(key);
+}
+
+function applyEnvToProcess(
+  env: Record<string, string | undefined>,
+): () => void {
+  const previousValues = new Map<string, string | undefined>();
+
+  for (const [key, value] of Object.entries(env)) {
+    if (value === undefined) continue;
+    previousValues.set(key, process.env[key]);
+    process.env[key] = value;
+  }
+
+  return () => {
+    for (const [key, value] of previousValues) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  };
+}
+
+/**
+ * Validate the deploy environment against installed provider manifests, the
+ * app's `.env.example` placeholders, and the app env schema module.
+ *
+ * This is a runtime gate, unlike `beignet doctor`: it reads the actual
+ * environment the process runs with, so run it in the deploy pipeline where
+ * production configuration is present.
+ */
+export async function runPreflight(
+  options: PreflightOptions,
+): Promise<PreflightResult> {
+  const findings: PreflightFinding[] = [];
+  const env: Record<string, string | undefined> = {
+    ...(options.env ?? process.env),
+  };
+
+  if (options.envFile) {
+    const source = await readFileIfExists(
+      path.resolve(options.cwd, options.envFile),
+    );
+    if (source === undefined) {
+      findings.push({
+        severity: "error",
+        code: "BEIGNET_PREFLIGHT_ENV_FILE_MISSING",
+        message: `Env file "${options.envFile}" does not exist.`,
+      });
+    } else {
+      for (const [key, value] of Object.entries(parseEnvFile(source))) {
+        if (env[key] === undefined) env[key] = value;
+      }
+    }
+  }
+
+  const packageJson = await readPackageJson(options.cwd);
+  if (!packageJson) {
+    findings.push({
+      severity: "error",
+      code: "BEIGNET_PREFLIGHT_PACKAGE_JSON_MISSING",
+      message: `No package.json found in ${options.cwd}.`,
+    });
+    return {
+      findings,
+      checkedProviders: [],
+      envModuleChecked: false,
+      doctorChecked: false,
+      checkedDependencies: [],
+    };
+  }
+
+  const rules = await providerDoctorRulesForInstalledPackages(
+    options.cwd,
+    packageJson,
+  );
+  const checkedProviders = rules.map((rule) => rule.packageName);
+  const requiredEnvKeys = new Set<string>();
+
+  for (const rule of rules) {
+    for (const key of rule.requiredEnv ?? []) {
+      requiredEnvKeys.add(key);
+      const value = env[key];
+      if (value === undefined || value.trim() === "") {
+        findings.push({
+          severity: "error",
+          code: "BEIGNET_PREFLIGHT_ENV_MISSING",
+          message: `${key} is required by ${rule.packageName} but is not set.`,
+        });
+      }
+    }
+  }
+
+  const exampleSource = await readFileIfExists(
+    path.join(options.cwd, ".env.example"),
+  );
+  const exampleValues = exampleSource ? parseEnvFile(exampleSource) : {};
+
+  for (const [key, value] of Object.entries(env)) {
+    if (value === undefined || value === "") continue;
+    const guarded = requiredEnvKeys.has(key) || isSecretish(key);
+    if (!guarded) continue;
+
+    if (
+      Object.hasOwn(exampleValues, key) &&
+      exampleValues[key] !== "" &&
+      exampleValues[key] === value
+    ) {
+      findings.push({
+        severity: "error",
+        code: "BEIGNET_PREFLIGHT_ENV_PLACEHOLDER",
+        message: `${key} still has its .env.example value. Set a real value in the deploy environment.`,
+      });
+      continue;
+    }
+
+    if (PLACEHOLDER_VALUE_PATTERN.test(value)) {
+      findings.push({
+        severity: "error",
+        code: "BEIGNET_PREFLIGHT_ENV_PLACEHOLDER",
+        message: `${key} looks like a placeholder value ("${value}"). Set a real value in the deploy environment.`,
+      });
+    }
+  }
+
+  await checkObservabilityWiring(options.cwd, packageJson, env, findings);
+
+  findings.push({
+    severity: "note",
+    code: "BEIGNET_PREFLIGHT_MANUAL_REVIEW",
+    message:
+      "Manual review (no framework primitives yet): CSRF protection, secure headers, and tracing export — see the deployment docs hardening checklist.",
+  });
+
+  let envModuleChecked = false;
+  let doctorChecked = false;
+  const checkedDependencies: string[] = [];
+  const restoreProcessEnv = applyEnvToProcess(env);
+
+  try {
+    const envModule = options.envModule ?? "lib/env.ts";
+    const envModulePath = path.resolve(options.cwd, envModule);
+    const envModuleSource = await readFileIfExists(envModulePath);
+
+    if (envModuleSource === undefined) {
+      findings.push({
+        severity: "note",
+        code: "BEIGNET_PREFLIGHT_ENV_MODULE_MISSING",
+        message: `No app env module at ${envModule}; skipping app env schema validation.`,
+      });
+    } else {
+      try {
+        const jiti = createJiti(envModulePath, {
+          interopDefault: true,
+          moduleCache: false,
+        });
+        await jiti.import(envModulePath);
+        envModuleChecked = true;
+      } catch (error) {
+        findings.push({
+          severity: "error",
+          code: "BEIGNET_PREFLIGHT_APP_ENV_INVALID",
+          message: `App env schema validation failed (${envModule}): ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        });
+      }
+    }
+
+    if (options.doctor !== false) {
+      const inspected = await inspectApp({ cwd: options.cwd });
+      findings.push(
+        ...productionFindingsFromDiagnostics(inspected.diagnostics),
+      );
+      doctorChecked = true;
+    }
+
+    if (options.connect) {
+      await runDependencyChecks(options, findings, checkedDependencies);
+    }
+  } finally {
+    restoreProcessEnv();
+  }
+
+  return {
+    findings,
+    checkedProviders,
+    envModuleChecked,
+    doctorChecked,
+    checkedDependencies,
+  };
+}
+
+interface HealthCheckable {
+  checkHealth(): Promise<unknown>;
+}
+
+function isHealthCheckable(value: unknown): value is HealthCheckable {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as HealthCheckable).checkHealth === "function"
+  );
+}
+
+function healthResultOk(result: unknown): boolean {
+  if (typeof result !== "object" || result === null) return true;
+  const ok = (result as { ok?: unknown }).ok;
+  return ok === undefined || ok === true;
+}
+
+async function withTimeout<T>(
+  work: Promise<T>,
+  ms: number,
+  label: string,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      work,
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`${label} timed out after ${ms}ms`)),
+          ms,
+        );
+      }),
+    ]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+/**
+ * Boot the app server through the same jiti loading the operational commands
+ * use, then run `checkHealth()` on every port that exposes one.
+ */
+async function runDependencyChecks(
+  options: PreflightOptions,
+  findings: PreflightFinding[],
+  checkedDependencies: string[],
+): Promise<void> {
+  const serverModule = options.serverModule ?? "server/index.ts";
+  const serverModulePath = path.resolve(options.cwd, serverModule);
+  const timeoutMs = options.connectTimeoutMs ?? 5000;
+
+  if ((await readFileIfExists(serverModulePath)) === undefined) {
+    findings.push({
+      severity: "error",
+      code: "BEIGNET_PREFLIGHT_SERVER_MODULE_MISSING",
+      message: `--connect needs a server module at ${serverModule} (override with --server-module).`,
+    });
+    return;
+  }
+
+  let server:
+    | { ports: Record<string, unknown>; stop?: () => Promise<void> }
+    | undefined;
+  try {
+    const jiti = createJiti(serverModulePath, {
+      interopDefault: true,
+      moduleCache: false,
+    });
+    const loaded = (await jiti.import(serverModulePath)) as Record<
+      string,
+      unknown
+    >;
+    const candidate = loaded.getServer ?? loaded.server;
+    const resolved =
+      typeof candidate === "function" ? await candidate() : await candidate;
+    if (
+      typeof resolved !== "object" ||
+      resolved === null ||
+      typeof (resolved as { ports?: unknown }).ports !== "object"
+    ) {
+      findings.push({
+        severity: "error",
+        code: "BEIGNET_PREFLIGHT_SERVER_EXPORT_MISSING",
+        message: `${serverModule} must export getServer (or server) resolving to a server with ports.`,
+      });
+      return;
+    }
+    server = resolved as {
+      ports: Record<string, unknown>;
+      stop?: () => Promise<void>;
+    };
+  } catch (error) {
+    findings.push({
+      severity: "error",
+      code: "BEIGNET_PREFLIGHT_SERVER_BOOT_FAILED",
+      message: `Booting the app server failed: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    });
+    return;
+  }
+
+  try {
+    for (const [name, port] of Object.entries(server.ports)) {
+      if (!isHealthCheckable(port)) continue;
+      checkedDependencies.push(name);
+      try {
+        const result = await withTimeout(
+          port.checkHealth(),
+          timeoutMs,
+          `${name}.checkHealth()`,
+        );
+        if (!healthResultOk(result)) {
+          const message = (result as { message?: unknown }).message;
+          findings.push({
+            severity: "error",
+            code: "BEIGNET_PREFLIGHT_DEPENDENCY_UNHEALTHY",
+            message: `${name} reported unhealthy${
+              typeof message === "string" ? `: ${message}` : "."
+            }`,
+          });
+        }
+      } catch (error) {
+        findings.push({
+          severity: "error",
+          code: "BEIGNET_PREFLIGHT_DEPENDENCY_UNHEALTHY",
+          message: `${name} health check failed: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        });
+      }
+    }
+  } finally {
+    try {
+      await server.stop?.();
+    } catch {
+      // Shutdown failures do not change readiness results.
+    }
+  }
+}
+
+/**
+ * Format a preflight result for terminal output.
+ */
+export function formatPreflight(result: PreflightResult, cwd: string): string {
+  const lines: string[] = [];
+  const errors = result.findings.filter((f) => f.severity === "error");
+  const warnings = result.findings.filter((f) => f.severity === "warning");
+  const notes = result.findings.filter((f) => f.severity === "note");
+
+  for (const finding of [...errors, ...warnings, ...notes]) {
+    const tag =
+      finding.severity === "error"
+        ? "error"
+        : finding.severity === "warning"
+          ? "warning"
+          : "note";
+    lines.push(`${tag} ${finding.code}: ${finding.message}`);
+  }
+
+  if (lines.length > 0) lines.push("");
+
+  const providerSummary = result.checkedProviders.length
+    ? `${result.checkedProviders.length} provider manifest(s)`
+    : "no provider manifests";
+  const envSummary = result.envModuleChecked
+    ? "app env schema validated"
+    : "app env schema not validated";
+  const doctorSummary = result.doctorChecked
+    ? "production hardening checks folded in"
+    : "production hardening checks skipped";
+  const dependencySummary = result.checkedDependencies.length
+    ? `, ${result.checkedDependencies.length} dependency health check(s) run`
+    : "";
+
+  if (errors.length === 0) {
+    lines.push(
+      `Preflight passed in ${cwd}: ${providerSummary} checked, ${envSummary}, ${doctorSummary}${dependencySummary}.`,
+    );
+  } else {
+    lines.push(
+      `Preflight failed in ${cwd}: ${errors.length} error(s) across ${providerSummary}, ${envSummary}, ${doctorSummary}${dependencySummary}.`,
+    );
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+const DSN_KEY_PATTERN = /DSN/i;
+
+/**
+ * Warn when logging or error reporting is absent or inert: no installed
+ * provider contributes a `logger` or `errorReporter` port, or an error
+ * reporting provider is installed but its DSN-style env var is unset.
+ */
+async function checkObservabilityWiring(
+  cwd: string,
+  packageJson: ProviderPackageJson,
+  env: Record<string, string | undefined>,
+  findings: PreflightFinding[],
+): Promise<void> {
+  let hasLogger = false;
+  let hasErrorReporter = false;
+
+  for (const packageName of installedPackageNames(packageJson)) {
+    const source = await readProviderPackageMetadataSource(cwd, packageName);
+    if (!source) continue;
+    const parsed = parseProviderPackageMetadata(source.metadata);
+    if (!parsed.success) continue;
+    const ports = parsed.metadata.ports ?? [];
+
+    if (ports.includes("logger")) hasLogger = true;
+    if (ports.includes("errorReporter")) {
+      hasErrorReporter = true;
+      const dsnKeys = (parsed.metadata.env ?? []).filter((key) =>
+        DSN_KEY_PATTERN.test(key),
+      );
+      for (const key of dsnKeys) {
+        const value = env[key];
+        if (value === undefined || value.trim() === "") {
+          findings.push({
+            severity: "warning",
+            code: "BEIGNET_PREFLIGHT_ERROR_REPORTING_INERT",
+            message: `${packageName} is installed but ${key} is not set, so error reporting will be inert.`,
+          });
+        }
+      }
+    }
+  }
+
+  if (!hasLogger) {
+    findings.push({
+      severity: "warning",
+      code: "BEIGNET_PREFLIGHT_LOGGING_NOT_CONFIGURED",
+      message:
+        "No installed provider contributes a logger port; production logs need a real logger provider such as @beignet/provider-logger-pino.",
+    });
+  }
+
+  if (!hasErrorReporter) {
+    findings.push({
+      severity: "warning",
+      code: "BEIGNET_PREFLIGHT_ERROR_REPORTING_NOT_CONFIGURED",
+      message:
+        "No installed provider contributes an errorReporter port; production error capture needs a provider such as @beignet/provider-error-reporting-sentry.",
+    });
+  }
+}