elanous 0.2.0 → 0.2.4

package/src/design/design-directions.ts

@@ -1,30 +1,18 @@
-// ── B5 — 「다섯 방향으로 대화 시작」 ──
-//
-// 요구사항은 표 한 행이다: *"다섯 방향으로 대화 시작"* — 브랜드가 아직 없을 때
-// 대화 첫머리에 시각적 출발점을 «고르게» 한다.
-//
-// ⭐ 결정(2026-08-24): 남의 값을 수입하지 않고 «형식»만 가져온다.
-//    upstream(OpenDesign)은 `DesignDirection` 에 팔레트·폰트를 담아 다섯을 큐레이션한다.
-//    ⛔ 그것을 수입하면 B1 라이선스 절차(체크섬 ⊕ NOTICE ⊕ 3자 드리프트 지킴이)를
-//    전부 짊어지고 upstream 을 계속 추적해야 한다.
-//    ✅ 그런데 우리에겐 `THEME_REGISTRY` 가 «이미» 있고, 21차가 그 대비까지 게이트로 지켰다.
-//    ⇒ 방향은 그 레지스트리에서 «도출»한다. 새 목록을 손으로 적지 않는다.
-//
-// ⛔ 그래서 이 파일에 색값이 «하나도» 없다. 하나라도 적는 순간 그것이
-//    테마 목록의 다음 사본이 되고, `B4-1`(#11498 계열)이 지운 그 문제가 돌아온다.
-//
-// B2 와의 관계: 규칙집은 *"하지 마라"*, 방향은 *"이렇게 생겨라"* — 다른 축이다.
-// 고른 방향의 «착지점»은 `DESIGN.md` 다. B2 가 이미 「DESIGN.md 가 선언한다」 축을 세웠다.
+// 방향은 테마 레지스트리 또는 번들 디자인 시스템의 토큰에서 도출한다.
+// 테마의 기존 목록과 선언 형식은 유지하고, 시스템 토큰 값은 이 파일에 복제하지 않는다.
+// B2 규칙집은 제약을, DESIGN.md 의 방향 선언은 선택을 담는다.
 
 import type { ThemeTokens } from '../theme/tokens.js';
 import { THEME_REGISTRY } from '../themes/index.js';
 import { readSectionItems } from './design-doc.js';
+import { libraryDir } from './design-library.js';
+import { defaultDesignSystemsDir, listDesignSystems, type DesignSystem } from './design-systems.js';
 
 /** `DESIGN.md` 안에서 방향을 선언하는 절. */
 export const DIRECTION_HEADING = '## Design direction';
 
 export interface DesignDirection {
-  /** 테마 이름 그대로 — 별도 id 를 만들면 그것이 사상 하나를 더 만든다. */
+  /** 테마 이름 또는 디자인 시스템 id 그대로. */
   id: string;
   /** 사람이 고를 때 보는 한 줄. */
   label: string;
@@ -34,14 +22,13 @@ export interface DesignDirection {
   isDark: boolean;
   /** 파스텔(채도를 낮춘) 계열인가. */
   isPastel: boolean;
-  /** 미리보기에 쓸 대표 색 — 테마 토큰에서 «그대로» 가져온다(사본 아님). */
-  swatch: { text: string; accent: string; muted: string };
-  /** 이 방향이 «어디서» 왔나. 없으면 테마 레지스트리다(기존 여섯).
-   *  ⛔ 「테마에서 왔다」와 「문서에서 왔다」를 한 값으로 접지 않는다 —
-   *  전자는 이 저장소가 대비까지 게이트로 지키고, 후자는 «남의 웹»에서 왔다. */
-  source?: 'theme' | 'document';
-  /** 이 방향이 묶는 서체. ⛔ 테마 방향엔 «없다» — 터미널 테마는 서체를 안 정한다.
-   *  그것이 이 필드가 선택인 이유다(억지로 채우면 「모른다」가 사라진다). */
+  /** 미리보기에 쓸 대표 색 — 테마 또는 시스템 토큰에서 가져온다. */
+  swatch: { text: string; accent: string; muted: string; bg?: string; fg?: string };
+  /** 방향의 출처. 없으면 테마 레지스트리다(기존 여섯). */
+  source?: 'theme' | 'document' | 'design-system';
+  /** 라이브러리 커스텀 시스템만 `Custom`. 번들·테마는 비운다. */
+  category?: 'Custom';
+  /** 시스템/문서 방향의 서체. 터미널 테마는 서체를 정하지 않는다. */
   typography?: { display: string | null; body: string | null };
 }
 
@@ -75,6 +62,36 @@ export function listDesignDirections(
   }));
 }
 
+export function listAllDesignDirections({
+  systemsDir = defaultDesignSystemsDir(),
+  librarySystemsDir,
+}: { systemsDir?: string; librarySystemsDir?: string } = {}): DesignDirection[] {
+  const themes = listDesignDirections();
+  const themeIds = new Set(themes.map((theme) => theme.id));
+  const bundled = listDesignSystems(systemsDir).filter((system) => !themeIds.has(system.id));
+  const bundledIds = new Set(bundled.map((system) => system.id));
+  const library = listDesignSystems(librarySystemsDir ?? libraryDir())
+    .filter((system) => !themeIds.has(system.id) && !bundledIds.has(system.id));
+  return [
+    ...themes,
+    ...[...bundled, ...library].map(directionFromSystem),
+  ];
+}
+
+function directionFromSystem(system: DesignSystem): DesignDirection {
+  return {
+    id: system.id,
+    label: system.name,
+    mood: system.summary,
+    isDark: (luminance(system.swatch.bg) ?? 255) < 128,
+    isPastel: false,
+    swatch: { bg: system.swatch.bg, fg: system.swatch.fg, text: system.swatch.fg, accent: system.swatch.accent, muted: system.swatch.fg },
+    typography: { display: system.fonts.display, body: system.fonts.body },
+    source: 'design-system',
+    ...(system.category === 'Custom' ? { category: 'Custom' as const } : {}),
+  };
+}
+
 export interface DirectionDeclaration {
   /** `DESIGN.md` 가 선언한 방향. 절이 없거나 비면 null. */
   declared: string | null;
@@ -105,13 +122,27 @@ export function parseDeclaredDirection(
  *  DESIGN.md 인가)을 소유한다. 그 규칙은 `#11793`·`#11930` 이 이미 정했고
  *  여기서 다시 정하면 세 번째 답이 생긴다. */
 export function writeDeclaredDirection(document: string, directionId: string): string {
+  return writeDirectionEntries(document, directionId, []);
+}
+
+export function writeDeclaredSystemDirection(document: string, directionId: string, sourceCommit: string): string {
+  return writeDirectionEntries(document, directionId, [
+    'tokens: design/system/tokens.css',
+    sourceCommit === 'custom'
+      ? `source: custom@${directionId}`
+      : `source: open-design@${sourceCommit.slice(0, 10)}`,
+  ]);
+}
+
+function writeDirectionEntries(document: string, directionId: string, details: readonly string[]): string {
+  const entries = [`- ${directionId}`, ...details.map((detail) => `- ${detail}`)];
   const lines = document.split(/\r?\n/);
   const start = lines.indexOf(DIRECTION_HEADING);
 
   if (start === -1) {
     // 절이 없다 — 문서 끝에 붙인다. 앞 문서의 마지막 빈 줄은 보존한다.
     const trimmed = document.replace(/\s*$/, '');
-    return `${trimmed}\n\n${DIRECTION_HEADING}\n\n- ${directionId}\n`;
+    return `${trimmed}\n\n${DIRECTION_HEADING}\n\n${entries.join('\n')}\n`;
   }
 
   // 절이 있다 — 그 절만 갈아 끼운다(다른 절은 손대지 않는다).
@@ -119,7 +150,7 @@ export function writeDeclaredDirection(document: string, directionId: string): s
   while (end < lines.length && !lines[end]!.startsWith('#')) end += 1;
   const rest = lines.slice(end);
   const head = lines.slice(0, start + 1);
-  return [...head, '', `- ${directionId}`, '', ...rest].join('\n').replace(/\n{3,}/g, '\n\n');
+  return [...head, '', ...entries, '', ...rest].join('\n').replace(/\n{3,}/g, '\n\n');
 }
 
 // ── 웹 레퍼런스를 «방향»으로 ────────────────────────────────────────────────
@@ -131,19 +162,8 @@ export function writeDeclaredDirection(document: string, directionId: string): s
 //
 // ⛔ 이 함수도 색값을 «적지 않는다» — 문서가 말한 값만 옮긴다(이 파일의 머리말 규율).
 
-// ── 🛑 «안 짓기로» 한 것 — 간격·모션 (2026-09-08 결정) ─────────────────────
-//
-// 인계 §19d 가 *"DesignDirection 에 간격·모션이 없다 — 추출은 내는데 타입이 안 담는다"*를
-// 열린 칸으로 적어 뒀다. ⛔ 짓기 전에 **누가 쓰나**를 쟀다:
-//
-//   direction.typography  (같은 날 추가)   →  소비자 ***0***
-//   PWA `DesignCheckPanel` 이 그리는 것    →  `id` · `mood` · `swatch` 뿐
-//
-// ⇒ 간격·모션을 더해도 «그리는 자리»가 없다. 그것은 사다리 ①(호출부 0)을 하나 더 짓는 일이다.
-// 🔑 그래서 **안 짓는다.** 필요해지는 조건을 대신 적어 둔다:
-//   ***「방향을 골라 페이지를 «저작»하는 소비자」가 생기면*** 그때 간격·모션이 값을 갖는다.
-//   (지금 소비자는 「고르는 화면」이지 「짓는 코드」가 아니다)
-// ⛔ 이 주석을 지우고 필드를 더하려면, 먼저 그 소비자를 대라.
+// 시스템의 간격·모션 값은 선택 시 복사하는 DESIGN.md 와 tokens.css 에 보존된다.
+// 웹 추출 방향은 해당 값을 사용하는 소비자가 생길 때 별도 필드로 확장한다.
 
 /** 왜 방향을 «못» 만들었나. ⛔ 「null」 하나로 접으면 「팔레트가 없다」와 「역할을 못 봤다」가 같아진다. */
 export type DirectionRefusal =

package/src/design/design-gate.ts

@@ -0,0 +1,241 @@
+// 프로젝트 단위 디자인 관문 — 고른 방향의 토큰 대비 HTML 준수를 한 판정으로 낸다.
+// 그래프 노드는 인자 없는 한 줄을 부르므로, 이 모듈은 LLM·네트워크를 부르지 않고
+// 대상 프로젝트의 파일도 쓰지 않는다.
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+import { debug } from '../debug/log.js';
+import { listAllDesignDirections, parseDeclaredDirection } from './design-directions.js';
+import { runLintDesign, type TokensSource } from './lint-artifact-run.js';
+
+export type DesignGateVerdict = 'pass' | 'fail' | 'not-applicable';
+
+export type DesignGateReason = 'no-design-document' | 'no-direction' | 'no-html';
+
+export interface DesignGateFinding {
+  readonly rule: string;
+  readonly severity: 'p0' | 'advisory';
+  readonly line: number | null;
+}
+
+export interface DesignGateFile {
+  readonly path: string;
+  readonly p0: number;
+  readonly advisory: number;
+  readonly skipped: readonly string[];
+  readonly findings: readonly DesignGateFinding[];
+}
+
+export interface DesignGateResult {
+  readonly verdict: DesignGateVerdict;
+  readonly reason?: DesignGateReason;
+  readonly direction: string | null;
+  readonly tokensSource: TokensSource | null;
+  readonly p0Total: number;
+  readonly advisoryTotal: number;
+  readonly files: readonly DesignGateFile[];
+  readonly truncated: boolean;
+  readonly omitted: number;
+  readonly checkedAt: string;
+}
+
+export interface DesignGateInput {
+  readonly projectDir: string;
+  readonly base?: string;
+  readonly maxFiles?: number;
+}
+
+export interface DesignGateDeps {
+  readonly readFile?: (path: string) => string;
+  readonly exists?: (path: string) => boolean;
+  readonly listHtml?: (projectDir: string) => readonly string[];
+  readonly gitDiffNames?: (projectDir: string, base: string) => readonly string[];
+  readonly gitUntracked?: (projectDir: string) => readonly string[];
+  readonly now?: () => string;
+  readonly lint?: typeof runLintDesign;
+  readonly directions?: () => ReturnType<typeof listAllDesignDirections>;
+}
+
+const DEFAULT_MAX_FILES = 50;
+const EXCLUDED_PREFIXES = ['node_modules/', '.git/', 'design/previews/', 'design/system/'];
+
+function posixRelative(projectDir: string, filePath: string): string {
+  return relative(projectDir, filePath).split(sep).join('/');
+}
+
+function isExcludedHtml(rel: string): boolean {
+  const normalized = rel.replace(/\\/g, '/').replace(/^\.\//, '');
+  if (!normalized.endsWith('.html')) return true;
+  return EXCLUDED_PREFIXES.some((prefix) => normalized === prefix.slice(0, -1) || normalized.startsWith(prefix));
+}
+
+function walkHtml(projectDir: string, dir: string, out: string[]): void {
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    const full = join(dir, name);
+    const rel = posixRelative(projectDir, full);
+    let isDirectory = false;
+    try {
+      isDirectory = statSync(full).isDirectory();
+    } catch {
+      continue;
+    }
+    if (isDirectory) {
+      if (EXCLUDED_PREFIXES.some((prefix) => rel === prefix.slice(0, -1) || rel.startsWith(prefix))) continue;
+      if (name === 'node_modules' || name === '.git') continue;
+      walkHtml(projectDir, full, out);
+      continue;
+    }
+    if (!isExcludedHtml(rel)) out.push(full);
+  }
+}
+
+function defaultListHtml(projectDir: string): string[] {
+  const out: string[] = [];
+  walkHtml(projectDir, projectDir, out);
+  return out.sort();
+}
+
+function gitLines(projectDir: string, args: readonly string[]): string[] {
+  const text = execFileSync('git', ['-C', projectDir, ...args], { encoding: 'utf8' });
+  return text.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
+}
+
+function resolveChangedHtml(
+  projectDir: string,
+  base: string,
+  deps: Required<Pick<DesignGateDeps, 'gitDiffNames' | 'gitUntracked' | 'exists'>>,
+): string[] {
+  const names = [...deps.gitDiffNames(projectDir, base), ...deps.gitUntracked(projectDir)];
+  const seen = new Set<string>();
+  const files: string[] = [];
+  for (const name of names) {
+    const rel = name.replace(/\\/g, '/').replace(/^\.\//, '');
+    if (isExcludedHtml(rel) || seen.has(rel)) continue;
+    const full = join(projectDir, rel);
+    if (!deps.exists(full)) continue;
+    try {
+      if (!statSync(full).isFile()) continue;
+    } catch {
+      continue;
+    }
+    seen.add(rel);
+    files.push(full);
+  }
+  return files.sort();
+}
+
+function emptyResult(
+  verdict: DesignGateVerdict,
+  reason: DesignGateReason | undefined,
+  direction: string | null,
+  checkedAt: string,
+): DesignGateResult {
+  return {
+    verdict,
+    ...(reason ? { reason } : {}),
+    direction,
+    tokensSource: null,
+    p0Total: 0,
+    advisoryTotal: 0,
+    files: [],
+    truncated: false,
+    omitted: 0,
+    checkedAt,
+  };
+}
+
+export function runDesignGate(input: DesignGateInput, deps: DesignGateDeps = {}): DesignGateResult {
+  const readFile = deps.readFile ?? ((path: string) => readFileSync(path, 'utf8'));
+  const exists = deps.exists ?? existsSync;
+  const listHtml = deps.listHtml ?? defaultListHtml;
+  const gitDiffNames = deps.gitDiffNames ?? ((projectDir: string, base: string) => gitLines(projectDir, ['diff', '--name-only', `${base}...HEAD`]));
+  const gitUntracked = deps.gitUntracked ?? ((projectDir: string) => gitLines(projectDir, ['ls-files', '--others', '--exclude-standard']));
+  const now = deps.now ?? (() => new Date().toISOString());
+  const lint = deps.lint ?? runLintDesign;
+  const directions = deps.directions ?? (() => listAllDesignDirections());
+  const checkedAt = now();
+  const maxFiles = input.maxFiles ?? DEFAULT_MAX_FILES;
+  const designPath = join(input.projectDir, 'DESIGN.md');
+
+  let result: DesignGateResult;
+  if (!exists(designPath)) {
+    result = emptyResult('not-applicable', 'no-design-document', null, checkedAt);
+  } else {
+    const document = readFile(designPath);
+    const parsed = parseDeclaredDirection(document, directions());
+    if (parsed.declared === null) {
+      result = emptyResult('not-applicable', 'no-direction', null, checkedAt);
+    } else {
+      const htmlFiles = input.base
+        ? resolveChangedHtml(input.projectDir, input.base, { gitDiffNames, gitUntracked, exists })
+        : [...listHtml(input.projectDir)].filter((file) => !isExcludedHtml(posixRelative(input.projectDir, file))).sort();
+      if (htmlFiles.length === 0) {
+        result = emptyResult('not-applicable', 'no-html', parsed.declared, checkedAt);
+      } else {
+        const limited = htmlFiles.slice(0, Math.max(0, maxFiles));
+        const omitted = htmlFiles.length - limited.length;
+        let tokensSource: TokensSource | null = null;
+        const files: DesignGateFile[] = limited.map((htmlPath, index) => {
+          const run = lint({ htmlPath, designPath });
+          if (index === 0) tokensSource = run.tokensSource;
+          return {
+            path: posixRelative(input.projectDir, htmlPath) || htmlPath,
+            p0: run.p0Count,
+            advisory: run.advisoryCount,
+            skipped: [...run.skipped],
+            findings: run.findings.map((finding) => ({
+              rule: finding.rule,
+              severity: finding.severity,
+              line: finding.line,
+            })),
+          };
+        });
+        const p0Total = files.reduce((sum, file) => sum + file.p0, 0);
+        const advisoryTotal = files.reduce((sum, file) => sum + file.advisory, 0);
+        result = {
+          verdict: p0Total >= 1 ? 'fail' : 'pass',
+          direction: parsed.declared,
+          tokensSource,
+          p0Total,
+          advisoryTotal,
+          files,
+          truncated: omitted > 0,
+          omitted,
+          checkedAt,
+        };
+      }
+    }
+  }
+
+  debug.log('design.gate', 'verdict', {
+    projectDir: input.projectDir,
+    direction: result.direction,
+    verdict: result.verdict,
+    p0Total: result.p0Total,
+    fileCount: result.files.length,
+  });
+  return result;
+}
+
+export function formatDesignGate(result: DesignGateResult): string[] {
+  const headline = result.verdict === 'not-applicable'
+    ? `design-gate ${result.verdict} (${result.reason ?? 'unknown'})`
+    : `design-gate ${result.verdict} direction=${result.direction ?? '(none)'} p0=${result.p0Total} advisory=${result.advisoryTotal}`;
+  const lines = [headline];
+  for (const file of result.files) {
+    const firstP0 = file.findings.find((finding) => finding.severity === 'p0');
+    lines.push(`${file.path} p0=${file.p0}${firstP0 ? ` ${firstP0.rule}` : ''}`);
+  }
+  const unchecked = result.files.reduce((sum, file) => sum + file.skipped.length, 0);
+  lines.push(`unchecked ${unchecked}`);
+  if (result.truncated) lines.push(`truncated omitted=${result.omitted}`);
+  return lines;
+}

package/src/design/design-library.ts

@@ -0,0 +1,57 @@
+// 사용자 디자인 시스템 라이브러리. 번들 `docs/design/systems/` 는 읽기만 한다.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { getElanousConfigDir } from '../elanous-config-dir.js';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { defaultDesignSystemsDir, listDesignSystems } from './design-systems.js';
+import { THEME_REGISTRY } from '../themes/index.js';
+import type { PromotedSystem } from './system-from-extract.js';
+
+const ID_PATTERN = /^[a-z0-9-]+$/;
+
+export function libraryDir(): string {
+  const configured = configuredLibraryDir();
+  if (configured) return configured;
+  // ⛔ 우주(운영/격리)를 따르는 상태 루트 아래 — `~/.elanous` 를 박으면 격리 시험이 운영 라이브러리에 쓴다.
+  return join(elanousStateRoot(), 'design', 'systems');
+}
+
+function configuredLibraryDir(): string | null {
+  try {
+    const raw = JSON.parse(readFileSync(join(getElanousConfigDir(), 'config.json'), 'utf8')) as { design?: { libraryDir?: unknown } };
+    const value = raw.design?.libraryDir;
+    if (typeof value !== 'string' || !value.trim()) return null;
+    const trimmed = value.trim();
+    return isAbsolute(trimmed) ? trimmed : join(getElanousConfigDir(), trimmed);
+  } catch {
+    return null;
+  }
+}
+
+export function reservedDesignIds(systemsDir: string = defaultDesignSystemsDir()): Set<string> {
+  const ids = new Set<string>(THEME_REGISTRY.map((theme) => theme.name));
+  for (const system of listDesignSystems(systemsDir)) ids.add(system.id);
+  return ids;
+}
+
+export function saveCustomSystem(
+  dir: string,
+  system: PromotedSystem,
+  options: { systemsDir?: string } = {},
+): { dir: string } {
+  const id = system.manifest.id;
+  if (!ID_PATTERN.test(id)) throw new Error(`design system id 거부: ${id}`);
+  if (reservedDesignIds(options.systemsDir).has(id)) throw new Error(`design system id 가 번들 또는 테마와 겹친다: ${id}`);
+  const rootSource = join(dir, 'SOURCE.json');
+  if (!existsSync(rootSource)) {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(rootSource, `${JSON.stringify({ commit: 'custom' }, null, 2)}\n`);
+  }
+  const folder = join(dir, id);
+  mkdirSync(folder, { recursive: true });
+  writeFileSync(join(folder, 'manifest.json'), `${JSON.stringify(system.manifest, null, 2)}\n`);
+  writeFileSync(join(folder, 'DESIGN.md'), system.designMd);
+  writeFileSync(join(folder, 'tokens.css'), system.tokensCss);
+  return { dir: folder };
+}

package/src/design/design-previews.ts

@@ -0,0 +1,138 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { basename } from 'node:path';
+
+import {
+  createProject,
+  getRun,
+  listFiles,
+  openDesignConfig,
+  readFile,
+  startRun,
+  type OpenDesignClientDeps,
+  type OpenDesignConnection,
+} from './open-design-client.js';
+
+export const DESIGN_PREVIEW_POLL_MS = 10_000;
+export const DESIGN_PREVIEW_TIMEOUT_MS = 15 * 60_000;
+
+const TERMINAL = new Set(['succeeded', 'failed', 'cancelled']);
+
+export interface DesignPreviewInput {
+  repoRoot: string;
+  brief: string;
+  systems: string[];
+  agentId?: string;
+  pollMs?: number;
+  timeoutMs?: number;
+}
+
+export interface DesignPreviewResult {
+  system: string;
+  ok: boolean;
+  path?: string;
+  runId?: string;
+  status: string;
+  reason?: string;
+}
+
+export interface DesignPreviewDeps extends OpenDesignClientDeps {
+  connection?: OpenDesignConnection | null;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+  mkdir?: (path: string) => void;
+  writeFile?: (path: string, contents: string) => void;
+  clock?: () => string;
+}
+
+function safeIdPart(value: string): string {
+  const cleaned = value.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
+  return cleaned || 'x';
+}
+
+export function designPreviewProjectId(repoRoot: string, system: string, stamp: string): string {
+  return `elanous-${safeIdPart(basename(repoRoot))}-${safeIdPart(system)}-${safeIdPart(stamp)}`;
+}
+
+function firstHtml(names: readonly string[]): string | undefined {
+  return names.find((name) => name.toLowerCase().endsWith('.html'));
+}
+
+async function previewOne(
+  input: DesignPreviewInput,
+  system: string,
+  connection: OpenDesignConnection,
+  deps: DesignPreviewDeps,
+): Promise<DesignPreviewResult> {
+  const stamp = (deps.clock ?? (() => new Date().toISOString().replace(/[-:.TZ]/g, '').slice(0, 14)))();
+  const id = designPreviewProjectId(input.repoRoot, system, stamp);
+  const created = await createProject({ id, name: `${basename(input.repoRoot)} ${system}`, designSystemId: system }, connection, deps);
+  if (!created.ok) return { system, ok: false, status: 'error', reason: created.reason };
+
+  const started = await startRun({
+    projectId: created.project.id,
+    message: input.brief,
+    agentId: input.agentId ?? 'codex',
+  }, connection, deps);
+  if (!started.ok) return { system, ok: false, status: 'error', reason: started.reason };
+
+  const pollMs = input.pollMs ?? DESIGN_PREVIEW_POLL_MS;
+  const timeoutMs = input.timeoutMs ?? DESIGN_PREVIEW_TIMEOUT_MS;
+  const startedAt = (deps.now ?? Date.now)();
+  const sleep = deps.sleep ?? ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms)));
+  let status = 'queued';
+  let runError: string | null = null;
+  for (;;) {
+    const run = await getRun(started.runId, connection, deps);
+    if (!run.ok) return { system, ok: false, runId: started.runId, status: 'error', reason: run.reason };
+    status = run.run.status ?? status;
+    runError = typeof run.run.error === 'string' && run.run.error.trim() ? run.run.error.trim().slice(0, 200) : null;
+    if (TERMINAL.has(status)) break;
+    if ((deps.now ?? Date.now)() - startedAt >= timeoutMs) {
+      return { system, ok: false, runId: started.runId, status: 'timeout', reason: 'timeout' };
+    }
+    await sleep(pollMs);
+  }
+  if (status !== 'succeeded') {
+    // OpenDesign says WHY (e.g. the engine could not authenticate) — carry that sentence, not just the status.
+    return { system, ok: false, runId: started.runId, status, reason: runError ? `${status}: ${runError}` : status };
+  }
+
+  const listed = await listFiles(created.project.id, connection, deps);
+  if (!listed.ok) return { system, ok: false, runId: started.runId, status, reason: listed.reason };
+  const html = firstHtml(listed.files.map((file) => file.name));
+  if (!html) return { system, ok: false, runId: started.runId, status, reason: 'no html file' };
+  const file = await readFile(created.project.id, html, connection, deps);
+  if (!file.ok) return { system, ok: false, runId: started.runId, status, reason: file.reason };
+
+  const dir = `${input.repoRoot.replace(/\/+$/, '')}/design/previews`;
+  const path = `${dir}/${system}.html`;
+  try {
+    deps.mkdir?.(dir);
+    (deps.writeFile ?? (() => { throw new Error('writeFile missing'); }))(path, file.text);
+  } catch {
+    return { system, ok: false, runId: started.runId, status, reason: 'cannot write preview' };
+  }
+  return { system, ok: true, path, runId: started.runId, status };
+}
+
+/** 시스템마다 프로젝트를 만들고 런을 병렬로 기다린다. 한 시스템의 실패는 다른 저장을 막지 않는다. */
+export async function makeDesignPreviews(
+  input: DesignPreviewInput,
+  deps: DesignPreviewDeps = {},
+): Promise<DesignPreviewResult[]> {
+  const connection = deps.connection === undefined ? openDesignConfig(deps) : deps.connection;
+  if (!connection) {
+    return input.systems.map((system) => ({
+      system,
+      ok: false,
+      status: 'unconfigured',
+      reason: 'OpenDesign 이 설정되지 않았다 — design.openDesign.url · tokenFile',
+    }));
+  }
+  const bound: DesignPreviewDeps = {
+    ...deps,
+    mkdir: deps.mkdir ?? ((path: string) => mkdirSync(path, { recursive: true })),
+    writeFile: deps.writeFile ?? ((path: string, contents: string) => writeFileSync(path, contents, 'utf8')),
+  };
+  return Promise.all(input.systems.map((system) => previewOne(input, system, connection, bound)));
+}

package/src/design/design-systems.ts

@@ -0,0 +1,61 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { debug } from '../debug/log.js';
+
+export interface DesignSystem {
+  id: string;
+  name: string;
+  category: string;
+  summary: string;
+  swatch: { bg: string; fg: string; accent: string };
+  fonts: { display: string; body: string };
+  sourceCommit: string;
+}
+
+export function defaultDesignSystemsDir(): string {
+  return resolve(import.meta.dir, '..', '..', 'docs', 'design', 'systems');
+}
+
+export function listDesignSystems(systemsDir: string): DesignSystem[] {
+  let folders: string[];
+  let sourceCommit: string;
+  try {
+    folders = readdirSync(systemsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    sourceCommit = (JSON.parse(readFileSync(join(systemsDir, 'SOURCE.json'), 'utf8')) as { commit: string }).commit;
+    if (typeof sourceCommit !== 'string' || !sourceCommit) throw new Error('missing source commit');
+  } catch (error) {
+    debug.log('design.systems', 'skipped', { id: 'SOURCE.json', reason: String(error) });
+    return [];
+  }
+
+  const systems: DesignSystem[] = [];
+  for (const id of folders) {
+    try {
+      const dir = join(systemsDir, id);
+      const manifest = JSON.parse(readFileSync(join(dir, 'manifest.json'), 'utf8')) as { id: string; name: string; category: string };
+      if (manifest.id !== id || !manifest.name || !manifest.category) throw new Error('invalid manifest');
+      const document = readFileSync(join(dir, 'DESIGN.md'), 'utf8');
+      const summary = document.split(/\r?\n/).filter((line) => line.startsWith('> '))[1]?.slice(2).trim();
+      if (!summary) throw new Error('missing summary');
+      const cssRaw = readFileSync(join(dir, 'tokens.css'), 'utf8');
+      const css = cssRaw.replace(/\/\*[\s\S]*?\*\//g, '');
+      const root = /:root\s*\{([\s\S]*?)\}/.exec(css)?.[1];
+      if (!root) throw new Error('missing :root tokens');
+      const token = (name: string): string => {
+        const value = new RegExp(`(?:^|\\n)\\s*--${name}\\s*:\\s*([^;\\n]+)\\s*;`, 'm').exec(root)?.[1]?.trim();
+        if (value) return value;
+        if (new RegExp(`/\\*\\s*⚪\\s*--${name}\\s*:`).test(cssRaw)) return '';
+        throw new Error(`missing --${name}`);
+      };
+      systems.push({
+        id, name: manifest.name, category: manifest.category, summary,
+        swatch: { bg: token('bg'), fg: token('fg'), accent: token('accent') },
+        fonts: { display: token('font-display'), body: token('font-body') },
+        sourceCommit,
+      });
+    } catch (error) {
+      debug.log('design.systems', 'skipped', { id, reason: String(error) });
+    }
+  }
+  return systems.sort((a, b) => a.id.localeCompare(b.id));
+}