@cartanova/qgrid-cli 2.8.0 → 2.9.1

package/bundle/src/application/token/token.entity.json

@@ -14,6 +14,12 @@
     },
     { "name": "name", "desc": "토큰 이름", "type": "string" },
     { "name": "active", "type": "boolean", "desc": "활성 여부", "dbDefault": "true" },
+    {
+      "name": "reauth_required",
+      "type": "boolean",
+      "desc": "인증 만료로 재로그인이 필요한지 여부",
+      "dbDefault": "false"
+    },
     { "name": "ord", "type": "integer", "desc": "정렬 순서", "dbDefault": "0" },
     {
       "name": "quota_threshold",
@@ -50,6 +56,7 @@
       "credentials",
       "name",
       "active",
+      "reauth_required",
       "ord",
       "quota_threshold",
       "weight",

package/bundle/src/application/token/token.model.test.ts

@@ -1,4 +1,7 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { randomUUID } from "node:crypto";
+
+import { Sonamu } from "sonamu";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
 
 import { TokenModel } from "./token.model";
 
@@ -122,6 +125,7 @@ describe("TokenModel.replaceByAccount", () => {
         id: 1,
         created_at: new Date(),
         active: true,
+        reauth_required: false,
         ord: 0,
         quota_threshold: 80,
         weight: 1,
@@ -177,51 +181,122 @@ describe("TokenModel.findActiveByProviderAndName", () => {
   });
 });
 
-describe("TokenModel.deactivateIfActive", () => {
+describe("TokenModel.findReauthRequired", () => {
   afterEach(() => {
     vi.restoreAllMocks();
   });
 
-  function mockKnex(responses: unknown[]) {
-    const raw = vi.fn();
-    for (const response of responses) raw.mockResolvedValueOnce(response);
-    vi.spyOn(TokenModel as unknown as { getPuri: (mode: "w") => unknown }, "getPuri").mockReturnValue(
-      { knex: { raw } } as unknown as MockPuri,
-    );
-    return raw;
-  }
+  it("queries auth-dead tokens instead of every inactive token", async () => {
+    const where = vi.fn();
+    const orderBy = vi.fn();
+    const qb = { where, orderBy };
+    vi.spyOn(
+      TokenModel as unknown as { getSubsetQueries: (subset: "A") => { qb: typeof qb } },
+      "getSubsetQueries",
+    ).mockReturnValue({ qb });
+    vi.spyOn(
+      TokenModel as unknown as {
+        executeSubsetQuery: (input: unknown) => Promise<{ rows: unknown[] }>;
+      },
+      "executeSubsetQuery",
+    ).mockResolvedValue({ rows: [] });
 
-  it("deactivates in one statement that carries the last-token guard", async () => {
-    const raw = mockKnex([{ rowCount: 1 }]);
+    await TokenModel.findReauthRequired("A");
 
-    await expect(TokenModel.deactivateIfActive(7)).resolves.toEqual({
-      deactivated: true,
-      keptAsLastActive: false,
-    });
-    expect(raw).toHaveBeenCalledTimes(1);
-    const sql = raw.mock.calls[0]![0] as string;
-    expect(sql).toContain("UPDATE tokens SET active = false");
-    expect(sql).toContain("count(*)");
+    expect(where).toHaveBeenCalledWith("tokens.reauth_required", true);
+    expect(where).not.toHaveBeenCalledWith("tokens.active", false);
   });
+});
 
-  it("returns false without a diagnostic read when the token is already inactive", async () => {
-    const raw = mockKnex([{ rowCount: 0 }, { rows: [] }]);
-
-    await expect(TokenModel.deactivateIfActive(7)).resolves.toEqual({
-      deactivated: false,
-      keptAsLastActive: false,
-    });
-    expect(raw).toHaveBeenCalledTimes(2);
+describe("TokenModel.markReauthRequired", () => {
+  beforeAll(async () => {
+    await Sonamu.initForTesting();
   });
 
-  it("refuses to deactivate the provider's last active token", async () => {
-    const raw = mockKnex([{ rowCount: 0 }, { rows: [{ provider: "anthropic" }] }]);
-
-    // 마지막 활성 토큰은 살려두되, 호출부가 systemic 실패로 알릴 수 있게 구분해 알린다.
-    await expect(TokenModel.deactivateIfActive(7)).resolves.toEqual({
-      deactivated: false,
-      keptAsLastActive: true,
-    });
-    expect(raw).toHaveBeenCalledTimes(2);
+  it("serializes provider deaths, preserves one active token, and rejects stale credentials", async () => {
+    const suffix = randomUUID();
+    const tokens = [
+      {
+        ...baseToken,
+        name: `auth-state-a-${suffix}`,
+        credentials: { ...baseToken.credentials, accountUuid: `account-a-${suffix}` },
+      },
+      {
+        ...baseToken,
+        name: `auth-state-b-${suffix}`,
+        credentials: { ...baseToken.credentials, accountUuid: `account-b-${suffix}` },
+      },
+    ];
+    const ids = await TokenModel.save(tokens);
+
+    try {
+      await expect(
+        TokenModel.markReauthRequired(ids[0]!, {
+          ...tokens[0]!.credentials,
+          accessToken: "stale-access-token",
+        }),
+      ).resolves.toEqual({
+        marked: false,
+        keptAsLastActive: false,
+        staleCredentials: true,
+      });
+
+      const results = await Promise.all([
+        TokenModel.markReauthRequired(ids[0]!, tokens[0]!.credentials),
+        TokenModel.markReauthRequired(ids[1]!, tokens[1]!.credentials),
+      ]);
+      expect(results.every((result) => result.marked)).toBe(true);
+
+      const { rows } = await TokenModel.findMany("A", { id: ids, num: 2 });
+      expect(rows.every((row) => row.reauth_required)).toBe(true);
+      expect(rows.filter((row) => row.active)).toHaveLength(1);
+
+      await expect(
+        TokenModel.markReauthRequired(ids[0]!, tokens[0]!.credentials),
+      ).resolves.toEqual({
+        marked: false,
+        keptAsLastActive: false,
+        staleCredentials: false,
+      });
+
+      const inactive = rows.find((row) => !row.active)!;
+      const refreshedCredentials = {
+        ...inactive.credentials,
+        accessToken: "refreshed-access-token",
+        refreshToken: "refreshed-refresh-token",
+      };
+      await TokenModel.save([
+        {
+          id: inactive.id,
+          provider: inactive.provider,
+          credentials: refreshedCredentials,
+          name: inactive.name,
+          reauth_required: false,
+        },
+      ]);
+      await expect(
+        TokenModel.markReauthRequired(inactive.id, inactive.credentials),
+      ).resolves.toEqual({
+        marked: false,
+        keptAsLastActive: false,
+        staleCredentials: true,
+      });
+
+      await expect(TokenModel.toggleActive(inactive.id)).resolves.toEqual({
+        active: true,
+        reauthRequired: false,
+      });
+      await TokenModel.toggleActive(inactive.id);
+      await Promise.all([
+        TokenModel.toggleActive(inactive.id),
+        TokenModel.markReauthRequired(inactive.id, refreshedCredentials),
+      ]);
+      await expect(TokenModel.findById("A", inactive.id)).resolves.toMatchObject({
+        active: false,
+        reauth_required: true,
+      });
+    } finally {
+      await TokenModel.del(ids);
+    }
   });
 });

package/bundle/src/application/token/token.model.ts

@@ -1,3 +1,5 @@
+import { isDeepStrictEqual } from "node:util";
+
 import { getLogger } from "@logtape/logtape";
 import {
   api,
@@ -12,12 +14,13 @@ import {
 import { SD } from "../../i18n/sd.generated";
 import { type TokenSubsetKey, type TokenSubsetMapping } from "../sonamu.generated";
 import { tokenLoaderQueries, tokenSubsetQueries } from "../sonamu.generated.sso";
-import { type TokenListParams, type TokenSaveParams } from "./token.types";
+import { type TokenCredentials, type TokenListParams, type TokenSaveParams } from "./token.types";
 
 const logger = getLogger(["qgrid", "token"]);
 
 const DEFAULT_QUOTA_THRESHOLD = 80;
 const DEFAULT_WEIGHT = 1;
+const TOKEN_AUTH_DEATH_LOCK_CLASS_ID = 719;
 
 export type TokenUpdateFields = {
   name?: string;
@@ -167,13 +170,10 @@ class TokenModelClass extends BaseModelClass<
     return result.rows[0];
   }
 
-  /**
-   * 라우팅에서 빠진 토큰들. 세션 만료로 자동 비활성화된 것과 수동으로 끈 것이 섞여 있다 —
-   * 둘 다 "재로그인하면 살아나는" 상태라 알림 대상으로는 같게 본다.
-   */
-  async findInactive<T extends TokenSubsetKey>(subset: T): Promise<TokenSubsetMapping[T][]> {
+  /** 실제 인증 만료가 확인돼 재로그인이 필요한 토큰들. 수동 비활성화는 제외한다. */
+  async findReauthRequired<T extends TokenSubsetKey>(subset: T): Promise<TokenSubsetMapping[T][]> {
     const { qb } = this.getSubsetQueries(subset);
-    qb.where("tokens.active", false);
+    qb.where("tokens.reauth_required", true);
     qb.orderBy("tokens.name", "asc");
     const enhancers = this.createEnhancers({ A: (row) => ({ ...row }) });
     const result = await this.executeSubsetQuery({
@@ -200,7 +200,6 @@ class TokenModelClass extends BaseModelClass<
     return result.rows;
   }
 
-  @api({ httpMethod: "POST", clients: ["axios", "tanstack-mutation"] })
   async save(spa: TokenSaveParams[]): Promise<number[]> {
     const wdb = this.getPuri("w");
     spa.forEach((sp) => {
@@ -216,15 +215,26 @@ class TokenModelClass extends BaseModelClass<
     return wdb.transaction((trx) => trx.table("tokens").where("id", id).update(fields));
   }
 
-  /**
-   * 세션 만료 토큰을 라우팅에서 제외한다. `active=true` 조건부 갱신이므로 공유 DB 를 쓰는
-   * 여러 인스턴스가 동시에 같은 만료를 감지해도 true 를 받는 프로세스는 하나뿐이다
-   * (호출부의 알림 발송 게이트).
-   *
-   * 단, 대상이 해당 provider 의 마지막 활성 토큰이면 갱신하지 않고 false 를 반환한다.
-   * client_id 취소나 OAuth 계약 변경처럼 전 토큰이 동시에 실패하는 상황에서 풀이
-   * 통째로 비는 것을 막는 안전판이다.
-   */
+  async toggleActive(id: number): Promise<{ active: boolean; reauthRequired: boolean } | null> {
+    const wdb = this.getPuri("w");
+    return wdb.transaction(async (trx) => {
+      const token = await trx
+        .from("tokens")
+        .select({ active: "active", reauth_required: "reauth_required" })
+        .where("id", id)
+        .forUpdate()
+        .first();
+      if (!token) return null;
+      if (!token.active && token.reauth_required) {
+        return { active: false, reauthRequired: true };
+      }
+
+      const active = !token.active;
+      await trx.from("tokens").where("id", id).update({ active });
+      return { active, reauthRequired: false };
+    });
+  }
+
   /**
    * 같은 계정의 기존 토큰을 지우고 새로 저장한다(로그인·재로그인 공통 경로).
    *
@@ -257,43 +267,61 @@ class TokenModelClass extends BaseModelClass<
   }
 
   /**
-   * @returns `deactivated` 는 이 호출이 실제로 비활성화를 수행했는지 — 호출부의 알림
-   *   게이트다. `keptAsLastActive` 는 마지막 활성 토큰이라 거부한 경우로, 사망 자체는
-   *   사실이지만 풀을 비우지 않으려고 살려둔 상태다(systemic 실패 신호).
+   * 인증 사망을 한 번만 기록하고, 다른 활성 토큰이 있으면 라우팅에서도 제외한다.
+   * 마지막 활성 토큰은 systemic 장애 안전판 때문에 active 상태를 유지하되 재로그인
+   * 필요 상태는 기록한다. `marked`가 공유 DB 인스턴스들의 알림 발송 게이트다.
    */
-  async deactivateIfActive(
+  async markReauthRequired(
     id: number,
-  ): Promise<{ deactivated: boolean; keptAsLastActive: boolean }> {
+    expectedCredentials: TokenCredentials,
+  ): Promise<{ marked: boolean; keptAsLastActive: boolean; staleCredentials: boolean }> {
     const wdb = this.getPuri("w");
+    return wdb.transaction(async (trx) => {
+      const token = await trx
+        .from("tokens")
+        .select({
+          provider: "provider",
+          credentials: "credentials",
+          reauth_required: "reauth_required",
+        })
+        .where("id", id)
+        .forUpdate()
+        .first();
+      if (!token || token.reauth_required) {
+        return { marked: false, keptAsLastActive: false, staleCredentials: false };
+      }
+      if (!isDeepStrictEqual(token.credentials, expectedCredentials)) {
+        return { marked: false, keptAsLastActive: false, staleCredentials: true };
+      }
 
-    // 활성 여부와 "마지막 남은 토큰인가"를 한 statement 안에서 판정한다. 두 조건을
-    // 따로 읽고 나중에 갱신하면 그 사이에 다른 인스턴스가 같은 provider 의 토큰을
-    // 비활성화해 풀이 통째로 빌 수 있다.
-    const updated = await wdb.knex.raw<{ rowCount: number }>(
-      `UPDATE tokens SET active = false
-       WHERE id = ? AND active = true
-         AND (SELECT count(*) FROM tokens peer
-              WHERE peer.provider = tokens.provider AND peer.active) > 1`,
-      [id],
-    );
-    if ((updated.rowCount ?? 0) > 0) return { deactivated: true, keptAsLastActive: false };
-
-    // 갱신되지 않은 이유는 둘 중 하나다: 이미 비활성이거나(정상 경쟁 결과), 마지막
-    // 활성 토큰이거나. 후자는 systemic 실패 신호라 남겨야 하므로 이때만 한 번 더 읽는다.
-    const survivor = (
-      await wdb.knex.raw<{ rows: { provider: string }[] }>(
-        "SELECT provider FROM tokens WHERE id = ? AND active = true",
+      await trx.knex.raw("SELECT pg_advisory_xact_lock(?, hashtext(?))", [
+        TOKEN_AUTH_DEATH_LOCK_CLASS_ID,
+        token.provider,
+      ]);
+      const updated = await trx.knex.raw<{ rows: { active: boolean }[] }>(
+        `UPDATE tokens
+         SET reauth_required = true,
+             active = CASE
+               WHEN active AND (SELECT count(*) FROM tokens peer
+                 WHERE peer.provider = tokens.provider AND peer.active) > 1
+               THEN false
+               ELSE active
+             END
+         WHERE id = ? AND reauth_required = false
+         RETURNING active`,
         [id],
-      )
-    ).rows[0];
-    if (survivor) {
-      logger.error(
-        `refusing to auto-deactivate token ${id}: last active ${survivor.provider} token — ` +
-          `systemic refresh failure suspected, keeping the pool non-empty`,
       );
-      return { deactivated: false, keptAsLastActive: true };
-    }
-    return { deactivated: false, keptAsLastActive: false };
+      const marked = updated.rows[0];
+      if (!marked) return { marked: false, keptAsLastActive: false, staleCredentials: false };
+
+      if (marked.active) {
+        logger.error(
+          `refusing to auto-deactivate token ${id}: last active provider token — ` +
+            `systemic refresh failure suspected, keeping the pool non-empty`,
+        );
+      }
+      return { marked: true, keptAsLastActive: marked.active, staleCredentials: false };
+    });
   }
 
   @api({ httpMethod: "POST", clients: ["axios", "tanstack-mutation"] })

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

@@ -38,6 +38,7 @@ export const TokenSaveParams = TokenBaseSchema.partial({
   id: true,
   created_at: true,
   active: true,
+  reauth_required: true,
   ord: true,
   quota_threshold: true,
   weight: true,

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

@@ -317,6 +317,7 @@ const entityLabels = {
   "entity.Token.credentials": "인증 정보 (JSONB)",
   "entity.Token.name": "토큰 이름",
   "entity.Token.active": "활성 여부",
+  "entity.Token.reauth_required": "인증 만료로 재로그인이 필요한지 여부",
   "entity.Token.ord": "정렬 순서",
   "entity.Token.quota_threshold": "quota 사용률 임계치(%). null이면 미설정",
   "entity.Token.weight": "가중 라운드로빈 라우팅 가중치 (1..100)",

package/bundle/src/migrations/20260901163614_alter_tokens_add1_alter1.ts

@@ -0,0 +1,15 @@
+import { type Knex } from "knex";
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.alterTable("tokens", (table) => {
+    // add
+    table.boolean("reauth_required").notNullable().defaultTo(knex.raw("false"));
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.alterTable("tokens", (table) => {
+    // rollback - add
+    table.dropColumns("reauth_required");
+  });
+}

package/bundle/src/startup-migrations.test.ts

@@ -1,4 +1,8 @@
-import { describe, expect, it, vi } from "vitest";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
 
 const { latest } = vi.hoisted(() => ({ latest: vi.fn() }));
 
@@ -8,17 +12,126 @@ vi.mock("./application/token/token.model", () => ({
   },
 }));
 
-import { runRequiredMigrations } from "./startup-migrations";
+import {
+  createStartupMigrationSource,
+  resolveStartupMigrationDirs,
+  runRequiredMigrations,
+} from "./startup-migrations";
+
+const tempRoots: string[] = [];
+
+async function makeDirs() {
+  const root = await mkdtemp(path.join(os.tmpdir(), "qgrid-startup-migrations-"));
+  tempRoots.push(root);
+  const sourceDir = path.join(root, "src", "migrations");
+  const compiledDir = path.join(root, "dist", "migrations");
+  await mkdir(sourceDir, { recursive: true });
+  await mkdir(compiledDir, { recursive: true });
+  return { sourceDir, compiledDir };
+}
+
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("resolveStartupMigrationDirs", () => {
+  it("패키지된 CLI(dist 실행)에서는 이름은 bundle/src, 모듈은 bundle/dist 를 가리킨다", () => {
+    expect(resolveStartupMigrationDirs("/opt/qgrid-cli/bundle/dist")).toEqual({
+      sourceDir: "/opt/qgrid-cli/bundle/src/migrations",
+      compiledDir: "/opt/qgrid-cli/bundle/dist/migrations",
+    });
+  });
+
+  it("소스 실행(src)에서는 두 경로가 같은 src/migrations 다", () => {
+    expect(resolveStartupMigrationDirs("/repo/packages/api/src")).toEqual({
+      sourceDir: "/repo/packages/api/src/migrations",
+      compiledDir: "/repo/packages/api/src/migrations",
+    });
+  });
+});
+
+describe("createStartupMigrationSource", () => {
+  it("knex_migrations 에 기록된 것과 같은 .ts 파일명을 정렬해 나열하고 그 외 파일은 무시한다", async () => {
+    const dirs = await makeDirs();
+    await writeFile(path.join(dirs.sourceDir, "20260901163614_alter_tokens_add1_alter1.ts"), "");
+    await writeFile(path.join(dirs.sourceDir, "20260820153531_alter_tokens_add1_alter1.ts"), "");
+    await writeFile(path.join(dirs.sourceDir, "20260820153531_alter_tokens_add1_alter1.d.ts"), "");
+    await writeFile(path.join(dirs.sourceDir, "README.md"), "");
+
+    const source = createStartupMigrationSource(dirs);
+    const names = await source.getMigrations([]);
+
+    expect(names).toEqual([
+      "20260820153531_alter_tokens_add1_alter1.ts",
+      "20260901163614_alter_tokens_add1_alter1.ts",
+    ]);
+    expect(source.getMigrationName("20260820153531_alter_tokens_add1_alter1.ts")).toBe(
+      "20260820153531_alter_tokens_add1_alter1.ts",
+    );
+  });
+
+  it("컴파일된 .js 가 있으면 .ts 대신 그것을 로드한다 (2.9.0 부팅 크래시 재발 방지)", async () => {
+    const dirs = await makeDirs();
+    const name = "20260901163614_alter_tokens_add1_alter1.ts";
+    await writeFile(path.join(dirs.sourceDir, name), 'throw new Error("source .ts must not load");\n');
+    await writeFile(
+      path.join(dirs.compiledDir, name.replace(/\.ts$/, ".js")),
+      'export async function up() { return "compiled"; }\nexport async function down() { return "down"; }\n',
+    );
+
+    const migration = await createStartupMigrationSource(dirs).getMigration(name);
+
+    await expect(migration.up({} as never)).resolves.toBe("compiled");
+    await expect(migration.down?.({} as never)).resolves.toBe("down");
+  });
+
+  it("컴파일 산출물이 없으면 소스 모듈로 fallback 한다 (ts loader 가 있는 소스 실행)", async () => {
+    const dirs = await makeDirs();
+    const name = "20260901163614_alter_tokens_add1_alter1.ts";
+    await writeFile(
+      path.join(dirs.sourceDir, name),
+      'export async function up() { return "source"; }\n',
+    );
+
+    const migration = await createStartupMigrationSource(dirs).getMigration(name);
+
+    await expect(migration.up({} as never)).resolves.toBe("source");
+    await expect(migration.down?.({} as never)).resolves.toBeUndefined();
+  });
+
+  it("up() 이 없는 모듈은 명확한 오류로 실패한다", async () => {
+    const dirs = await makeDirs();
+    const name = "20260901163614_alter_tokens_add1_alter1.ts";
+    await writeFile(path.join(dirs.compiledDir, name.replace(/\.ts$/, ".js")), "export const x = 1;\n");
+
+    await expect(createStartupMigrationSource(dirs).getMigration(name)).rejects.toThrow(
+      /has no up\(\) export/,
+    );
+  });
+});
 
 describe("required startup migrations", () => {
+  it("knex 기본 directory 대신 migrationSource 로 latest 를 실행한다", async () => {
+    const dirs = await makeDirs();
+    latest.mockResolvedValueOnce([3, ["20260901163614_alter_tokens_add1_alter1.ts"]]);
+
+    await runRequiredMigrations(dirs);
+
+    expect(latest).toHaveBeenCalledWith({ migrationSource: expect.any(Object) });
+    const call = latest.mock.calls.at(-1)?.[0] as { migrationSource: unknown; directory?: string };
+    expect(call.directory).toBeUndefined();
+  });
+
   it("terminates with a failure status when migration fails", async () => {
+    const dirs = await makeDirs();
     const failure = new Error("tokens.weight migration failed");
     const exit = vi.spyOn(process, "exit").mockImplementation(() => {
       throw failure;
     });
     latest.mockRejectedValueOnce(failure);
 
-    await expect(runRequiredMigrations()).rejects.toBe(failure);
+    await expect(runRequiredMigrations(dirs)).rejects.toBe(failure);
 
     expect(exit).toHaveBeenCalledWith(1);
   });

package/bundle/src/startup-migrations.ts

@@ -1,15 +1,82 @@
+import { existsSync } from "node:fs";
+import { readdir } from "node:fs/promises";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 
 import { getLogger } from "@logtape/logtape";
+import { type Knex } from "knex";
 
 import { TokenModel } from "./application/token/token.model";
 
-export async function runRequiredMigrations(): Promise<void> {
+export type StartupMigrationDirs = {
+  /** Sonamu 가 migration 을 생성·기록하는 원본 디렉터리. `knex_migrations.name` 은 이 파일명(`.ts`)이다. */
+  sourceDir: string;
+  /** 빌드 산출물 디렉터리. dist 에서 실행 중이면 같은 이름의 `.js` 가 여기 있다. */
+  compiledDir: string;
+};
+
+// import.meta.dirname 은 소스 실행(ts loader)에서는 `src/`, 패키지된 CLI 에서는 `bundle/dist/` 다.
+// 두 경우 모두 `../src/migrations` 가 이름의 정본이고 `./migrations` 가 컴파일 산출물 위치다.
+// 소스 실행에서는 둘이 같은 디렉터리라 컴파일 파일이 없고, `.ts` 를 loader 가 직접 읽는다.
+export function resolveStartupMigrationDirs(
+  moduleDir: string = import.meta.dirname,
+): StartupMigrationDirs {
+  return {
+    sourceDir: path.join(moduleDir, "../src/migrations"),
+    compiledDir: path.join(moduleDir, "migrations"),
+  };
+}
+
+// Sonamu 가 만드는 파일명 규칙: `YYYYMMDDHHmmss_<title>.ts`. 타입 선언이나 README 는 제외한다.
+const MIGRATION_FILE_RE = /^\d{14}_.+\.ts$/;
+
+type MigrationModule = {
+  up?: (knex: Knex) => Promise<unknown>;
+  down?: (knex: Knex) => Promise<unknown>;
+};
+
+/**
+ * 패키지된 CLI 는 `bundle/dist` 에서 실행되는데, knex 기본 FsMigrations 에 `../src/migrations` 를
+ * 넘기면 pending migration 을 `.ts` 로 import 하다 "Unknown file extension .ts" 로 죽는다(2.9.0 사고).
+ * 반대로 디렉터리를 `dist/migrations` 로 바꾸면 `knex_migrations` 에 `.ts` 이름으로 기록된 과거
+ * migration 이 전부 pending 으로 보인다. 그래서 이름은 `src/migrations` 의 `.ts` 파일명을 그대로
+ * 쓰고, 모듈만 컴파일된 `.js` 가 있으면 그것을 로드한다.
+ */
+export function createStartupMigrationSource(
+  dirs: StartupMigrationDirs,
+): Knex.MigrationSource<string> {
+  return {
+    async getMigrations() {
+      const entries = await readdir(dirs.sourceDir);
+      return entries
+        .filter((name) => MIGRATION_FILE_RE.test(name) && !name.endsWith(".d.ts"))
+        .sort();
+    },
+    getMigrationName(name) {
+      return name;
+    },
+    async getMigration(name) {
+      const compiled = path.join(dirs.compiledDir, name.replace(/\.ts$/, ".js"));
+      const source = path.join(dirs.sourceDir, name);
+      const target = existsSync(compiled) ? compiled : source;
+      const module = (await import(pathToFileURL(target).href)) as MigrationModule;
+      if (typeof module.up !== "function") {
+        throw new Error(`migration ${name} has no up() export (${target})`);
+      }
+      return { up: module.up, down: module.down ?? (async () => undefined) };
+    },
+  };
+}
+
+export async function runRequiredMigrations(
+  dirs: StartupMigrationDirs = resolveStartupMigrationDirs(),
+): Promise<void> {
   const log = getLogger(["qgrid", "startup"]);
   try {
     const knex = TokenModel.getDB("w");
-    const migrationsDir = path.join(import.meta.dirname, "../src/migrations");
-    const [batch, migrations] = await knex.migrate.latest({ directory: migrationsDir });
+    const [batch, migrations] = await knex.migrate.latest({
+      migrationSource: createStartupMigrationSource(dirs),
+    });
     if (migrations.length > 0) {
       log.info(`migration: ${migrations.length} applied (batch ${batch})`);
     }