import { readFileSync } from "node:fs"; import { resolve } from "node:path"; import { describe, expect, test } from "vitest"; import { getEnvVariableDefinition, getRequiredEnvVariableNames, groupEnvVariablesByClassification } from "./index.js"; const envVarsDocument = readFileSync(resolve(process.cwd(), "docs/env-vars.md"), "utf8"); describe("env catalog", () => { test("looks up dynamic SITE_KEY_* definitions without requiring a concrete catalog entry", () => { expect(getEnvVariableDefinition("SITE_KEY_BOOKING")?.dynamicPrefix).toBe("SITE_KEY_"); expect(getEnvVariableDefinition("SITE_KEY_COMMUNITY")?.name).toBe("SITE_KEY_*"); }); test("classifies worker Redis keys and opt-in toggle", () => { expect(getEnvVariableDefinition("WORKER_ENABLED")).toMatchObject({ classification: "optional-provider", targets: ["worker"], source: "code-and-example", defaultValue: "false", }); expect(getEnvVariableDefinition("BULLMQ_REDIS_URL")).toMatchObject({ classification: "optional-provider", targets: ["web", "api", "worker"], source: "code-and-example", }); expect(getEnvVariableDefinition("REDIS_URL")).toMatchObject({ classification: "optional-provider", targets: ["web", "api", "mcp", "worker"], source: "code", requiredInProductionTargets: ["web", "mcp"], }); expect(getEnvVariableDefinition("EMAIL_QUEUE_NAME")).toMatchObject({ classification: "optional-provider", targets: ["worker"], source: "code", defaultValue: "hivegrid.email", }); expect(getEnvVariableDefinition("WORKFLOW_QUEUE_NAME")).toMatchObject({ classification: "optional-provider", targets: ["worker"], source: "code", defaultValue: "hivegrid.workflows", }); expect(getEnvVariableDefinition("WORKER_QUEUE_GROUP")?.description).toContain("plugin"); expect(getEnvVariableDefinition("WORKER_CONCURRENCY_PLUGIN")).toMatchObject({ classification: "optional-provider", targets: ["worker"], source: "code-and-example", defaultValue: "5", }); expect(getEnvVariableDefinition("WORKER_REDIS_POOL_SIZE")?.notes).toContain("plugin=4"); }); test("keeps active Crisp usage out of deprecated-only classification", () => { expect(getEnvVariableDefinition("CRISP_CHAT_WEBSITE_ID")).toMatchObject({ classification: "optional-provider", targets: ["web"], source: "code-and-example", }); }); test("catalogs active operational runtime toggles", () => { for (const key of ["WEB_RUNTIME_SURFACE", "PORTAL_SESSION_SECRET"]) { expect(getEnvVariableDefinition(key)).toMatchObject({ classification: "production-only", targets: ["web"], source: "code-and-example", }); } expect(getEnvVariableDefinition("PORTAL_APP_HOST")).toMatchObject({ classification: "production-only", targets: ["web", "worker"], source: "code-and-example", }); expect(getEnvVariableDefinition("CRYPTO_SECRET")).toMatchObject({ classification: "required-per-app", targets: ["web", "api", "worker"], source: "code-and-example", }); expect(getEnvVariableDefinition("CRYPTO_SECRET")?.notes).toContain("worker-mail"); expect(getEnvVariableDefinition("HIVEGRID_API_MAINTENANCE_MODE")).toMatchObject({ classification: "production-only", targets: ["api"], source: "code", }); expect(getEnvVariableDefinition("WEB_BUILD_DIRECTORY")).toMatchObject({ classification: "production-only", targets: ["web"], source: "code", }); expect(getEnvVariableDefinition("SEED_DEMO_PRO_MANAGED")).toMatchObject({ classification: "production-only", targets: ["web"], source: "code", defaultValue: "false", }); expect(getEnvVariableDefinition("SEED_DEMO_USER_PASSWORD")).toMatchObject({ classification: "production-only", targets: ["shared"], kind: "secret", source: "code", }); }); test("groups required production keys without optional worker fallback keys", () => { expect(getRequiredEnvVariableNames({ target: "worker", nodeEnv: "production" })).toEqual( expect.arrayContaining(["APP_NAME", "DATABASE_URL"]) ); expect(getRequiredEnvVariableNames({ target: "worker", nodeEnv: "production" })).not.toEqual( expect.arrayContaining(["WORKER_ENABLED", "BULLMQ_REDIS_URL", "REDIS_URL", "SITE_KEY_*"]) ); expect(getRequiredEnvVariableNames({ target: "mcp", nodeEnv: "production" })).toContain("REDIS_URL"); expect(groupEnvVariablesByClassification()["optional-provider"].map((definition) => definition.name)).toEqual( expect.arrayContaining(["WORKER_ENABLED", "BULLMQ_REDIS_URL", "REDIS_URL", "CRISP_CHAT_WEBSITE_ID", "SITE_KEY_*"]) ); }); test("documents production-required and active provider keys in env-vars", () => { const requiredKeys = new Set([ ...getRequiredEnvVariableNames({ target: "web", nodeEnv: "production" }), ...getRequiredEnvVariableNames({ target: "api", nodeEnv: "production" }), ...getRequiredEnvVariableNames({ target: "worker", nodeEnv: "production" }), ]); for (const key of requiredKeys) { expect(envVarsDocument, `docs/env-vars.md missing required key ${key}`).toContain(`\`${key}\``); } for (const key of ["IMPORT_QUEUE_ENABLED", "IMPORT_QUEUE_RUNTIME_READY", "PORTAL_GDPR_EXPORT_QUEUE_ENABLED"]) { expect(envVarsDocument, `docs/env-vars.md missing active optional key ${key}`).toContain(`\`${key}\``); } }); test("targets provider keys consumed by web config to the web runtime", () => { for (const key of ["MAILJET_API_KEY", "MAILJET_SECRET_KEY", "MAILJET_FROM_EMAIL", "MAILJET_FROM_NAME"]) { expect(getEnvVariableDefinition(key)?.targets, `${key} must include web because loadWebConfig consumes it`).toContain("web"); } }); test("catalogs the Aircall Technology Partner OAuth boundary as web-only", () => { for (const key of ["AIRCALL_CLIENT_ID", "AIRCALL_CLIENT_SECRET", "AIRCALL_REDIRECT_URI", "AIRCALL_WEBHOOK_URL"]) { expect(getEnvVariableDefinition(key)).toMatchObject({ classification: "optional-provider", targets: ["web"], source: "code-and-example", }); } expect(getEnvVariableDefinition("AIRCALL_CLIENT_SECRET")?.kind).toBe("secret"); }); test("catalogs the KWP OAuth boundary and exposes only its tenant binding to the worker", () => { for (const key of ["KWP_OAUTH_CLIENT_ID", "KWP_OAUTH_CLIENT_SECRET", "KWP_OAUTH_SCOPES", "KWP_CUSTOMER_CODE", "KWP_OIDC_ISSUER", "KWP_MANDANT"]) { expect(getEnvVariableDefinition(key)).toMatchObject({ classification: "optional-provider", targets: ["web"], source: "code-and-example", }); expect(getEnvVariableDefinition(key)?.requiredInProduction, `${key} must remain optional in production`).not.toBe(true); } expect(getEnvVariableDefinition("KWP_HIVEGRID_TENANT_ID")).toMatchObject({ classification: "optional-provider", targets: ["web", "worker"], source: "code-and-example", }); expect(getEnvVariableDefinition("KWP_HIVEGRID_TENANT_ID")?.requiredInProduction).not.toBe(true); expect(getEnvVariableDefinition("KWP_OAUTH_CLIENT_SECRET")?.kind).toBe("secret"); expect(getEnvVariableDefinition("KWP_OIDC_ISSUER")?.kind).toBe("url"); expect(getEnvVariableDefinition("KWP_OAUTH_REDIRECT_URI")).toBeUndefined(); }); test("catalogs the Web Push VAPID boundary without making it core-required", () => { for (const key of ["WEB_PUSH_VAPID_SUBJECT", "WEB_PUSH_VAPID_PRIVATE_KEY"]) { expect(getEnvVariableDefinition(key)).toMatchObject({ classification: "optional-provider", targets: ["worker"], source: "code-and-example" }); expect(getEnvVariableDefinition(key)?.requiredInProduction).not.toBe(true); } expect(getEnvVariableDefinition("WEB_PUSH_VAPID_PUBLIC_KEY")).toMatchObject({ classification: "optional-provider", targets: ["web", "worker"], source: "code-and-example", requiredInProductionTargets: ["web"], }); expect(getEnvVariableDefinition("WEB_PUSH_VAPID_PUBLIC_KEY")?.requiredInProduction).not.toBe(true); expect(getEnvVariableDefinition("WEB_PUSH_VAPID_PRIVATE_KEY")?.kind).toBe("secret"); }); test("catalogs the Authentik JIT database boundary as a web-only secret", () => { expect(getEnvVariableDefinition("AUTHENTIK_ADMIN_JIT_DATABASE_URL")).toMatchObject({ classification: "optional-provider", targets: ["web"], kind: "secret", source: "code-and-example", }); }); });