@cartanova/qgrid-cli 2.6.7 → 2.6.9

package/bundle/src/application/setting/setting.store.ts

@@ -0,0 +1,85 @@
+/**
+ * 런타임 설정 조회 캐시.
+ *
+ * 값의 출처는 DB(`settings`) → env 순이다. env 를 남겨두는 이유는 전환 때문이다 — dev0 는
+ * `ecosystem.config.json` 으로 값을 주입하는데, DB 만 보게 만들면 배포 직후 설정이 전부
+ * 기본값으로 떨어진다.
+ *
+ * 설정은 요청 경로(워커 스케일링, 알림 전송)에서 읽히므로 매번 DB 를 때리지 않고 메모리에
+ * 둔다. `immediate` 변경도 현재 API 프로세스에만 즉시 반영된다. 인스턴스가 여러 개면 다른
+ * 인스턴스의 캐시는 갱신되지 않으며, 이 범위에서는 프로세스 간 전파를 두지 않는다.
+ */
+import { getLogger } from "@logtape/logtape";
+
+import { SettingModel } from "./setting.model";
+
+const logger = getLogger(["qgrid", "setting"]);
+
+/** 로드 전에는 null 이라 전부 env 로 떨어진다. */
+let cache: Map<string, string> | null = null;
+
+type SettingChangeHandler = (key: string) => void;
+export type SettingPersistence = Pick<
+  typeof SettingModel,
+  "clearByKey" | "findAllAsMap" | "setByKey"
+>;
+let settingChangeHandler: SettingChangeHandler | null = null;
+
+/**
+ * 런타임 소비자는 상위 조립 계층에서 하나만 등록한다. handler 는 동기 작업만 해야 하며,
+ * 실패해도 이미 성공한 DB 저장을 실패로 바꾸지 않는다.
+ */
+export function setSettingChangeHandler(handler: SettingChangeHandler | null): void {
+  settingChangeHandler = handler;
+}
+
+function notifySettingChanged(key: string): void {
+  try {
+    settingChangeHandler?.(key);
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    logger.warn(`setting change handler failed for ${key}: ${message}`);
+  }
+}
+
+export async function loadSettings(persistence: SettingPersistence = SettingModel): Promise<void> {
+  try {
+    cache = await persistence.findAllAsMap();
+    logger.info(`settings loaded: ${cache.size} stored`);
+  } catch (e) {
+    // 테이블이 아직 없는 배포(마이그레이션 전)에서도 서버는 떠야 한다.
+    cache = new Map();
+    logger.warn(`settings load failed, using env only: ${(e as Error).message}`);
+  }
+}
+
+/** DB → env 순. 둘 다 없으면 undefined 라 호출부의 기본값으로 떨어진다. */
+export function getSetting(key: string, envKey: string): string | undefined {
+  return cache?.get(key) ?? process.env[envKey];
+}
+
+/** 저장된 값인지 — 화면에서 출처를 구분해 보여준다. */
+export function isStored(key: string): boolean {
+  return cache?.has(key) ?? false;
+}
+
+export async function saveSetting(
+  key: string,
+  value: string,
+  persistence: SettingPersistence = SettingModel,
+): Promise<void> {
+  await persistence.setByKey(key, value);
+  cache ??= new Map();
+  cache.set(key, value);
+  notifySettingChanged(key);
+}
+
+/** 저장값을 지워 env 기본값으로 되돌린다. */
+export async function resetSetting(
+  key: string,
+  persistence: SettingPersistence = SettingModel,
+): Promise<void> {
+  await persistence.clearByKey(key);
+  cache?.delete(key);
+  notifySettingChanged(key);
+}

package/bundle/src/application/setting/setting.types.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+
+import { SettingBaseSchema, SettingBaseListParams } from "../sonamu.generated";
+
+// Setting - ListParams
+export const SettingListParams = SettingBaseListParams;
+export type SettingListParams = z.infer<typeof SettingListParams>;
+
+// Setting - SaveParams
+export const SettingSaveParams = SettingBaseSchema.partial({ id: true, created_at: true });
+export type SettingSaveParams = z.infer<typeof SettingSaveParams>;
+
+// ── 설정 API 응답 스키마 ──
+
+export const SettingKind = z.enum(["boolean", "integer", "number", "string", "secret", "preset"]);
+export type SettingKind = z.infer<typeof SettingKind>;
+
+export const SettingApplies = z.enum(["immediate", "restart"]);
+export type SettingApplies = z.infer<typeof SettingApplies>;
+
+export const SettingSource = z.enum(["db", "env", "default"]);
+export type SettingSource = z.infer<typeof SettingSource>;
+
+export const SettingItem = z.object({
+  key: z.string(),
+  group: z.string(),
+  label: z.string(),
+  kind: SettingKind,
+  applies: SettingApplies,
+  /** 현재 적용 중인 값. 눈 토글을 지원하기 위해 secret 도 원본으로 내려간다. */
+  value: z.string(),
+  /** 이 값이 어디서 왔는지. 화면에서 출처를 보여줘야 "왜 안 바뀌지"가 없다. */
+  source: SettingSource,
+  min: z.number().nullable(),
+  max: z.number().nullable(),
+  /** `preset` 종류에서 고를 수 있는 값. 다른 종류는 빈 배열. */
+  presets: z.number().array(),
+  help: z.string().nullable(),
+});
+export type SettingItem = z.infer<typeof SettingItem>;
+
+/** 화면에서 바꿀 수 없는 기동 시점 값들 — 어떤 환경에 붙어 있는지 확인용. */
+export const RuntimeInfoItem = z.object({
+  label: z.string(),
+  value: z.string(),
+});
+export type RuntimeInfoItem = z.infer<typeof RuntimeInfoItem>;
+
+export const SettingsResponse = z.object({
+  settings: SettingItem.array(),
+  runtime: RuntimeInfoItem.array(),
+});
+export type SettingsResponse = z.infer<typeof SettingsResponse>;

package/bundle/src/application/sonamu.generated.http

@@ -70,6 +70,60 @@ Content-Type: application/json
 
 ###
 
+GET {{baseUrl}}/api/setting/findById
+	?subset=A
+	&id=0
+Content-Type: application/json
+
+###
+
+GET {{baseUrl}}/api/setting/findMany
+	?subset=A
+	&rawParams[num]=24
+	&rawParams[page]=1
+	&rawParams[search]=key
+	&rawParams[keyword]=KEYWORD
+	&rawParams[orderBy]=key-asc
+	&rawParams[queryMode]=both
+	&rawParams[id]=0
+	&rawParams[sonamuFilter]=unknown-custom
+	&rawParams[key]=KEY
+Content-Type: application/json
+
+###
+
+GET {{baseUrl}}/api/setting/listSettings
+	?
+Content-Type: application/json
+
+###
+
+POST {{baseUrl}}/api/setting/updateSetting
+Content-Type: application/json
+
+{
+  "key": "KEY",
+  "value": "VALUE"
+}
+
+###
+
+POST {{baseUrl}}/api/setting/resetSetting
+Content-Type: application/json
+
+{
+  "key": "KEY"
+}
+
+###
+
+POST {{baseUrl}}/api/setting/triggerExpiryReminder
+Content-Type: application/json
+
+{}
+
+###
+
 GET {{baseUrl}}/api/requestLogStep/findById
 	?subset=A
 	&id=0

package/bundle/src/application/sonamu.generated.sso.ts

@@ -8,9 +8,11 @@ import { type PuriWrapper, type DatabaseSchemaExtend, type PuriLoaderQueries } f
 import {
   type RequestLogSubsetKey,
   type RequestLogStepSubsetKey,
+  type SettingSubsetKey,
   type TokenSubsetKey,
   type RequestLogBaseSchema,
   type RequestLogStepBaseSchema,
+  type SettingBaseSchema,
   type TokenBaseSchema,
 } from "./sonamu.generated";
 
@@ -176,6 +178,24 @@ export const requestLogStepLoaderQueries = {
   I: [],
 } as const satisfies PuriLoaderQueries<RequestLogStepSubsetKey>;
 
+// SubsetQuery: Setting
+export const settingSubsetQueries = {
+  A: (qbWrapper: PuriWrapper<DatabaseSchemaExtend>) => {
+    return qbWrapper.from("settings").select({
+      id: "settings.id",
+      created_at: "settings.created_at",
+      key: "settings.key",
+      value: "settings.value",
+      updated_at: "settings.updated_at",
+    });
+  },
+};
+
+// LoaderQuery: Setting
+export const settingLoaderQueries = {
+  A: [],
+} as const satisfies PuriLoaderQueries<SettingSubsetKey>;
+
 // SubsetQuery: Token
 export const tokenSubsetQueries = {
   A: (qbWrapper: PuriWrapper<DatabaseSchemaExtend>) => {
@@ -206,6 +226,7 @@ declare module "sonamu" {
   export interface DatabaseSchemaExtend {
     request_logs: RequestLogBaseSchema;
     request_log_steps: RequestLogStepBaseSchema;
+    settings: SettingBaseSchema;
     tokens: TokenBaseSchema;
   }
 

package/bundle/src/application/sonamu.generated.ts

@@ -127,6 +127,14 @@ export const RequestLogStepSearchField = z.enum(["id"]).describe("RequestLogStep
 export type RequestLogStepSearchField = z.infer<typeof RequestLogStepSearchField>;
 export const RequestLogStepSearchFieldLabel = { id: "ID" };
 
+// Enums: Setting
+export const SettingOrderBy = z.enum(["key-asc"]).describe("SettingOrderBy");
+export type SettingOrderBy = z.infer<typeof SettingOrderBy>;
+export const SettingOrderByLabel = { "key-asc": "키순" };
+export const SettingSearchField = z.enum(["key"]).describe("SettingSearchField");
+export type SettingSearchField = z.infer<typeof SettingSearchField>;
+export const SettingSearchFieldLabel = { key: "키" };
+
 // Enums: Token
 export const TokenOrderBy = z.enum(["id-desc", "ord-asc"]).describe("TokenOrderBy");
 export type TokenOrderBy = z.infer<typeof TokenOrderBy>;
@@ -262,6 +270,18 @@ export type RequestLogStepBaseSchema = z.infer<typeof RequestLogStepBaseSchema>
   ];
 };
 
+// BaseSchema: Setting
+export const SettingBaseSchema = z.object({
+  id: z.int(),
+  created_at: z.date(),
+  key: z.string().max(100),
+  value: z.string(),
+  updated_at: z.date().nullable(),
+});
+export type SettingBaseSchema = z.infer<typeof SettingBaseSchema> & {
+  readonly __hasDefault__: readonly ["created_at", "updated_at", "id"];
+};
+
 // BaseSchema: Token
 export const TokenBaseSchema = z.object({
   id: z.int(),
@@ -319,6 +339,22 @@ export const RequestLogStepBaseListParams = z
   .partial();
 export type RequestLogStepBaseListParams = z.infer<typeof RequestLogStepBaseListParams>;
 
+// BaseListParams: Setting
+export const SettingBaseListParams = z
+  .object({
+    num: z.number().int().nonnegative(),
+    page: z.number().int().min(1),
+    search: SettingSearchField,
+    keyword: z.string(),
+    orderBy: SettingOrderBy,
+    queryMode: SonamuQueryMode,
+    id: zArrayable(z.number().int().positive()),
+    sonamuFilter: z.custom<ApplySonamuFilter<SettingBaseSchema, never, never>>(),
+    key: z.string().max(100),
+  })
+  .partial();
+export type SettingBaseListParams = z.infer<typeof SettingBaseListParams>;
+
 // BaseListParams: Token
 export const TokenBaseListParams = z
   .object({
@@ -486,6 +522,21 @@ export type RequestLogStepSubsetMapping = {
 export const RequestLogStepSubsetKey = z.enum(["A", "T", "I"]);
 export type RequestLogStepSubsetKey = z.infer<typeof RequestLogStepSubsetKey>;
 
+// Subsets: Setting
+export const SettingSubsetA = z.object({
+  id: z.int(),
+  created_at: z.date(),
+  key: z.string().max(100),
+  value: z.string(),
+  updated_at: z.date().nullable(),
+});
+export type SettingSubsetA = z.infer<typeof SettingSubsetA>;
+export type SettingSubsetMapping = {
+  A: SettingSubsetA;
+};
+export const SettingSubsetKey = z.enum(["A"]);
+export type SettingSubsetKey = z.infer<typeof SettingSubsetKey>;
+
 // Subsets: Token
 export const TokenSubsetA = z.object({
   id: z.int(),

package/bundle/src/i18n/en.ts

@@ -47,6 +47,8 @@ export default {
   "error.internalServerError": "Internal server error",
   "error.notFound": "Not found",
   "error.serviceUnavailable": "Service unavailable",
+  "setting.invalidValue": (reason: string) => `Invalid setting value: ${reason}`,
+  "setting.unknownKey": (key: string) => `Unknown setting key ${key}`,
   "qgrid.dispatcherFailed": (provider: string) => `${provider} dispatcher failed to initialize`,
   "qgrid.dispatcherStarting": (provider: string) =>
     `${provider} dispatcher is starting up. Please retry shortly`,

package/bundle/src/i18n/ko.ts

@@ -46,6 +46,8 @@ export default {
   "error.internalServerError": "서버 오류가 발생했습니다",
   "error.notFound": "찾을 수 없습니다",
   "error.serviceUnavailable": "서비스를 사용할 수 없습니다",
+  "setting.invalidValue": (reason: string) => `설정 값이 올바르지 않습니다: ${reason}`,
+  "setting.unknownKey": (key: string) => `알 수 없는 설정 키 ${key}`,
   "qgrid.dispatcherFailed": (provider: string) => `${provider} dispatcher 초기화에 실패했습니다`,
   "qgrid.dispatcherStarting": (provider: string) =>
     `${provider} dispatcher 기동 중입니다. 잠시 후 다시 시도해주세요`,

package/bundle/src/i18n/sd.generated.ts

@@ -297,6 +297,14 @@ const entityLabels = {
   "enum.RequestLogStepType.tool_call": "Tool 호출",
   "enum.RequestLogStepOrderBy.id-asc": "ID순",
   "enum.RequestLogStepSearchField.id": "ID",
+  "entity.Setting": "Setting",
+  "entity.Setting.id": "ID",
+  "entity.Setting.created_at": "등록일시",
+  "entity.Setting.key": "설정 키 (예: openai.maxWorkersPerToken)",
+  "entity.Setting.value": "설정 값 (문자열 저장, 앱에서 파싱·검증)",
+  "entity.Setting.updated_at": "최종 수정일시",
+  "enum.SettingOrderBy.key-asc": "키순",
+  "enum.SettingSearchField.key": "키",
   "entity.Token": "Token",
   "entity.Token.id": "ID",
   "entity.Token.created_at": "등록일시",

package/bundle/src/migrations/20260808194708_create__settings.ts

@@ -0,0 +1,19 @@
+import { type Knex } from "knex";
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.createTable("settings", (table) => {
+    table.increments().primary();
+    table
+      .timestamp("created_at", { useTz: true, precision: 3 })
+      .notNullable()
+      .defaultTo(knex.raw("CURRENT_TIMESTAMP"));
+    table.string("key", 100).notNullable();
+    table.text("value").notNullable();
+    table.timestamp("updated_at", { useTz: true, precision: 3 }).nullable();
+  });
+  await knex.raw(`CREATE UNIQUE INDEX settings_key_unique ON settings USING btree(key);`);
+}
+
+export async function down(knex: Knex): Promise<void> {
+  return knex.schema.dropTable("settings");
+}

package/bundle/src/sonamu.config.ts

@@ -8,6 +8,7 @@ import { drivers as cacheDrivers, store } from "sonamu/cache";
 
 import { monitLogSink } from "./application/monit/log-buffer";
 import {
+  rescheduleExpiredTokenReminder,
   startExpiredTokenReminder,
   stopExpiredTokenReminder,
 } from "./application/qgrid/expired-token-reminder";
@@ -15,6 +16,7 @@ import { QgridDispatcher } from "./application/qgrid/qgrid.dispatcher";
 import { QgridFrame } from "./application/qgrid/qgrid.frame";
 import { TokenSubscriber } from "./application/qgrid/token-subscriber";
 import { ensureTokensTrigger } from "./application/qgrid/token-trigger-setup";
+import { loadSettings, setSettingChangeHandler } from "./application/setting/setting.store";
 import { handleServerError } from "./server-error-handler";
 import { AnthropicDispatcher } from "./utils/providers/anthropic/anthropic-dispatcher";
 import { OpenAIDispatcher } from "./utils/providers/openai/openai-dispatcher";
@@ -170,6 +172,15 @@ export default defineConfig({
       onStart: async () => {
         const log = getLogger(["qgrid", "startup"]);
 
+        // dispatcher 가 생성자에서 워커 설정을 읽으므로 그 전에 올려야 한다.
+        await loadSettings();
+        // 런타임 설정 소비자를 상위 계층에서 연결해 setting 모듈이 qgrid 를 역참조하지 않게 한다.
+        setSettingChangeHandler((key) => {
+          if (key === "slack.expiryReminderMinutes" || key === "slack.remindersEnabled") {
+            rescheduleExpiredTokenReminder();
+          }
+        });
+
         let triggerReady = true;
         try {
           await ensureTokensTrigger(connConfig);
@@ -221,6 +232,7 @@ export default defineConfig({
       onShutdown: async () => {
         const log = getLogger(["qgrid", "startup"]);
         stopExpiredTokenReminder();
+        setSettingChangeHandler(null);
         if (QgridDispatcher.openaiDispatcher) {
           await QgridDispatcher.openaiDispatcher.stop();
         }

package/bundle/src/utils/providers/openai/openai-dispatcher.test.ts

@@ -251,6 +251,18 @@ describe("OpenAIDispatcher worker capacity", () => {
     expect(estimateOpenAIWorkerRssGiB(50)).toBeCloseTo(8.56, 2);
     expect(estimateOpenAIWorkerRssGiB(60)).toBeCloseTo(10.13, 2);
   });
+
+  it("clamps memory guard inputs to the 64 GiB host policy", () => {
+    expect(
+      resolveOpenAIWorkerPoolConfig({
+        QGRID_OPENAI_MAX_ESTIMATED_RSS_GIB: "999",
+        QGRID_OPENAI_MIN_HOST_AVAILABLE_GIB: "999",
+      }),
+    ).toMatchObject({
+      maxEstimatedRssGiB: 32,
+      minHostAvailableGiB: 64,
+    });
+  });
 });
 
 describe("OpenAIDispatcher monit stats", () => {

package/bundle/src/utils/providers/openai/openai-worker-pool-config.ts

@@ -1,3 +1,10 @@
+import {
+  MAX_OPENAI_ESTIMATED_RSS_GIB,
+  MAX_OPENAI_MIN_HOST_AVAILABLE_GIB,
+  SETTING_DEFS,
+} from "../../../application/setting/setting.constant";
+import { getSetting } from "../../../application/setting/setting.store";
+
 export const MAX_OPENAI_WORKERS_PER_TOKEN = 20;
 const DEFAULT_OPENAI_MIN_WORKERS_PER_TOKEN = 1;
 const DEFAULT_OPENAI_MAX_WORKERS_PER_TOKEN = 3;
@@ -26,14 +33,35 @@ function boundedInteger(
   return Math.max(min, Math.min(Math.floor(parsed), max));
 }
 
-function boundedNumber(value: string | undefined, fallback: number, min: number): number {
+function boundedNumber(
+  value: string | undefined,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
   const parsed = Number(value);
   if (!Number.isFinite(parsed)) return fallback;
-  return Math.max(min, parsed);
+  return Math.max(min, Math.min(parsed, max));
+}
+
+/**
+ * 설정 저장소(DB) 를 먼저 보고 없으면 env 로 떨어지는 조회 객체.
+ *
+ * 기존 파싱 로직이 `env[KEY]` 형태를 전제하므로, 소스만 바꿔 끼우고 검증·기본값 처리는
+ * 그대로 둔다. `get` 접근만 지원하므로 `in`이나 `Object.keys()`로 조회하지 않는다. 테스트는
+ * `env` 인자에 순수한 맵을 넘겨 저장소를 우회한다.
+ */
+function settingsBackedEnv(): Record<string, string | undefined> {
+  return new Proxy({} as Record<string, string | undefined>, {
+    get: (_target, prop: string) => {
+      const def = SETTING_DEFS.find((d) => d.envKey === prop);
+      return def ? getSetting(def.key, def.envKey) : process.env[prop];
+    },
+  });
 }
 
 export function resolveOpenAIWorkerPoolConfig(
-  env: Record<string, string | undefined> = process.env,
+  env: Record<string, string | undefined> = settingsBackedEnv(),
 ): OpenAIWorkerPoolConfig {
   const autoscale = env.QGRID_OPENAI_AUTOSCALE !== "false" && env.QGRID_OPENAI_AUTOSCALE !== "0";
   const minWorkersPerToken = boundedInteger(
@@ -64,8 +92,18 @@ export function resolveOpenAIWorkerPoolConfig(
       1_000,
       24 * 60 * 60_000,
     ),
-    maxEstimatedRssGiB: boundedNumber(env.QGRID_OPENAI_MAX_ESTIMATED_RSS_GIB, 16, 1),
-    minHostAvailableGiB: boundedNumber(env.QGRID_OPENAI_MIN_HOST_AVAILABLE_GIB, 20, 0),
+    maxEstimatedRssGiB: boundedNumber(
+      env.QGRID_OPENAI_MAX_ESTIMATED_RSS_GIB,
+      16,
+      1,
+      MAX_OPENAI_ESTIMATED_RSS_GIB,
+    ),
+    minHostAvailableGiB: boundedNumber(
+      env.QGRID_OPENAI_MIN_HOST_AVAILABLE_GIB,
+      20,
+      0,
+      MAX_OPENAI_MIN_HOST_AVAILABLE_GIB,
+    ),
   };
 }
 

package/bundle/src/utils/quiet-hours.ts

@@ -0,0 +1,79 @@
+/**
+ * Slack 알림 조용 시간.
+ *
+ * 토큰 만료는 사람이 재로그인해야 풀리는데, 그 사람이 자거나 쉬는 동안 알려도 할 수 있는
+ * 일이 없다. 업무 시간에만 알리고 나머지는 다음 근무 시간으로 미룬다 — 만료 알림은
+ * 주기적으로 반복되므로 조용 시간에 버려도 아침 첫 주기에 다시 온다.
+ *
+ * 다만 provider 의 마지막 토큰이 죽는 것은 서비스 정지 신호라 이 규칙에서 제외한다
+ * (호출부가 `urgent: true` 로 보내면 된다).
+ */
+import { type getSetting } from "../application/setting/setting.store";
+
+/**
+ * 설정 조회 함수의 형태만 빌린다 — `type` import 라 런타임 의존이 생기지 않는다.
+ *
+ * 값 자체는 항상 호출부(`slack-notify`)가 넘긴다. 여기서 `getSetting` 을 실제로 import 하면
+ * `setting.store → setting.model → token.model` 이 딸려와, `token.model` 을 mock 하는
+ * 테스트들이 실제 모듈을 먼저 로드해 버린다. 조용 시간 판정은 시각 계산이지 설정 조회가
+ * 아니므로, 읽는 책임은 이미 설정을 읽고 있는 호출부에 둔다.
+ */
+type ReadSetting = typeof getSetting;
+
+/** `setting.constant.ts` 의 두 fallback 과 같아야 한다. 일치 여부는 테스트가 지킨다. */
+export const DEFAULT_QUIET_FROM_HOUR = 20;
+export const DEFAULT_QUIET_UNTIL_HOUR = 8;
+
+/**
+ * 서버가 UTC 로 돌아도 한국 시간으로 판정한다. dev0 는 UTC 이므로 `getHours()` 를 그대로
+ * 쓰면 "저녁 8시"가 한국 시간 새벽 5시가 된다.
+ */
+const SEOUL_FORMATTER = new Intl.DateTimeFormat("en-US", {
+  timeZone: "Asia/Seoul",
+  hour: "numeric",
+  hour12: false,
+  weekday: "short",
+});
+
+function seoulParts(at: Date): { hour: number; weekday: string } {
+  const parts = SEOUL_FORMATTER.formatToParts(at);
+  const hour = Number(parts.find((p) => p.type === "hour")?.value ?? "0");
+  const weekday = parts.find((p) => p.type === "weekday")?.value ?? "";
+  // Intl 은 자정을 24 로 줄 수 있다. 0..23 으로 맞춘다.
+  return { hour: hour % 24, weekday };
+}
+
+/** 0..23 범위를 벗어나거나 숫자가 아니면 기본값으로 떨어진다. */
+function boundedHour(raw: string | undefined, fallback: number): number {
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 23) return fallback;
+  return parsed;
+}
+
+/**
+ * 조용 시간인지 판정한다.
+ *
+ * 시작 > 종료면 자정을 넘는 구간(20시~익일 8시), 시작 < 종료면 같은 날 구간(0시~8시처럼)
+ * 으로 읽는다. 야간 근무처럼 낮에 조용하고 싶은 팀도 있어 뒤집힌 값을 막지 않는다.
+ */
+export function isQuietHours(at: Date, readSetting: ReadSetting): boolean {
+  const { hour, weekday } = seoulParts(at);
+
+  const isWeekend = weekday === "Sat" || weekday === "Sun";
+  if (isWeekend && readSetting("slack.notifyOnWeekends", "SLACK_NOTIFY_ON_WEEKENDS") !== "true") {
+    return true;
+  }
+
+  const from = boundedHour(
+    readSetting("slack.quietFromHour", "SLACK_QUIET_FROM_HOUR"),
+    DEFAULT_QUIET_FROM_HOUR,
+  );
+  const until = boundedHour(
+    readSetting("slack.quietUntilHour", "SLACK_QUIET_UNTIL_HOUR"),
+    DEFAULT_QUIET_UNTIL_HOUR,
+  );
+
+  // 시작과 종료가 같으면 구간이 비어 있다는 뜻으로 읽어 조용 시간을 두지 않는다.
+  if (from === until) return false;
+  return from > until ? hour >= from || hour < until : hour >= from && hour < until;
+}