@veducio/keja 0.0.0-stage → 0.2.3

package/src/project/config.test.ts

@@ -0,0 +1,140 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { defineConfig, loadConfig, resolveProjectPaths } from "./config.ts";
+
+describe("defineConfig", () => {
+  it("uses the default project paths", () => {
+    expect(defineConfig()).toMatchObject({
+      versioning: "keja.versioning.ts",
+      public_path: "src/public",
+      service_path: "src/service",
+    });
+  });
+
+  it("keeps the paths that are set", () => {
+    expect(
+      defineConfig({
+        versioning: "config/versions.ts",
+        public_path: "routes/public",
+      }),
+    ).toMatchObject({
+      versioning: "config/versions.ts",
+      public_path: "routes/public",
+      service_path: "src/service",
+    });
+  });
+
+  it("keeps the database disabled until it is turned on", () => {
+    expect(defineConfig().database).toEqual({ enabled: false });
+    expect(defineConfig({ db: { enabled: false } }).database).toEqual({
+      enabled: false,
+    });
+    expect(defineConfig({ db: { enabled: true } }).database).toEqual({
+      enabled: true,
+      migrations: "migrations",
+    });
+    expect(
+      defineConfig({
+        db: { enabled: true, migrations: "db/migrations" },
+      }).database,
+    ).toEqual({
+      enabled: true,
+      migrations: "db/migrations",
+    });
+  });
+
+  it("rejects an empty path", () => {
+    expect(() => defineConfig({ service_path: "  " })).toThrow(
+      "keja.config.ts service_path must be a non-empty path",
+    );
+  });
+
+  it("keeps an optional Argus registry", () => {
+    expect(
+      defineConfig({
+        name: "billing",
+        argus: {
+          enabled: true,
+          url: "https://argus.veducio.com/",
+          env: "staging",
+          username: "argus",
+          password: "secret",
+          public: "billing",
+        },
+      }).argus,
+    ).toEqual({
+      enabled: true,
+      url: "https://argus.veducio.com",
+      env: "staging",
+      username: "argus",
+      password: "secret",
+      public: "billing",
+      service: null,
+    });
+    expect(defineConfig({ argus: { enabled: false } }).argus).toEqual({
+      enabled: false,
+    });
+    expect(() =>
+      defineConfig({
+        argus: { enabled: true, url: "argus.veducio.com", env: "staging" },
+      }),
+    ).toThrow("keja.config.ts argus.url must be an absolute http or https URL");
+  });
+
+  it("reads Vault settings from config", () => {
+    expect(
+      defineConfig({
+        vault: {
+          enabled: true,
+          address: "https://vault.example/",
+          token: "s.token",
+          namespace: "apps",
+          mount: "kv",
+        },
+      }).vault,
+    ).toEqual({
+      enabled: true,
+      address: "https://vault.example",
+      token: "s.token",
+      namespace: "apps",
+      mount: "kv",
+    });
+    expect(defineConfig().vault).toEqual({ enabled: false });
+  });
+});
+
+describe("loadConfig", () => {
+  it("resolves the default paths from the project root", async () => {
+    const root = mkdtempSync(path.join(tmpdir(), "keja-config-"));
+    await expect(loadConfig(root)).resolves.toEqual({
+      config: null,
+      name: null,
+      argus: { enabled: false },
+      database: { enabled: false },
+      vault: { enabled: false },
+      versioning: path.resolve(root, "keja.versioning.ts"),
+      public: path.resolve(root, "src/public"),
+      service: path.resolve(root, "src/service"),
+    });
+  });
+
+  it("resolves custom paths from the project root", () => {
+    const root = path.resolve("app");
+    expect(
+      resolveProjectPaths(
+        root,
+        defineConfig({
+          versioning: "versioning/api.ts",
+          public_path: "http/public",
+          service_path: "http/service",
+        }),
+      ),
+    ).toEqual({
+      versioning: path.resolve(root, "versioning/api.ts"),
+      public: path.resolve(root, "http/public"),
+      service: path.resolve(root, "http/service"),
+    });
+  });
+});

package/src/project/config.ts

@@ -0,0 +1,413 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { projectError } from "../errors/framework-errors.ts";
+import { freshImportUrl } from "./reload-graph.ts";
+
+const configBrand = "keja.config";
+
+const defaultConfig = {
+  versioning: "keja.versioning.ts",
+  public_path: "src/public",
+  service_path: "src/service",
+};
+
+export type ArgusSettings = {
+  url: string;
+  env: string;
+  username: string | null;
+  password: string | null;
+  public: string | null;
+  service: string | null;
+};
+
+export type ArgusConfigInput = {
+  enabled: boolean;
+  url?: string;
+  env?: string;
+  username?: string;
+  password?: string;
+  public?: string;
+  service?: string;
+};
+
+export type ArgusConfig =
+  | { enabled: false }
+  | ({ enabled: true } & ArgusSettings);
+
+export type DatabaseConfigInput = {
+  enabled: boolean;
+  migrations?: string;
+};
+
+export type DatabaseConfig =
+  | { enabled: false }
+  | { enabled: true; migrations: string };
+
+export type VaultSettings = {
+  address: string;
+  token: string;
+  namespace: string | null;
+  mount: string;
+};
+
+export type VaultConfigInput = {
+  enabled: boolean;
+  address?: string;
+  token?: string;
+  namespace?: string;
+  mount?: string;
+};
+
+export type VaultConfig =
+  | { enabled: false }
+  | ({ enabled: true } & VaultSettings);
+
+export type KejaConfigInput = {
+  name?: string;
+  versioning?: string;
+  public_path?: string;
+  service_path?: string;
+  argus?: ArgusConfigInput;
+  db?: DatabaseConfigInput;
+  vault?: VaultConfigInput;
+};
+
+export type KejaConfig = {
+  name: string | null;
+  versioning: string;
+  public_path: string;
+  service_path: string;
+  argus: ArgusConfig;
+  database: DatabaseConfig;
+  vault: VaultConfig;
+};
+
+export function defineConfig(input: KejaConfigInput = {}) {
+  const config: KejaConfig = {
+    name: optionalText(input.name, "name", "service name"),
+    versioning: configPath(
+      input.versioning,
+      defaultConfig.versioning,
+      "versioning",
+    ),
+    public_path: configPath(
+      input.public_path,
+      defaultConfig.public_path,
+      "public_path",
+    ),
+    service_path: configPath(
+      input.service_path,
+      defaultConfig.service_path,
+      "service_path",
+    ),
+    argus: configArgus(input.argus),
+    database: configDatabase(input.db),
+    vault: configVault(input.vault),
+  };
+  return Object.assign(config, { [configBrand]: true as const });
+}
+
+export function isConfig(value: unknown): value is KejaConfig {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    configBrand in value &&
+    (value as Record<string, unknown>)[configBrand] === true &&
+    hasPath(value, "versioning") &&
+    hasPath(value, "public_path") &&
+    hasPath(value, "service_path") &&
+    hasName(value) &&
+    hasArgus(value) &&
+    hasDatabase(value) &&
+    hasVault(value)
+  );
+}
+
+export type ProjectPaths = {
+  config: string | null;
+  versioning: string;
+  public: string;
+  service: string;
+};
+
+export type LoadedConfig = ProjectPaths & {
+  name: string | null;
+  argus: ArgusConfig;
+  database: DatabaseConfig;
+  vault: VaultConfig;
+};
+
+export function resolveProjectPaths(root: string, config: KejaConfig) {
+  return {
+    versioning: path.resolve(root, config.versioning),
+    public: path.resolve(root, config.public_path),
+    service: path.resolve(root, config.service_path),
+  };
+}
+
+export async function loadConfig(
+  root: string,
+  generation?: string,
+): Promise<LoadedConfig> {
+  const file = path.join(root, "keja.config.ts");
+  if (!existsSync(file)) {
+    return loadedConfig(root, null, defineConfig());
+  }
+  const href = generation
+    ? freshImportUrl(file, generation)
+    : pathToFileURL(file).href;
+  const loaded = await import(href);
+  if (!isConfig(loaded.default)) {
+    throw projectError(
+      "invalidConfigFile",
+      `${file} must default-export defineConfig(...)`,
+    );
+  }
+  return loadedConfig(root, file, loaded.default);
+}
+
+function configPath(value: unknown, fallback: string, field: string) {
+  if (value === undefined) {
+    return fallback;
+  }
+  if (typeof value !== "string" || value.trim() === "") {
+    throw projectError(
+      "invalidConfigFile",
+      `keja.config.ts ${field} must be a non-empty path`,
+    );
+  }
+  return value.trim();
+}
+
+function loadedConfig(
+  root: string,
+  file: string | null,
+  config: KejaConfig,
+): LoadedConfig {
+  return {
+    config: file,
+    ...resolveProjectPaths(root, config),
+    name: config.name,
+    argus: config.argus,
+    database: resolvedDatabase(root, config.database),
+    vault: config.vault,
+  };
+}
+
+function resolvedDatabase(
+  root: string,
+  database: DatabaseConfig,
+): DatabaseConfig {
+  if (!database.enabled) {
+    return database;
+  }
+  return {
+    enabled: true,
+    migrations: path.resolve(root, database.migrations),
+  };
+}
+
+function configDatabase(
+  value: DatabaseConfigInput | undefined,
+): DatabaseConfig {
+  if (value === undefined) {
+    return { enabled: false };
+  }
+  if (!isEnabledObject(value)) {
+    throw projectError(
+      "invalidConfigFile",
+      "keja.config.ts db must be an object with enabled",
+    );
+  }
+  if (!value.enabled) {
+    return { enabled: false };
+  }
+  return {
+    enabled: true,
+    migrations: configPath(value.migrations, "migrations", "db.migrations"),
+  };
+}
+
+function configArgus(value: ArgusConfigInput | undefined): ArgusConfig {
+  if (value === undefined) {
+    return { enabled: false };
+  }
+  if (!isEnabledObject(value)) {
+    throw projectError(
+      "invalidConfigFile",
+      "keja.config.ts argus must be an object with enabled",
+    );
+  }
+  if (!value.enabled) {
+    return { enabled: false };
+  }
+  const username = optionalText(value.username, "argus.username", "username");
+  const password = optionalText(value.password, "argus.password", "password");
+  if ((username === null) !== (password === null)) {
+    throw projectError(
+      "invalidConfigFile",
+      "keja.config.ts argus.username and argus.password must both be set",
+    );
+  }
+  return {
+    enabled: true,
+    url: absoluteHttpUrl(value.url, "argus.url"),
+    env: requiredText(value.env, "argus.env", "environment name"),
+    username,
+    password,
+    public: optionalText(value.public, "argus.public", "service name"),
+    service: optionalText(value.service, "argus.service", "service name"),
+  };
+}
+
+function configVault(value: VaultConfigInput | undefined): VaultConfig {
+  if (value === undefined) {
+    return { enabled: false };
+  }
+  if (!isEnabledObject(value)) {
+    throw projectError(
+      "invalidConfigFile",
+      "keja.config.ts vault must be an object with enabled",
+    );
+  }
+  if (!value.enabled) {
+    return { enabled: false };
+  }
+  const namespace =
+    value.namespace ?? configEnv("VAULT_NAMESPACE") ?? undefined;
+  return {
+    enabled: true,
+    address: absoluteHttpUrl(
+      value.address ?? configEnv("VAULT_ADDR") ?? undefined,
+      "vault.address",
+    ),
+    token: requiredText(
+      value.token ?? configEnv("VAULT_TOKEN") ?? undefined,
+      "vault.token",
+      "token",
+    ),
+    namespace: optionalText(namespace, "vault.namespace", "namespace"),
+    mount: vaultMount(value.mount ?? configEnv("VAULT_KV_MOUNT") ?? "secret"),
+  };
+}
+
+function isEnabledObject(value: unknown): value is { enabled: boolean } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { enabled?: unknown }).enabled === "boolean"
+  );
+}
+
+function absoluteHttpUrl(value: unknown, field: string) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw projectError(
+      "invalidConfigFile",
+      `keja.config.ts ${field} must be an absolute http or https URL`,
+    );
+  }
+  try {
+    const url = new URL(value.trim());
+    if (url.protocol === "http:" || url.protocol === "https:") {
+      return url.href.replace(/\/$/, "");
+    }
+  } catch {
+    throw projectError(
+      "invalidConfigFile",
+      `keja.config.ts ${field} must be an absolute http or https URL`,
+    );
+  }
+  throw projectError(
+    "invalidConfigFile",
+    `keja.config.ts ${field} must be an absolute http or https URL`,
+  );
+}
+
+function vaultMount(value: string) {
+  const mount = value.trim().replace(/^\/+|\/+$/g, "");
+  if (!/^[A-Za-z0-9_-]+$/.test(mount)) {
+    throw projectError(
+      "invalidConfigFile",
+      `keja.config.ts vault.mount must be a mount name`,
+    );
+  }
+  return mount;
+}
+
+function configEnv(name: string) {
+  const runtime = globalThis as {
+    Bun?: { env?: Record<string, string | undefined> };
+  };
+  const value = runtime.Bun?.env?.[name] ?? process.env[name];
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+}
+
+function requiredText(value: unknown, field: string, label: string) {
+  const text = optionalText(value, field, label);
+  if (text === null) {
+    throw projectError(
+      "invalidConfigFile",
+      `keja.config.ts ${field} must be a non-empty ${label}`,
+    );
+  }
+  return text;
+}
+
+function optionalText(value: unknown, field: string, label: string) {
+  if (value === undefined) {
+    return null;
+  }
+  if (typeof value !== "string" || value.trim() === "") {
+    throw projectError(
+      "invalidConfigFile",
+      `keja.config.ts ${field} must be a non-empty ${label}`,
+    );
+  }
+  return value.trim();
+}
+
+function hasName(value: object) {
+  const name = (value as KejaConfig).name;
+  return name === null || typeof name === "string";
+}
+
+function hasArgus(value: object) {
+  const argus = (value as KejaConfig).argus;
+  return (
+    typeof argus === "object" &&
+    argus !== null &&
+    (argus.enabled === false ||
+      (argus.enabled === true &&
+        typeof argus.url === "string" &&
+        typeof argus.env === "string"))
+  );
+}
+
+function hasVault(value: object) {
+  const vault = (value as KejaConfig).vault;
+  return (
+    typeof vault === "object" &&
+    vault !== null &&
+    (vault.enabled === false ||
+      (vault.enabled === true &&
+        typeof vault.address === "string" &&
+        typeof vault.token === "string" &&
+        typeof vault.mount === "string"))
+  );
+}
+
+function hasDatabase(value: object) {
+  const database = (value as KejaConfig).database;
+  return (
+    typeof database === "object" &&
+    database !== null &&
+    (database.enabled === false ||
+      (database.enabled === true && typeof database.migrations === "string"))
+  );
+}
+
+function hasPath(value: object, key: keyof KejaConfig) {
+  return typeof (value as KejaConfig)[key] === "string";
+}

package/src/project/load.test.ts

@@ -0,0 +1,60 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { defineRoute, response } from "../route/define.ts";
+import { collectRouteFiles, routesFromModule } from "./load.ts";
+
+describe("collectRouteFiles", () => {
+  it("keeps route modules nested several directories deep", async () => {
+    const root = mkdtempSync(path.join(tmpdir(), "keja-routes-"));
+    const publicDirectory = path.join(root, "public");
+    mkdirSync(path.join(publicDirectory, "orgs", "teams"), {
+      recursive: true,
+    });
+    writeFileSync(path.join(publicDirectory, "_middleware.ts"), "");
+    writeFileSync(path.join(publicDirectory, "orgs", "_middleware.ts"), "");
+    writeFileSync(
+      path.join(publicDirectory, "orgs", "teams", "members.ts"),
+      "",
+    );
+    writeFileSync(
+      path.join(publicDirectory, "orgs", "teams", "members.test.ts"),
+      "",
+    );
+
+    await expect(collectRouteFiles(publicDirectory)).resolves.toEqual([
+      "orgs/teams/members.ts",
+    ]);
+  });
+});
+
+describe("routesFromModule", () => {
+  it("reads a default route and named routes from one module", () => {
+    const ready = route("get", "/ready");
+    const list = route("get", "/jobs");
+    const create = route("post", "/jobs");
+    expect(
+      routesFromModule({
+        default: ready,
+        list,
+        create,
+        schema: z.object({ name: z.string() }),
+      }).map((item) => `${item.method} ${item.path}`),
+    ).toEqual(["get /ready", "get /jobs", "post /jobs"]);
+    expect(routesFromModule({ schema: z.string() })).toEqual([]);
+  });
+});
+
+function route(method: "get" | "post", routePath: string) {
+  return defineRoute({
+    method,
+    path: routePath,
+    version: "v1",
+    responses: {
+      Ok: response({ code: 200, json: z.object({ ok: z.literal(true) }) }),
+    },
+    handler: ({ respond }) => respond.Ok({ ok: true }),
+  });
+}