feat(selfhost): add environment preflight

Author: oktofeesh1

src/selfhost/preflight.ts

@@ -0,0 +1,73 @@
+export type SelfHostPreflightProblem = {
+  var: string;
+  message: string;
+};
+
+export type SelfHostPreflightResult =
+  | { ok: true; problems: [] }
+  | { ok: false; problems: SelfHostPreflightProblem[] };
+
+type SelfHostPreflightEnv = Record<string, string | undefined>;
+
+function nonBlank(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function addProblem(
+  problems: SelfHostPreflightProblem[],
+  name: string,
+  message: string,
+): void {
+  problems.push({ var: name, message });
+}
+
+export function preflightEnv(env: SelfHostPreflightEnv): SelfHostPreflightResult {
+  const problems: SelfHostPreflightProblem[] = [];
+
+  if (!nonBlank(env.REDIS_URL))
+    addProblem(
+      problems,
+      "REDIS_URL",
+      "Set REDIS_URL to the Redis connection URL used for shared transient review state.",
+    );
+
+  const hasGitHubApp = Boolean(nonBlank(env.GITHUB_APP_ID));
+  const hasOrbBroker = Boolean(nonBlank(env.ORB_ENROLLMENT_SECRET));
+  if (!hasGitHubApp && !hasOrbBroker) {
+    if (!nonBlank(env.SELFHOST_SETUP_TOKEN))
+      addProblem(
+        problems,
+        "SELFHOST_SETUP_TOKEN",
+        "Set SELFHOST_SETUP_TOKEN before using the first-run setup wizard.",
+      );
+    if (!nonBlank(env.PUBLIC_API_ORIGIN))
+      addProblem(
+        problems,
+        "PUBLIC_API_ORIGIN",
+        "Set PUBLIC_API_ORIGIN to the public HTTPS origin that receives GitHub App setup callbacks.",
+      );
+  }
+
+  const databaseUrl = nonBlank(env.DATABASE_URL);
+  if (databaseUrl && !/^postgres(?:ql)?:\/\//i.test(databaseUrl))
+    addProblem(
+      problems,
+      "DATABASE_URL",
+      "Set DATABASE_URL to a postgres:// URL, or leave it unset to use the SQLite backend.",
+    );
+
+  return problems.length === 0 ? { ok: true, problems: [] } : { ok: false, problems };
+}
+
+export function formatSelfHostPreflightError(problems: SelfHostPreflightProblem[]): string {
+  return [
+    "Self-host environment preflight failed:",
+    ...problems.map((problem) => `- ${problem.var}: ${problem.message}`),
+  ].join("\n");
+}
+
+export function assertSelfHostPreflight(env: SelfHostPreflightEnv): void {
+  const result = preflightEnv(env);
+  if (!result.ok) throw new Error(formatSelfHostPreflightError(result.problems));
+}

src/server.ts

@@ -55,6 +55,7 @@ import {
   makeLocalManifestReader,
   makeLocalReviewContextReader,
 } from "./selfhost/private-config";
+import { assertSelfHostPreflight } from "./selfhost/preflight";
 import {
   buildSentryOpenTelemetryBridge,
   captureError,
@@ -256,6 +257,8 @@ function buildSqliteBackend(
 
 async function main(): Promise<void> {
   loadFileSecrets();
+  /* v8 ignore next -- importing this entrypoint starts the Node server; pure validation is covered in selfhost-preflight tests. */
+  assertSelfHostPreflight(process.env);
   // Container-private per-repo config (self-host): register the GITTENSORY_REPO_CONFIG_DIR reader so the focus-
   // manifest loader prefers a mounted `{owner}__{repo}.yml` over the public `.gittensory.yml` (review policy stays
   // private). Unset dir ⇒ null reader ⇒ unchanged public-fetch behavior.

test/unit/selfhost-preflight.test.ts

@@ -0,0 +1,103 @@
+import {
+  assertSelfHostPreflight,
+  formatSelfHostPreflightError,
+  preflightEnv,
+  type SelfHostPreflightProblem,
+} from "../../src/selfhost/preflight";
+
+describe("self-host environment preflight (#2080)", () => {
+  it("returns every missing required value at once for the first-run setup path", () => {
+    const result = preflightEnv({});
+
+    expect(result).toEqual({
+      ok: false,
+      problems: [
+        expect.objectContaining({ var: "REDIS_URL" }),
+        expect.objectContaining({ var: "SELFHOST_SETUP_TOKEN" }),
+        expect.objectContaining({ var: "PUBLIC_API_ORIGIN" }),
+      ],
+    });
+  });
+
+  it("trims values, passes configured GitHub App installs, and accepts postgres URLs", () => {
+    expect(
+      preflightEnv({
+        REDIS_URL: " redis://redis:6379 ",
+        GITHUB_APP_ID: " 123 ",
+        DATABASE_URL: " postgres://gittensory:secret@postgres:5432/gittensory ",
+      }),
+    ).toEqual({ ok: true, problems: [] });
+
+    expect(
+      preflightEnv({
+        REDIS_URL: "redis://redis:6379",
+        GITHUB_APP_ID: "123",
+        DATABASE_URL: "postgresql://gittensory:secret@postgres:5432/gittensory",
+      }),
+    ).toEqual({ ok: true, problems: [] });
+  });
+
+  it("requires setup-wizard vars only when neither a GitHub App nor Orb broker enrollment is configured", () => {
+    expect(
+      preflightEnv({
+        REDIS_URL: "redis://redis:6379",
+        SELFHOST_SETUP_TOKEN: "setup-secret",
+        PUBLIC_API_ORIGIN: "https://selfhost.example",
+      }),
+    ).toEqual({ ok: true, problems: [] });
+
+    expect(
+      preflightEnv({
+        REDIS_URL: "redis://redis:6379",
+        ORB_ENROLLMENT_SECRET: "orb-secret",
+      }),
+    ).toEqual({ ok: true, problems: [] });
+  });
+
+  it("flags blank values and invalid DATABASE_URL while never echoing supplied secrets", () => {
+    const result = preflightEnv({
+      REDIS_URL: "   ",
+      SELFHOST_SETUP_TOKEN: "secret-setup-token",
+      PUBLIC_API_ORIGIN: "https://selfhost.example",
+      DATABASE_URL: "sqlite:///tmp/gittensory.sqlite?password=super-secret-db",
+    });
+
+    expect(result).toEqual({
+      ok: false,
+      problems: [
+        expect.objectContaining({ var: "REDIS_URL" }),
+        expect.objectContaining({ var: "DATABASE_URL" }),
+      ],
+    });
+    const serialized = JSON.stringify(result);
+    expect(serialized).not.toContain("secret-setup-token");
+    expect(serialized).not.toContain("super-secret-db");
+    expect(serialized).not.toContain("sqlite:///tmp");
+  });
+
+  it("formats all problems with names and actionable hints", () => {
+    const problems: SelfHostPreflightProblem[] = [
+      { var: "REDIS_URL", message: "Set REDIS_URL to Redis." },
+      { var: "PUBLIC_API_ORIGIN", message: "Set PUBLIC_API_ORIGIN to HTTPS." },
+    ];
+
+    expect(formatSelfHostPreflightError(problems)).toBe(
+      "Self-host environment preflight failed:\n" +
+        "- REDIS_URL: Set REDIS_URL to Redis.\n" +
+        "- PUBLIC_API_ORIGIN: Set PUBLIC_API_ORIGIN to HTTPS.",
+    );
+  });
+
+  it("asserts the preflight result for the boot path", () => {
+    expect(() =>
+      assertSelfHostPreflight({
+        REDIS_URL: "redis://redis:6379",
+        GITHUB_APP_ID: "123",
+      }),
+    ).not.toThrow();
+
+    expect(() => assertSelfHostPreflight({ DATABASE_URL: "mysql://db/app" })).toThrow(
+      /Self-host environment preflight failed:\n- REDIS_URL: .*SELFHOST_SETUP_TOKEN.*PUBLIC_API_ORIGIN.*DATABASE_URL:/s,
+    );
+  });
+});