@podosoft/podokit 0.17.4 → 1.0.1

package/dist/templates/fullstack/apps/api/src/app.ts

@@ -0,0 +1,162 @@
+import { cors } from "@elysia/cors";
+import { openapi } from "@elysia/openapi";
+import { AppException, type ErrorEnvelope } from "@podosoft/podokit-contracts";
+import { Elysia } from "elysia";
+import { configureServices, extensionModules } from "./app.extensions";
+import { validateEnv, type AppEnv } from "./config/env.validation";
+import {
+  appContext,
+  createCoreServices,
+  type AppPlugin,
+  type PodokitModule,
+  type ServiceRegistry,
+} from "./core/services";
+import { healthPlugin } from "./health/health.plugin";
+// podokit:begin:imports
+// podokit:end:imports
+
+export interface CreateAppOptions {
+  env?: AppEnv;
+  services?: ServiceRegistry;
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {};
+}
+
+function mergeOpenApi(
+  base: Record<string, unknown>,
+  contributions: Array<{ document: Record<string, unknown>; pathPrefix?: string }>,
+): Record<string, unknown> {
+  const paths = { ...record(base.paths) };
+  const components = { ...record(base.components) };
+  const tags = Array.isArray(base.tags) ? [...base.tags] : [];
+
+  for (const contribution of contributions) {
+    const prefix = contribution.pathPrefix?.replace(/\/$/, "") ?? "";
+    for (const [path, operations] of Object.entries(record(contribution.document.paths))) {
+      paths[`${prefix}${path}`] = operations;
+    }
+    for (const [group, values] of Object.entries(record(contribution.document.components))) {
+      components[group] = { ...record(components[group]), ...record(values) };
+    }
+    if (Array.isArray(contribution.document.tags)) {
+      for (const tag of contribution.document.tags) {
+        const name = record(tag).name;
+        if (!tags.some((candidate) => record(candidate).name === name)) tags.push(tag);
+      }
+    }
+  }
+  return { ...base, paths, components, tags };
+}
+
+function errorEnvelope(
+  code: string,
+  message: string,
+  statusCode: number,
+  path: string,
+  details?: unknown,
+): ErrorEnvelope {
+  return {
+    success: false,
+    error: {
+      code,
+      message,
+      statusCode,
+      path,
+      timestamp: new Date().toISOString(),
+      ...(details === undefined ? {} : { details }),
+    },
+  };
+}
+
+const buildApp = (options: CreateAppOptions = {}) => {
+  const env = options.env ?? validateEnv(process.env);
+  const services = options.services ?? createCoreServices(env);
+  const modules: PodokitModule[] = [
+    // podokit:begin:modules
+    // podokit:end:modules
+    ...extensionModules,
+  ];
+  for (const module of modules) module.configure?.(env, services);
+  configureServices(services);
+  services.freeze();
+  const context = appContext(env, services);
+  const corsOrigin = env.CORS_ORIGIN?.split(",").map((origin) => origin.trim());
+
+  const app = new Elysia({ name: "podokit" })
+    .use(cors({ origin: corsOrigin ?? true, credentials: true }))
+    .use(
+      openapi({
+        path: "/api-docs",
+        specPath: "/api-docs-elysia-json",
+        scalar: { url: "/api-docs-json" },
+        documentation: {
+          info: {
+            title: "{{projectName}} API",
+            description: "Generated with PodoKit",
+            version: "1.0.0",
+          },
+        },
+      }),
+    )
+    .onRequest(async ({ request, server, set }) => {
+      const requestId = request.headers.get("x-request-id") ?? crypto.randomUUID();
+      set.headers["x-request-id"] = requestId;
+      await context.requestGuards.run({
+        request,
+        ...(server?.requestIP(request)?.address
+          ? { remoteAddress: server.requestIP(request)?.address }
+          : {}),
+        setHeader: (name, value) => { set.headers[name] = value; },
+      });
+    })
+    .onAfterResponse(({ request, set }) => {
+      context.logger.info(
+        { method: request.method, path: new URL(request.url).pathname, statusCode: set.status },
+        "Complete request",
+      );
+    })
+    .onError(({ code, error, path, set }) => {
+      if (error instanceof AppException) {
+        set.status = error.statusCode;
+        return errorEnvelope(error.code, error.message, error.statusCode, path);
+      }
+      const statusCode = code === "NOT_FOUND" ? 404 : code === "VALIDATION" ? 400 : 500;
+      set.status = statusCode;
+      const publicCode = code === "NOT_FOUND"
+        ? "NOT_FOUND"
+        : code === "VALIDATION"
+          ? "VALIDATION_ERROR"
+          : "INTERNAL_ERROR";
+      const message = statusCode === 500
+        ? "Internal server error"
+        : error instanceof Error
+          ? error.message
+          : "Request failed";
+      return errorEnvelope(publicCode, message, statusCode, path);
+    });
+
+  const plugins: AppPlugin[] = [
+    healthPlugin,
+    ...modules.flatMap((module) => module.plugin ? [module.plugin] : []),
+  ];
+  for (const plugin of plugins) app.use(plugin(context));
+  app.get("/api-docs-json", async () => {
+    const response = await app.handle(new Request("http://localhost/api-docs-elysia-json"));
+    const base = record(await response.json());
+    return mergeOpenApi(base, await context.openapi.contributions());
+  }, {
+    detail: { hide: true },
+  });
+  app.onStop(() => { void services.close(); });
+  return app;
+};
+
+export type PodokitApp = ReturnType<typeof buildApp>;
+
+export function createApp(options: CreateAppOptions = {}): PodokitApp {
+  return buildApp(options);
+}

package/dist/templates/{todo → fullstack}/apps/api/src/config/redis.connection.spec.ts

@@ -1,5 +1,5 @@
-import { describe, expect, it } from "@jest/globals";
-import { redisConnectionOptions } from "./redis.connection";
+import { describe, expect, it } from "bun:test";
+import { redisConnectionOptions, redisConnectionUrl } from "./redis.connection";
 
 describe("redisConnectionOptions", () => {
   it("prefers an authenticated URL over individual settings", () => {
@@ -51,3 +51,21 @@ describe("redisConnectionOptions", () => {
     }
   });
 });
+
+describe("redisConnectionUrl", () => {
+  it("preserves an explicitly configured URL after validation", () => {
+    expect(redisConnectionUrl({ REDIS_URL: "rediss://user:p%40ss@example.com:6381/4" }))
+      .toBe("rediss://user:p%40ss@example.com:6381/4");
+  });
+
+  it("builds a Bun Redis URL from host-style environment variables", () => {
+    expect(redisConnectionUrl({
+      REDIS_HOST: "cache.example.com",
+      REDIS_PORT: "6381",
+      REDIS_DB: "4",
+      REDIS_USERNAME: "podokit",
+      REDIS_PASSWORD: "p@ss",
+      REDIS_TLS: "true",
+    })).toBe("rediss://podokit:p%40ss@cache.example.com:6381/4");
+  });
+});

package/dist/templates/{todo → fullstack}/apps/api/src/config/redis.connection.ts

@@ -67,3 +67,19 @@ export function redisConnectionOptions(
       };
   return { ...base, ...overrides };
 }
+
+/** Resolve the same Redis configuration as BullMQ into a URL for Bun.RedisClient. */
+export function redisConnectionUrl(env: NodeJS.ProcessEnv = process.env): string {
+  if (env.REDIS_URL) {
+    fromUrl(env.REDIS_URL);
+    return env.REDIS_URL;
+  }
+  const options = redisConnectionOptions(env);
+  const url = new URL(`${options.tls ? "rediss" : "redis"}://localhost`);
+  url.hostname = options.host;
+  url.port = String(options.port);
+  url.pathname = `/${options.db}`;
+  if (options.username) url.username = options.username;
+  if (options.password) url.password = options.password;
+  return url.toString();
+}

package/dist/templates/fullstack/apps/api/src/core/api-contract.spec.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "bun:test";
+import {
+  assertApiContract,
+  assertConsistentRouteParameters,
+  documentedApiRoutes,
+  expectedApiRoutes,
+  missingApiRoutes,
+} from "./api-contract";
+
+describe("API contract inventory", () => {
+  it("covers the core, Todo, module, and Better Auth routes", () => {
+    const expected = expectedApiRoutes("todo", ["auth", "redis", "file-upload"]);
+
+    expect(expected).toContain("GET /health/ready");
+    expect(expected).toContain("PATCH /todos/{id}");
+    expect(expected).toContain("POST /api/auth/sign-in/email");
+    expect(expected).toContain("PUT /cache/{key}");
+    expect(expected).toContain("POST /files");
+  });
+
+  it("uses one structural parameter name for every public blog post route", () => {
+    const expected = expectedApiRoutes("fullstack", ["blog"]);
+
+    expect(expected).toContain("GET /blog/{postRef}");
+    expect(expected).toContain("PATCH /blog/{postRef}");
+    expect(expected).toContain("POST /blog/{postRef}/comments");
+    expect(expected).not.toContain("GET /blog/{slug}");
+    expect(expected).not.toContain("PATCH /blog/{id}");
+  });
+
+  it("normalizes OpenAPI operations and reports an exact missing route", () => {
+    const document = { paths: { "/health": { get: {} }, "/health/ready": { get: {} } } };
+
+    expect(documentedApiRoutes(document)).toEqual(new Set(["GET /health", "GET /health/ready"]));
+    expect(missingApiRoutes(document, "fullstack", ["redis"])).toEqual([
+      "GET /cache/{key}",
+      "PUT /cache/{key}",
+    ]);
+    expect(() => assertApiContract(document, "fullstack", ["redis"])).toThrow(
+      "OpenAPI contract is missing routes",
+    );
+  });
+
+  it("rejects different parameter names at one router position", () => {
+    expect(() => assertConsistentRouteParameters([
+      { method: "GET", path: "/hosts/:hostId" },
+      { method: "GET", path: "/hosts/:hostId/files/:path" },
+      { method: "DELETE", path: "/hosts/:id/services/:serviceId" },
+    ])).toThrow(
+      "API routes at the same structural position must use one parameter name",
+    );
+
+    expect(() => assertConsistentRouteParameters([
+      { method: "GET", path: "/hosts/:hostId" },
+      { method: "GET", path: "/hosts/:hostId/files/:path" },
+      { method: "DELETE", path: "/hosts/:hostId/services/:serviceId" },
+    ])).not.toThrow();
+  });
+});

package/dist/templates/fullstack/apps/api/src/core/api-contract.ts

@@ -0,0 +1,169 @@
+const OPERATIONS = new Set(["get", "post", "put", "patch", "delete", "options", "head"]);
+
+const CORE_ROUTES = [
+  "GET /health",
+  "GET /health/ready",
+];
+
+const TEMPLATE_ROUTES: Record<string, string[]> = {
+  todo: [
+    "GET /todos",
+    "GET /todos/{id}",
+    "POST /todos",
+    "PATCH /todos/{id}",
+    "DELETE /todos/{id}",
+  ],
+};
+
+const MODULE_ROUTES: Record<string, string[]> = {
+  auth: [
+    "GET /account/me",
+    "GET /account/require-2fa",
+    "GET /account/capabilities",
+    "PUT /account/settings",
+    "GET /account/auth-config",
+    "PUT /account/auth-config",
+    "POST /account/org-member",
+    "GET /api/auth/get-session",
+    "POST /api/auth/sign-in/email",
+  ],
+  "admin-dashboard": [
+    "GET /site/settings",
+    "PUT /site/settings",
+    "POST /site/favicon",
+    "GET /site/favicon",
+    "POST /account/profile-image",
+    "DELETE /account/profile-image",
+    "GET /profile-images/{fileName}",
+  ],
+  "api-key-auth": ["GET /machine/ping"],
+  "audit-log": ["GET /audit-logs"],
+  analytics: [
+    "GET /analytics/config",
+    "GET /admin/analytics/config",
+    "PUT /admin/analytics/config",
+    "DELETE /admin/analytics/config/credentials",
+    "POST /admin/analytics/config/test",
+    "GET /admin/analytics/report",
+    "GET /admin/analytics/realtime",
+  ],
+  blog: [
+    "GET /blog",
+    "POST /blog/images",
+    "GET /blog/images/{id}",
+    "GET /blog/mine",
+    "GET /blog/manage/{slug}",
+    "GET /blog/{postRef}/comments",
+    "GET /blog/{postRef}",
+    "POST /blog",
+    "PATCH /blog/{postRef}",
+    "DELETE /blog/{postRef}",
+    "POST /blog/{postRef}/comments",
+    "PATCH /blog/comments/{id}",
+    "DELETE /blog/comments/{id}",
+    "GET /admin/blog",
+    "GET /admin/blog/{id}",
+    "POST /admin/blog",
+    "PATCH /admin/blog/{id}",
+    "DELETE /admin/blog/{id}",
+  ],
+  bullmq: ["POST /jobs", "GET /jobs/{id}"],
+  "file-upload": ["POST /files", "GET /files/{key}/url"],
+  "job-progress": ["POST /progress"],
+  "object-storage-s3": [
+    "PUT /storage/{key}",
+    "GET /storage/{key}",
+    "GET /storage/{key}/presigned",
+  ],
+  redis: ["PUT /cache/{key}", "GET /cache/{key}"],
+  sse: ["GET /events/stream", "POST /events"],
+};
+
+interface RuntimeRoute {
+  path: string;
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {};
+}
+
+function runtimeRoutes(value: unknown): RuntimeRoute[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((route) => {
+    const path = record(route).path;
+    return typeof path === "string" ? [{ path }] : [];
+  });
+}
+
+/**
+ * Memoirist stores one parameter name at each structural radix-tree position.
+ * Routes such as `/hosts/:id` and `/hosts/:hostId/files` therefore cannot share
+ * an Elysia application even though their complete paths differ.
+ */
+export function assertConsistentRouteParameters(routes: unknown): void {
+  const names = new Map<string, { name: string; path: string }>();
+  const conflicts: string[] = [];
+
+  for (const route of runtimeRoutes(routes)) {
+    let position = "";
+    for (const segment of route.path.split("/").filter(Boolean)) {
+      const match = /^:([^?*]+)/.exec(segment);
+      position += `/${match ? ":" : segment}`;
+      const name = match?.[1];
+      if (!name) continue;
+      const existing = names.get(position);
+      if (!existing) {
+        names.set(position, { name, path: route.path });
+      } else if (existing.name !== name) {
+        conflicts.push(
+          `${route.path} uses :${name}; ${existing.path} uses :${existing.name} at ${position}`,
+        );
+      }
+    }
+  }
+
+  if (conflicts.length > 0) {
+    throw new Error(
+      `API routes at the same structural position must use one parameter name:\n${conflicts.join("\n")}`,
+    );
+  }
+}
+
+export function documentedApiRoutes(document: unknown): Set<string> {
+  const routes = new Set<string>();
+  for (const [path, operations] of Object.entries(record(record(document).paths))) {
+    for (const method of Object.keys(record(operations))) {
+      if (OPERATIONS.has(method.toLowerCase())) routes.add(`${method.toUpperCase()} ${path}`);
+    }
+  }
+  return routes;
+}
+
+export function expectedApiRoutes(template: string, modules: string[]): Set<string> {
+  const routes = new Set(CORE_ROUTES);
+  for (const route of TEMPLATE_ROUTES[template] ?? []) routes.add(route);
+  for (const module of modules) {
+    for (const route of MODULE_ROUTES[module] ?? []) routes.add(route);
+  }
+  return routes;
+}
+
+export function missingApiRoutes(
+  document: unknown,
+  template: string,
+  modules: string[],
+): string[] {
+  const documented = documentedApiRoutes(document);
+  return [...expectedApiRoutes(template, modules)]
+    .filter((route) => !documented.has(route))
+    .sort();
+}
+
+export function assertApiContract(document: unknown, template: string, modules: string[]): void {
+  const missing = missingApiRoutes(document, template, modules);
+  if (missing.length > 0) {
+    throw new Error(`OpenAPI contract is missing routes:\n${missing.join("\n")}`);
+  }
+}

package/dist/templates/fullstack/apps/api/src/core/services.spec.ts

@@ -0,0 +1,90 @@
+import { describe, expect, test } from "bun:test";
+import {
+  AccessPolicy,
+  OpenApiRegistry,
+  RequestGuardRegistry,
+  ServiceRegistry,
+} from "./services";
+
+describe("ServiceRegistry", () => {
+  test("awaits startup in registration order and starts only once", async () => {
+    const registry = new ServiceRegistry();
+    const order: number[] = [];
+    registry.onStart(async () => { order.push(1); });
+    registry.onStart(() => { order.push(2); });
+    registry.freeze();
+
+    await Promise.all([registry.start(), registry.start()]);
+    expect(order).toEqual([1, 2]);
+  });
+
+  test("closes in reverse order and closes only once", async () => {
+    const registry = new ServiceRegistry();
+    const order: number[] = [];
+    const first = Symbol("first");
+    const second = Symbol("second");
+    registry.register(first, true, () => { order.push(1); });
+    registry.register(second, true, async () => { order.push(2); });
+
+    await Promise.all([registry.close(), registry.close()]);
+    expect(order).toEqual([2, 1]);
+  });
+
+  test("rejects startup before later starters can run", async () => {
+    const registry = new ServiceRegistry();
+    let reached = false;
+    registry.onStart(() => { throw new Error("dependency unavailable"); });
+    registry.onStart(() => { reached = true; });
+
+    await expect(registry.start()).rejects.toThrow("dependency unavailable");
+    expect(reached).toBe(false);
+  });
+});
+
+describe("AccessPolicy", () => {
+  test("defaults to session access", () => {
+    const policy = new AccessPolicy();
+    expect(policy.resolve(new Request("http://localhost/todos"))).toBe("session");
+  });
+
+  test("matches methods, parameters, and wildcard routes", () => {
+    const policy = new AccessPolicy();
+    policy.register("GET", "/blog/:slug", "public");
+    policy.register("*", "/api/auth/*", "public");
+
+    expect(policy.resolve(new Request("http://localhost/blog/hello"))).toBe("public");
+    expect(policy.resolve(new Request("http://localhost/blog/hello", { method: "POST" }))).toBe("session");
+    expect(policy.resolve(new Request("http://localhost/api/auth/sign-in/email"))).toBe("public");
+  });
+
+  test("uses the most recently registered matching rule", () => {
+    const policy = new AccessPolicy();
+    policy.register("*", "/content/*", "public");
+    policy.register("POST", "/content/:slug", "session");
+
+    expect(policy.resolve(new Request("http://localhost/content/post", { method: "POST" }))).toBe("session");
+  });
+});
+
+describe("RequestGuardRegistry", () => {
+  test("runs guards in registration order", async () => {
+    const registry = new RequestGuardRegistry();
+    const order: number[] = [];
+    registry.register(() => { order.push(1); });
+    registry.register(async () => { order.push(2); });
+
+    await registry.run({
+      request: new Request("http://localhost/health"),
+      setHeader: () => undefined,
+    });
+    expect(order).toEqual([1, 2]);
+  });
+});
+
+describe("OpenApiRegistry", () => {
+  test("rejects duplicate contributor names", () => {
+    const registry = new OpenApiRegistry();
+    registry.register("auth", () => ({ document: {} }));
+    expect(() => registry.register("auth", () => ({ document: {} }))).toThrow("already exists");
+  });
+});