devstack 0.1.0

package/templates/base/backend/src/lib/logger.ts

@@ -0,0 +1,168 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import {
+  configureSync,
+  getConsoleSink,
+  getLogger,
+  getTextFormatter,
+  resetSync,
+  type LogRecord,
+  type Sink,
+} from "@logtape/logtape";
+import { isSpanContextValid, trace } from "@opentelemetry/api";
+
+const SERVICE_NAME = "{{projectName}}-backend";
+const contextLocalStorage = new AsyncLocalStorage<Record<string, unknown>>();
+
+type LoggerConsole = Pick<Console, "debug" | "error" | "info" | "log" | "warn">;
+type LoggerMode = "json" | "text";
+type LoggerLevel = "debug" | "error" | "info";
+
+interface ConfigureBackendLoggerOptions {
+  console?: LoggerConsole;
+  force?: boolean;
+  level?: LoggerLevel;
+  mode?: LoggerMode;
+  rawEnv?: Record<string, string | undefined>;
+}
+
+let isConfigured = false;
+
+function normalizeLogValue(value: unknown): unknown {
+  if (value instanceof Error) {
+    return {
+      message: value.message,
+      name: value.name,
+      stack: value.stack,
+    };
+  }
+
+  return value;
+}
+
+function renderLogMessage(record: LogRecord): string {
+  return record.message
+    .map(part => {
+      if (typeof part === "string") {
+        return part;
+      }
+
+      if (typeof part === "number" || typeof part === "boolean") {
+        return String(part);
+      }
+
+      try {
+        return JSON.stringify(normalizeLogValue(part));
+      } catch {
+        return String(part);
+      }
+    })
+    .join("");
+}
+
+export function serializeLogRecord(record: LogRecord) {
+  const activeSpanContext = trace.getActiveSpan()?.spanContext();
+
+  return {
+    timestamp: new Date(record.timestamp).toISOString(),
+    level: record.level === "warning" ? "warn" : record.level,
+    message: renderLogMessage(record),
+    service: SERVICE_NAME,
+    ...(activeSpanContext && isSpanContextValid(activeSpanContext)
+      ? {
+          spanId: activeSpanContext.spanId,
+          traceId: activeSpanContext.traceId,
+        }
+      : {}),
+    ...Object.fromEntries(
+      Object.entries(record.properties).map(([key, value]) => [key, normalizeLogValue(value)])
+    ),
+  };
+}
+
+function createJsonConsoleSink(outputConsole: LoggerConsole): Sink {
+  return record => {
+    const payload = JSON.stringify(serializeLogRecord(record));
+    const level = record.level === "warning" ? "warn" : record.level;
+
+    switch (level) {
+      case "debug":
+        outputConsole.debug(payload);
+        return;
+      case "error":
+      case "fatal":
+        outputConsole.error(payload);
+        return;
+      case "warn":
+        outputConsole.warn(payload);
+        return;
+      default:
+        outputConsole.info(payload);
+    }
+  };
+}
+
+function resolveLoggerMode(rawEnv: Record<string, string | undefined>): LoggerMode {
+  if (rawEnv.LOG_FORMAT === "json") {
+    return "json";
+  }
+
+  return rawEnv.NODE_ENV === "production" ? "json" : "text";
+}
+
+function resolveLoggerLevel(rawEnv: Record<string, string | undefined>): LoggerLevel {
+  const rawLevel = rawEnv.LOG_LEVEL?.toLowerCase();
+
+  if (rawLevel === "debug" || rawLevel === "error" || rawLevel === "info") {
+    return rawLevel;
+  }
+
+  return rawEnv.NODE_ENV === "test" ? "error" : "info";
+}
+
+export function configureBackendLogger(options: ConfigureBackendLoggerOptions = {}) {
+  if (isConfigured && !options.force) {
+    return;
+  }
+
+  const rawEnv = options.rawEnv ?? process.env;
+  const mode = options.mode ?? resolveLoggerMode(rawEnv);
+  const level = options.level ?? resolveLoggerLevel(rawEnv);
+  const outputConsole = options.console ?? console;
+  const sinkConsole: Console = Object.assign(Object.create(console), console, outputConsole);
+  const sink =
+    mode === "json"
+      ? createJsonConsoleSink(outputConsole)
+      : getConsoleSink({
+          console: sinkConsole,
+          formatter: getTextFormatter(),
+        });
+
+  configureSync({
+    contextLocalStorage,
+    loggers: [
+      {
+        category: ["{{projectName}}"],
+        lowestLevel: level,
+        sinks: ["console"],
+      },
+      {
+        category: ["logtape"],
+        lowestLevel: "error",
+        sinks: ["console"],
+      },
+    ],
+    reset: true,
+    sinks: {
+      console: sink,
+    },
+  });
+
+  isConfigured = true;
+}
+
+export function resetBackendLoggerForTests() {
+  resetSync();
+  isConfigured = false;
+}
+
+export const logger = getLogger(["{{projectName}}", "backend"]);

package/templates/base/backend/src/lib/openapi-schemas.ts

@@ -0,0 +1,123 @@
+import { z } from "@hono/zod-openapi";
+
+export const validationErrorDetailSchema = z
+  .object({
+    field: z.string(),
+    message: z.string(),
+  })
+  .openapi("ValidationErrorDetail");
+
+export const problemDetailsSchema = z
+  .object({
+    type: z.string(),
+    title: z.string(),
+    status: z.number().int(),
+    detail: z.string(),
+    instance: z.string(),
+    errors: z.array(validationErrorDetailSchema).optional(),
+    provider: z.string().optional(),
+  })
+  .openapi("ProblemDetails");
+
+export const paginationMetaSchema = z
+  .object({
+    hasMore: z.boolean(),
+    nextCursor: z.string().nullable(),
+  })
+  .openapi("PaginationMeta");
+
+export function dataEnvelope<T extends z.ZodTypeAny>(schema: T) {
+  return z.object({
+    data: schema,
+  });
+}
+
+export function paginatedEnvelope<T extends z.ZodTypeAny>(schema: T) {
+  return z.object({
+    data: z.array(schema),
+    meta: paginationMetaSchema,
+  });
+}
+
+export const commonErrorResponses = {
+  400: {
+    content: {
+      "application/problem+json": {
+        schema: problemDetailsSchema,
+      },
+    },
+    description: "Bad request",
+  },
+  401: {
+    content: {
+      "application/problem+json": {
+        schema: problemDetailsSchema,
+      },
+    },
+    description: "Unauthorized",
+  },
+  403: {
+    content: {
+      "application/problem+json": {
+        schema: problemDetailsSchema,
+      },
+    },
+    description: "Forbidden",
+  },
+  404: {
+    content: {
+      "application/problem+json": {
+        schema: problemDetailsSchema,
+      },
+    },
+    description: "Resource not found",
+  },
+  409: {
+    content: {
+      "application/problem+json": {
+        schema: problemDetailsSchema,
+      },
+    },
+    description: "Conflict",
+  },
+  422: {
+    content: {
+      "application/problem+json": {
+        schema: problemDetailsSchema,
+      },
+    },
+    description: "Unprocessable entity",
+  },
+  429: {
+    content: {
+      "application/problem+json": {
+        schema: problemDetailsSchema,
+      },
+    },
+    description: "Too many requests",
+  },
+  500: {
+    content: {
+      "application/problem+json": {
+        schema: problemDetailsSchema,
+      },
+    },
+    description: "Internal server error",
+  },
+  502: {
+    content: {
+      "application/problem+json": {
+        schema: problemDetailsSchema,
+      },
+    },
+    description: "Bad gateway",
+  },
+  504: {
+    content: {
+      "application/problem+json": {
+        schema: problemDetailsSchema,
+      },
+    },
+    description: "Gateway timeout",
+  },
+} as const;

package/templates/base/backend/src/lib/openapi.ts

@@ -0,0 +1,113 @@
+import { OpenAPIHono, createRoute, type z } from "@hono/zod-openapi";
+import type { Env } from "hono";
+import { formatProblemDetails, UnprocessableEntityError } from "./errors";
+import { commonErrorResponses } from "./openapi-schemas";
+
+type OpenApiAppOptions<E extends Env> = ConstructorParameters<typeof OpenAPIHono<E>>[0];
+
+export const bearerAuthSecurity = [{ BearerAuth: [] as string[] }];
+
+export const validationHook = (result: any, c: any) => {
+  if (result.success) {
+    return undefined;
+  }
+
+  const details =
+    result.error?.issues.map((issue: { message: string; path: PropertyKey[] }) => ({
+      field: issue.path.join(".") || "unknown",
+      message: issue.message,
+    })) ?? [];
+  const problem = formatProblemDetails(
+    new UnprocessableEntityError("Validation failed", details),
+    new URL(c.req.url).pathname
+  );
+
+  c.header("Content-Type", "application/problem+json");
+  c.status(422);
+  return c.body(JSON.stringify(problem));
+};
+
+export function createOpenApiApp<E extends Env>(options: OpenApiAppOptions<E> = {}) {
+  const defaultHook = (options?.defaultHook ?? validationHook) as NonNullable<
+    OpenApiAppOptions<E>
+  >["defaultHook"];
+  return new OpenAPIHono<E>({
+    ...options,
+    defaultHook,
+  });
+}
+
+export const defineRoute = ((route: any) => createRoute(route)) as any;
+
+export function jsonContent<T extends z.ZodTypeAny>(schema: T) {
+  return {
+    "application/json": {
+      schema,
+    },
+  } as const;
+}
+
+export function problemContent<T extends z.ZodTypeAny>(schema: T) {
+  return {
+    "application/problem+json": {
+      schema,
+    },
+  } as const;
+}
+
+export function jsonBody<T extends z.ZodTypeAny>(schema: T, description: string, required = true) {
+  return {
+    required,
+    description,
+    content: jsonContent(schema),
+  } as const;
+}
+
+export function formBody<T extends z.ZodTypeAny>(
+  schema: T,
+  description: string,
+  required = true,
+  contentType: "multipart/form-data" | "application/x-www-form-urlencoded" = "multipart/form-data"
+) {
+  return {
+    required,
+    description,
+    content: {
+      [contentType]: {
+        schema,
+      },
+    },
+  } as const;
+}
+
+export function jsonResponse<T extends z.ZodTypeAny>(schema: T, description: string) {
+  return {
+    description,
+    content: jsonContent(schema),
+  } as const;
+}
+
+export function noContentResponse(description = "No content") {
+  return {
+    description,
+  } as const;
+}
+
+export function getRequiredParam(
+  c: {
+    req: {
+      param: (key: string) => string | undefined;
+    };
+  },
+  key: string
+) {
+  const value = c.req.param(key);
+
+  if (!value) {
+    throw new Error(`Missing required route param: ${key}`);
+  }
+
+  return value;
+}
+
+export { commonErrorResponses };

package/templates/base/backend/src/lib/pagination.ts

@@ -0,0 +1,75 @@
+import { clamp } from "es-toolkit/math";
+
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+
+type QueryValue = string | string[] | undefined;
+
+export interface PaginationParams {
+  limit: number;
+  startingAfter?: string;
+  endingBefore?: string;
+}
+
+export interface PaginationMeta {
+  hasMore: boolean;
+  nextCursor: string | null;
+}
+
+export interface PaginatedResult<T> {
+  data: T[];
+  meta: PaginationMeta;
+}
+
+function getQueryValue(value: QueryValue): string | undefined {
+  if (Array.isArray(value)) {
+    return value[0];
+  }
+
+  return value;
+}
+
+function parseLimit(value: QueryValue): number {
+  const rawValue = getQueryValue(value);
+
+  if (!rawValue) {
+    return DEFAULT_LIMIT;
+  }
+
+  const parsedValue = Number.parseInt(rawValue, 10);
+
+  if (!Number.isFinite(parsedValue) || parsedValue <= 0) {
+    return DEFAULT_LIMIT;
+  }
+
+  return clamp(parsedValue, DEFAULT_LIMIT, MAX_LIMIT);
+}
+
+export function parsePaginationParams(query: Record<string, QueryValue>): PaginationParams {
+  const startingAfter = getQueryValue(query.starting_after);
+  const endingBefore = getQueryValue(query.ending_before);
+
+  return {
+    limit: parseLimit(query.limit),
+    ...(startingAfter ? { startingAfter } : {}),
+    ...(endingBefore ? { endingBefore } : {}),
+  };
+}
+
+export function buildPaginatedResponse<T>(
+  items: T[],
+  limit: number,
+  getId: (item: T) => string
+): PaginatedResult<T> {
+  const hasMore = items.length > limit;
+  const data = hasMore ? items.slice(0, limit) : items;
+  const lastItem = data.at(-1);
+
+  return {
+    data,
+    meta: {
+      hasMore,
+      nextCursor: hasMore && lastItem ? getId(lastItem) : null,
+    },
+  };
+}

package/templates/base/backend/src/lib/response.ts

@@ -0,0 +1,23 @@
+import type { PaginatedResult } from "./pagination";
+
+export interface DataEnvelope<T> {
+  data: T;
+}
+
+export interface PaginatedEnvelope<T> extends PaginatedResult<T> {}
+
+export function ok<T>(data: T): DataEnvelope<T> {
+  return { data };
+}
+
+export function created<T>(data: T): DataEnvelope<T> {
+  return { data };
+}
+
+export function paginated<T>(result: PaginatedResult<T>): PaginatedEnvelope<T> {
+  return result;
+}
+
+export function noContent(): null {
+  return null;
+}

package/templates/base/backend/src/modules/items/index.ts

@@ -0,0 +1 @@
+export { itemsModule } from "./route";

package/templates/base/backend/src/modules/items/model.ts

@@ -0,0 +1,26 @@
+import { z } from "@hono/zod-openapi";
+
+export const itemSchema = z
+  .object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string().nullable(),
+    created_at: z.coerce.date(),
+    updated_at: z.coerce.date(),
+  })
+  .openapi("Item");
+
+export const createItemSchema = z
+  .object({
+    name: z.string().trim().min(1).max(120),
+    description: z.string().trim().max(500).optional(),
+  })
+  .strict();
+
+export const updateItemSchema = createItemSchema.partial().strict();
+
+export const itemParamsSchema = z
+  .object({
+    itemId: z.string().trim().min(1),
+  })
+  .strict();

package/templates/base/backend/src/modules/items/repository.ts

@@ -0,0 +1,30 @@
+import { asc, eq } from "drizzle-orm";
+import type { Database } from "@/db";
+import { items, type NewItem } from "@/db/schema";
+
+type Transaction = Parameters<Parameters<Database["transaction"]>[0]>[0];
+type DatabaseClient = Database | Transaction;
+
+export async function listItems(db: DatabaseClient) {
+  return db.select().from(items).orderBy(asc(items.created_at));
+}
+
+export async function findItemById(db: DatabaseClient, itemId: string) {
+  const [record] = await db.select().from(items).where(eq(items.id, itemId)).limit(1);
+  return record ?? null;
+}
+
+export async function createItem(db: DatabaseClient, input: NewItem) {
+  const [record] = await db.insert(items).values(input).returning();
+  return record;
+}
+
+export async function updateItem(db: DatabaseClient, itemId: string, input: Partial<NewItem>) {
+  const [record] = await db.update(items).set(input).where(eq(items.id, itemId)).returning();
+  return record ?? null;
+}
+
+export async function deleteItem(db: DatabaseClient, itemId: string) {
+  const [record] = await db.delete(items).where(eq(items.id, itemId)).returning();
+  return record ?? null;
+}

package/templates/base/backend/src/modules/items/route.ts

@@ -0,0 +1,93 @@
+import {
+  createOpenApiApp,
+  defineRoute,
+  jsonBody,
+  jsonResponse,
+  noContentResponse,
+} from "@/lib/openapi";
+import { dataEnvelope } from "@/lib/openapi-schemas";
+import { created, noContent, ok } from "@/lib/response";
+import { createItemSchema, itemParamsSchema, itemSchema, updateItemSchema } from "./model";
+import {
+  createItem,
+  deleteItem,
+  getItem,
+  listItems,
+  updateItem,
+} from "./usecases";
+
+export const itemsModule = createOpenApiApp();
+
+const listRoute = defineRoute({
+  method: "get",
+  path: "/",
+  tags: ["Items"],
+  summary: "List example items",
+  responses: {
+    200: jsonResponse(dataEnvelope(itemSchema.array()), "Example items"),
+  },
+});
+
+const getRoute = defineRoute({
+  method: "get",
+  path: "/{itemId}",
+  tags: ["Items"],
+  summary: "Get example item",
+  request: {
+    params: itemParamsSchema,
+  },
+  responses: {
+    200: jsonResponse(dataEnvelope(itemSchema), "Example item"),
+  },
+});
+
+const createRoute = defineRoute({
+  method: "post",
+  path: "/",
+  tags: ["Items"],
+  summary: "Create example item",
+  request: {
+    body: jsonBody(createItemSchema, "Create item payload"),
+  },
+  responses: {
+    201: jsonResponse(dataEnvelope(itemSchema), "Created example item"),
+  },
+});
+
+const updateRoute = defineRoute({
+  method: "patch",
+  path: "/{itemId}",
+  tags: ["Items"],
+  summary: "Update example item",
+  request: {
+    params: itemParamsSchema,
+    body: jsonBody(updateItemSchema, "Update item payload"),
+  },
+  responses: {
+    200: jsonResponse(dataEnvelope(itemSchema), "Updated example item"),
+  },
+});
+
+const deleteRoute = defineRoute({
+  method: "delete",
+  path: "/{itemId}",
+  tags: ["Items"],
+  summary: "Delete example item",
+  request: {
+    params: itemParamsSchema,
+  },
+  responses: {
+    204: noContentResponse(),
+  },
+});
+
+itemsModule.openapi(listRoute, async c => c.json(ok(await listItems()), 200));
+itemsModule.openapi(getRoute, async c => c.json(ok(await getItem(c.req.param("itemId"))), 200));
+itemsModule.openapi(createRoute, async c => c.json(created(await createItem(await c.req.json())), 201));
+itemsModule.openapi(updateRoute, async c =>
+  c.json(ok(await updateItem(c.req.param("itemId"), await c.req.json())), 200)
+);
+itemsModule.openapi(deleteRoute, async c => {
+  await deleteItem(c.req.param("itemId"));
+  return c.json(noContent(), 204);
+});