import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
import path from "node:path";
import process from "node:process";
import { chromium, type APIRequestContext, type BrowserContext, type Page } from "@playwright/test";
import { TECH_LOG_ROUTE_REGISTRY } from "../src/features/tech-log/contracts/tech-log-route-contract.ts";
/**
* 공개 화면과 Studio 화면 전부를 찍는다. UI 검토용이다.
*
*
찍을 목록을 손으로 적지 않는다. 라우트 레지스트리를 그대로 돌고, 라우트 하나당 해석기를
* {@link RESOLVERS} 에 반드시 하나 두게 한다 — `Record` 라 라우트가 늘면 컴파일러가
* 빈 자리를 잡는다. 이 저장소에서 손으로 나열한 목록에 새 항목을 빠뜨리는 일이 반복됐고(종류
* 필터에서 개념·환경 구성이 빠졌던 것이 같은 실수다), 검토용 목록이 조용히 낡으면 "찍히지 않은
* 화면은 문제가 없는 것처럼" 보인다.
*
* `:slug` 같은 자리는 지어내지 않고 살아 있는 API 에서 실제 값을 가져온다. 지어낸 주소는
* 404 화면을 찍어 놓고 검토가 끝난 것처럼 보이게 만든다. 채울 값이 없으면 건너뛰되 그 사실을
* 결과에 남긴다.
*
*
Studio 는 로그인이 필요하다. 세션을 파일로 저장해 두고 재사용하며, 매 화면마다 로그인 관문
* (`[data-surface="authentication-required"]`)이 아닌지 확인한다 — 세션이 끊긴 채로 돌면 같은
* 로그인 화면 수십 장을 찍어 놓고 Studio 를 다 봤다고 착각한다.
*
* 사용법:
* node scripts/capture-screens.ts --login # 창을 열어 직접 로그인하고 세션 저장
* node scripts/capture-screens.ts # 공개 + Studio 전부
* node scripts/capture-screens.ts --only=public
* node scripts/capture-screens.ts --widths=1440 --slices=3
* node scripts/capture-screens.ts --base=http://localhost:5173
*/
type RouteId = keyof typeof TECH_LOG_ROUTE_REGISTRY;
const DEFAULT_BASE = "https://hyeonworks.com";
/** 이 사이트의 반응형 분기는 1179 / 1050 / 900 / 767 이다. 그 위와 아래를 하나씩 본다. */
const DEFAULT_WIDTHS = [1440, 390] as const;
const VIEWPORT_HEIGHT = 900;
/** 한 폭당 이만큼까지만 자른다. 긴 문서라도 검토는 앞쪽에서 대부분 끝난다. */
const DEFAULT_SLICES = 5;
const OUTPUT_DIRECTORY = "artifacts/design-review/screens";
const SESSION_FILE = "artifacts/design-review/studio-session.json";
/** 로그인 관문. 이것이 보이면 그 화면은 Studio 화면이 아니라 로그인 화면이다. */
const AUTH_GATE = '[data-surface="authentication-required"]';
type LiveData = {
/** 종류별 공개 경로 한 개씩. 값이 없으면 그 종류로 게시된 기록이 아직 없다는 뜻이다. */
readonly knowledgePaths: Readonly>;
readonly questionPath: string | null;
readonly topicSlug: string | null;
/** 접근(variant)을 가진 주제와 그 접근 하나. 접근이 없는 주제만 있으면 null 이다. */
readonly topicWithVariant: Readonly<{ slug: string; variant: string }> | null;
readonly projectSlug: string | null;
readonly releaseVersion: string | null;
readonly documentId: string | null;
readonly publicationEventId: string | null;
readonly studioProjectId: string | null;
readonly studioTopicId: string | null;
readonly studioReleaseId: string | null;
};
type Resolver = (data: LiveData) => string | null;
function knowledge(kind: string): Resolver {
return (data) => data.knowledgePaths[kind] ?? null;
}
/**
* 라우트 하나를 실제 주소로 바꾸는 법.
*
* `null` 은 "지금 살아 있는 자료로는 이 화면을 열 수 없다"는 뜻이다. 결과 보고서에 이유와 함께
* 남는다 — 조용히 빠지면 검토에서 그 화면이 없었다는 사실 자체가 보이지 않는다.
*/
const RESOLVERS: Record = {
TECH_LOG_HOME: () => "/",
TECH_LOG_EXPLORE: () => "/explore",
// `/explore/:kind` 는 두 갈래가 화면이 서로 다르다. 둘 다 찍는다.
TECH_LOG_EXPLORE_KIND: () => "/explore/knowledge",
TECH_LOG_CASE: knowledge("CASE"),
TECH_LOG_REFERENCE: knowledge("REFERENCE"),
TECH_LOG_CONCEPT: knowledge("CONCEPT"),
TECH_LOG_SETUP: knowledge("SETUP"),
TECH_LOG_QUESTION: (data) => data.questionPath,
TECH_LOG_TOPICS: () => "/topics",
TECH_LOG_TOPIC: (data) => (data.topicSlug ? `/topics/${data.topicSlug}` : null),
TECH_LOG_TOPIC_VARIANT: (data) =>
data.topicWithVariant
? `/topics/${data.topicWithVariant.slug}/${data.topicWithVariant.variant}`
: null,
TECH_LOG_PROJECTS: () => "/projects",
TECH_LOG_PROJECT: (data) => (data.projectSlug ? `/projects/${data.projectSlug}` : null),
TECH_LOG_PROJECT_RECORDS: (data) =>
data.projectSlug ? `/projects/${data.projectSlug}/records` : null,
TECH_LOG_PROJECT_DECISIONS: (data) =>
data.projectSlug ? `/projects/${data.projectSlug}/decisions` : null,
TECH_LOG_PROJECT_ACTIVITY: (data) =>
data.projectSlug ? `/projects/${data.projectSlug}/activity` : null,
TECH_LOG_RELEASES: () => "/releases",
TECH_LOG_RELEASE: (data) => (data.releaseVersion ? `/releases/${data.releaseVersion}` : null),
TECH_LOG_PROFILE: () => "/profile",
// 빈 검색 결과가 아니라 실제로 걸리는 말을 넣는다. 빈 화면은 배치를 보여 주지 않는다.
TECH_LOG_SEARCH: () => "/search?q=%EA%B0%80%EC%83%81%ED%99%94",
TECH_LOG_STUDIO_HOME: () => "/studio",
TECH_LOG_STUDIO_DOCUMENTS: () => "/studio/documents",
TECH_LOG_STUDIO_DOCUMENT_NEW: () => "/studio/documents/new",
TECH_LOG_STUDIO_DOCUMENT_EDIT: (data) =>
data.documentId ? `/studio/documents/${data.documentId}/edit` : null,
TECH_LOG_STUDIO_DOCUMENT_VALIDATION: (data) =>
data.documentId ? `/studio/documents/${data.documentId}/validation` : null,
TECH_LOG_STUDIO_DOCUMENT_PREVIEW: (data) =>
data.documentId ? `/studio/documents/${data.documentId}/preview` : null,
TECH_LOG_STUDIO_DOCUMENT_PUBLISH: (data) =>
data.documentId ? `/studio/documents/${data.documentId}/publish` : null,
TECH_LOG_STUDIO_PUBLICATIONS: () => "/studio/publications",
TECH_LOG_STUDIO_PUBLICATION_PREVIEW: (data) =>
data.publicationEventId ? `/studio/publications/${data.publicationEventId}/preview` : null,
TECH_LOG_STUDIO_ASSETS: () => "/studio/assets",
TECH_LOG_STUDIO_TAXONOMY: () => "/studio/taxonomy",
TECH_LOG_STUDIO_PROJECT_EDIT: (data) =>
data.studioProjectId ? `/studio/projects/${data.studioProjectId}` : null,
TECH_LOG_STUDIO_TOPIC_EDIT: (data) =>
data.studioTopicId ? `/studio/topics/${data.studioTopicId}` : null,
TECH_LOG_STUDIO_RELEASES: () => "/studio/releases",
TECH_LOG_STUDIO_RELEASE_EDIT: (data) =>
data.studioReleaseId ? `/studio/releases/${data.studioReleaseId}` : null,
// 없는 주소여야 찍을 수 있는 화면이다.
TECH_LOG_STUDIO_NOT_FOUND: () => "/studio/no-such-studio-page",
NOT_FOUND: () => "/no-such-page",
};
/**
* 한 라우트가 여러 화면을 그리는 경우. `/explore/:kind` 의 두 갈래처럼 같은 코드가 아니라 서로
* 다른 화면이면 검토에서 둘 다 봐야 한다.
*/
const EXTRA_TARGETS: ReadonlyArray> =
[{ id: "TECH_LOG_EXPLORE_KIND-questions", group: "PUBLIC", url: "/explore/questions" }];
type Target = Readonly<{ id: string; group: "PUBLIC" | "STUDIO"; url: string }>;
type Skipped = Readonly<{ id: string; group: string; reason: string }>;
async function json(request: APIRequestContext, url: string): Promise {
const response = await request.get(url, { headers: { Accept: "application/json" } });
if (!response.ok()) return null;
try {
return (await response.json()) as unknown;
} catch {
return null;
}
}
function envelope(value: unknown): Record | null {
if (typeof value !== "object" || value === null) return null;
const data = (value as { data?: unknown }).data;
return typeof data === "object" && data !== null ? (data as Record) : null;
}
function itemsOf(value: unknown): ReadonlyArray> {
const data = envelope(value);
const items = data?.["items"];
return Array.isArray(items) ? (items as Record[]) : [];
}
function text(row: Record | undefined, key: string): string | null {
const value = row?.[key];
return typeof value === "string" && value.length > 0 ? value : null;
}
/** 공개 화면에 필요한 값. 로그인 없이 읽는다. */
async function readPublic(request: APIRequestContext, base: string) {
const [knowledgeRaw, questionsRaw, topicsRaw, projectsRaw, releasesRaw] = await Promise.all([
json(request, `${base}/api/v1/public/explore/knowledge?limit=100`),
json(request, `${base}/api/v1/public/explore/questions?limit=20`),
json(request, `${base}/api/v1/public/topics`),
json(request, `${base}/api/v1/public/projects`),
json(request, `${base}/api/v1/public/releases`),
]);
const knowledgePaths: Record = {};
for (const row of itemsOf(knowledgeRaw)) {
const kind = text(row, "type");
const routePath = text(row, "path");
if (kind && routePath && !(kind in knowledgePaths)) knowledgePaths[kind] = routePath;
}
const topics = itemsOf(topicsRaw);
const withVariant = topics.find((row) => Number(row["variantCount"] ?? 0) > 0);
let topicWithVariant: { slug: string; variant: string } | null = null;
const withVariantSlug = text(withVariant, "slug");
if (withVariantSlug) {
const detail = envelope(await json(request, `${base}/api/v1/public/topics/${withVariantSlug}`));
const variants = detail?.["variants"];
const first = Array.isArray(variants) ? (variants[0] as Record) : undefined;
const variant = text(first, "slug") ?? text(first, "variantSlug");
if (variant) topicWithVariant = { slug: withVariantSlug, variant };
}
return {
knowledgePaths,
questionPath: text(itemsOf(questionsRaw)[0], "path"),
topicSlug: text(topics[0], "slug"),
topicWithVariant,
projectSlug: text(itemsOf(projectsRaw)[0], "slug"),
releaseVersion: text(itemsOf(releasesRaw)[0], "version"),
};
}
/** Studio 화면에 필요한 값. 저장된 세션으로 읽는다. */
async function readStudio(request: APIRequestContext, base: string) {
const [documentsRaw, publicationsRaw, projectsRaw, topicsRaw, releasesRaw] = await Promise.all([
json(request, `${base}/api/v1/studio/documents?limit=1`),
json(request, `${base}/api/v1/studio/publications?limit=1`),
json(request, `${base}/api/v1/studio/catalog?type=PROJECT&limit=1`),
json(request, `${base}/api/v1/studio/catalog?type=TOPIC&limit=1`),
json(request, `${base}/api/v1/studio/releases?size=1`),
]);
const event = itemsOf(publicationsRaw)[0]?.["event"];
const releases = itemsOf(releasesRaw);
return {
documentId: text(itemsOf(documentsRaw)[0], "id"),
publicationEventId: text(
typeof event === "object" && event !== null ? (event as Record) : undefined,
"publicationEventId",
),
studioProjectId: text(itemsOf(projectsRaw)[0], "id"),
studioTopicId: text(itemsOf(topicsRaw)[0], "id"),
studioReleaseId: text(releases[0], "id") ?? text(releases[0], "releaseId"),
};
}
const EMPTY_STUDIO = {
documentId: null,
publicationEventId: null,
studioProjectId: null,
studioTopicId: null,
studioReleaseId: null,
} as const;
/**
* 창을 열어 사람이 직접 로그인하게 하고 그 세션을 파일로 남긴다.
*
* 자격 증명을 스크립트가 들고 있지 않아도 되고, Keycloak 화면이 바뀌어도 깨지지 않는다.
*/
async function login(base: string): Promise {
/*
로그인 창은 사람이 타이핑하는 동안 몇 분씩 떠 있다. 기본 설정으로 띄우면 그 시간 내내
메모리를 크게 물고 있어서 이 기계의 감시에 걸려 죽었다 — 창이 죽으면 세션도 못 받는다.
그림을 그릴 일도 없는 창이므로 GPU 와 큰 공유 메모리를 쓰지 않게 하고 힙도 줄인다.
*/
const browser = await chromium.launch({
headless: false,
args: [
"--disable-gpu",
"--disable-dev-shm-usage",
"--disable-extensions",
"--js-flags=--max-old-space-size=320",
],
});
const context = await browser.newContext({ viewport: { width: 1440, height: 900 } });
const page = await context.newPage();
await page.goto(`${base}/studio`);
process.stdout.write("열린 창에서 로그인하세요. Studio 화면이 뜨면 자동으로 저장합니다...\n");
try {
await page.waitForSelector('a[href="/studio/documents"]', { timeout: 300_000 });
await mkdir(path.dirname(SESSION_FILE), { recursive: true });
await context.storageState({ path: SESSION_FILE });
process.stdout.write(`세션 저장: ${SESSION_FILE}\n`);
} finally {
await browser.close();
}
}
async function sessionState(): Promise {
try {
await readFile(SESSION_FILE, "utf8");
return SESSION_FILE;
} catch {
return undefined;
}
}
/**
* 한 화면을 폭마다 찍는다.
*
* 전체 페이지를 한 장으로 찍으면 세로로 긴 문서가 통째로 축소되어 17px 글자가 7~8px 로
* 뭉갠다. 덩어리는 보이지만 정작 타이포는 못 본다. 그래서 화면 높이만큼씩 잘라 찍는다.
*/
async function capture(
page: Page,
target: Target,
base: string,
widths: readonly number[],
maxSlices: number,
): Promise<{ files: string[]; problem: string | null }> {
const files: string[] = [];
const directory = path.join(OUTPUT_DIRECTORY, target.group.toLowerCase());
for (const width of widths) {
await page.setViewportSize({ width, height: VIEWPORT_HEIGHT });
await page.goto(`${base}${target.url}`, { waitUntil: "domcontentloaded" });
await page.waitForSelector("main", { timeout: 20_000 }).catch(() => undefined);
// 자료를 받아 다시 그리는 화면이 많다. 반쯤 그려진 상태를 남기면 검토가 그것을 지적한다.
await page.waitForLoadState("networkidle", { timeout: 15_000 }).catch(() => undefined);
await page.waitForTimeout(400);
if (target.group === "STUDIO" && (await page.locator(AUTH_GATE).count()) > 0) {
return { files, problem: "세션이 끊겨 로그인 화면이 떴습니다 — --login 으로 다시 로그인하세요" };
}
const height = await page.evaluate(() => document.documentElement.scrollHeight);
const slices = Math.min(Math.max(Math.ceil(height / VIEWPORT_HEIGHT), 1), maxSlices);
for (let index = 0; index < slices; index += 1) {
await page.evaluate((top: number) => window.scrollTo(0, top), index * VIEWPORT_HEIGHT);
await page.waitForTimeout(200);
const file = path.join(directory, `${target.id}-${width}-${index + 1}.png`);
await page.screenshot({ path: file, scale: "css" });
files.push(file);
}
}
return { files, problem: null };
}
function flag(name: string): string | null {
const found = process.argv.slice(2).find((entry) => entry.startsWith(`--${name}=`));
return found ? found.slice(name.length + 3) : null;
}
async function main(): Promise {
const base = (flag("base") ?? DEFAULT_BASE).replace(/\/+$/u, "");
if (process.argv.includes("--login")) {
await login(base);
return;
}
const only = flag("only");
const widths = flag("widths")?.split(",").map(Number).filter(Number.isFinite) ?? [
...DEFAULT_WIDTHS,
];
const maxSlices = Number(flag("slices") ?? DEFAULT_SLICES);
/*
이번에 찍는 묶음만 비운다. 통째로 지우면 `--only=studio` 한 번이 직전에 찍어 둔 공개 화면을
전부 날린다 — 실제로 한 번 날렸다.
*/
const clearing = only === "public" ? ["public"] : only === "studio" ? ["studio"] : ["public", "studio"];
for (const group of clearing) {
await rm(path.join(OUTPUT_DIRECTORY, group), { recursive: true, force: true });
await mkdir(path.join(OUTPUT_DIRECTORY, group), { recursive: true });
}
const browser = await chromium.launch();
const skipped: Skipped[] = [];
const captured: Array<{ target: Target; files: string[] }> = [];
try {
const publicContext = await browser.newContext({ viewport: { width: 1440, height: 900 } });
const publicData = await readPublic(publicContext.request, base);
const storage = await sessionState();
let studioContext: BrowserContext | null = null;
let studioData: Awaited> = { ...EMPTY_STUDIO };
if (only !== "public") {
if (!storage) {
process.stdout.write(
`Studio 세션이 없습니다(${SESSION_FILE}). 공개 화면만 찍습니다.\n` +
" → node scripts/capture-screens.ts --login 으로 먼저 로그인하세요.\n\n",
);
} else {
studioContext = await browser.newContext({
storageState: storage,
viewport: { width: 1440, height: 900 },
});
studioData = await readStudio(studioContext.request, base);
}
}
const data: LiveData = { ...publicData, ...studioData };
const targets: Target[] = [];
for (const [routeId, definition] of Object.entries(TECH_LOG_ROUTE_REGISTRY)) {
const group = definition.layoutGroup === "STUDIO" ? "STUDIO" : "PUBLIC";
if (only === "public" && group === "STUDIO") continue;
if (only === "studio" && group === "PUBLIC") continue;
if (group === "STUDIO" && !studioContext) {
skipped.push({ id: routeId, group, reason: "Studio 세션 없음" });
continue;
}
const url = RESOLVERS[routeId as RouteId](data);
if (url === null) {
skipped.push({ id: routeId, group, reason: "이 화면을 채울 실제 자료가 없습니다" });
continue;
}
targets.push({ id: routeId, group, url });
}
for (const extra of EXTRA_TARGETS) {
if (only === "studio" && extra.group === "PUBLIC") continue;
if (only === "public" && extra.group === "STUDIO") continue;
targets.push(extra);
}
const publicPage = await publicContext.newPage();
const studioPage = studioContext ? await studioContext.newPage() : null;
for (const target of targets) {
const page = target.group === "STUDIO" ? studioPage : publicPage;
if (!page) continue;
const result = await capture(page, target, base, widths, maxSlices);
if (result.problem) {
skipped.push({ id: target.id, group: target.group, reason: result.problem });
process.stdout.write(` ✗ ${target.id} ${target.url} — ${result.problem}\n`);
continue;
}
captured.push({ target, files: result.files });
process.stdout.write(` ✓ ${target.id} ${target.url} (${result.files.length}장)\n`);
}
} finally {
await browser.close();
}
/*
묶음별로 결과를 남기고, 목차는 남아 있는 파일 전부에서 다시 만든다. `--only` 로 한쪽만 찍어도
목차에서 다른 쪽이 사라지지 않는다.
*/
for (const group of clearing) {
const rows = captured.filter((entry) => entry.target.group.toLowerCase() === group);
const groupSkipped = skipped.filter((entry) => entry.group.toLowerCase() === group);
await writeFile(
path.join(OUTPUT_DIRECTORY, `captured-${group}.json`),
`${JSON.stringify({ base, captured: rows, skipped: groupSkipped }, null, 2)}\n`,
"utf8",
);
}
const merged: Array<{ target: Target; files: string[] }> = [];
const mergedSkipped: Skipped[] = [];
for (const group of ["public", "studio"]) {
try {
const raw = JSON.parse(
await readFile(path.join(OUTPUT_DIRECTORY, `captured-${group}.json`), "utf8"),
) as { captured: Array<{ target: Target; files: string[] }>; skipped: Skipped[] };
merged.push(...raw.captured);
mergedSkipped.push(...raw.skipped);
} catch {
// 아직 찍지 않은 묶음이다.
}
}
const lines = ["# 화면 목록", "", `기준 주소: ${base}`, ""];
for (const group of ["PUBLIC", "STUDIO"] as const) {
const rows = merged.filter((entry) => entry.target.group === group);
if (rows.length === 0) continue;
lines.push(`## ${group === "PUBLIC" ? "공개" : "Studio"} (${rows.length})`, "");
for (const { target, files } of rows) {
lines.push(`### ${target.id}`, "", `\`${target.url}\``, "");
for (const file of files) lines.push(`})`);
lines.push("");
}
}
if (mergedSkipped.length > 0) {
lines.push("## 찍지 못한 화면", "");
for (const entry of mergedSkipped) lines.push(`- \`${entry.id}\` (${entry.group}) — ${entry.reason}`);
lines.push("");
}
await writeFile(path.join(OUTPUT_DIRECTORY, "index.md"), `${lines.join("\n")}\n`, "utf8");
process.stdout.write(
`\n찍은 화면 ${captured.length}개, 건너뛴 화면 ${skipped.length}개\n` +
`${OUTPUT_DIRECTORY}/index.md\n`,
);
}
await main();