elanous 0.2.0 → 0.2.4

package/src/nexus/api/connect-info.ts

@@ -10,11 +10,9 @@
 //     auto_token:     string | null,    // 자동 mint 시 raw bearer
 //   }
 //
-// `auto_token` 정책:
-//   - server hostname = 127.0.0.1/localhost (loopback only) → 기존
-//     `~/.elanous/acp-token` 파일 내용을 그대로 노출. Loopback 호출자는
-//     이미 같은 user uid 로 file 을 읽을 수 있으므로 추가 leak 없음.
-//   - 그 외 (LAN/Tailscale) → null. 사용자가 token 을 paste 해야 함.
+// `auto_token` 정책: 언제나 null (칸은 호환용으로 남긴다).
+//   종전엔 «서버 바인드가 루프백이면» 토큰 파일 원문을 실었는데, tailnet 공유(serve → localhost 프록시)에서는
+//   tailnet 기기·Pod 가 Origin 없는 GET 한 번으로 관리 토큰을 얻었다(🅣 전수 2026-09-26). 같은 기계의 CLI 는 파일을 직접 읽는다.
 //
 // `elanous nexus connect <host>` (T4.B) 가 처음 실행할 때 본 endpoint 를
 // 호출 → metadata 로 bookmark 만들고 token 을 저장. 이후 일상 사용
@@ -42,6 +40,10 @@ export interface ConnectInfoCtx {
   serverLabel?: string;
   /** Test seam — when present, used instead of file read. */
   acpTokenOverride?: string | null;
+  /** ⛔ false 면 토큰을 싣지 않는다 — 다른 웹사이트(교차 출처)의 요청(🅢 2026-09-26 실측: `Origin: https://evil.example` 에
+   *  200 ⊕ `access-control-allow-origin: *` ⊕ `auto_token` 원문 → 브라우저로 연 아무 페이지가 관리 토큰을 읽을 수 있었다).
+   *  허용 판정은 호출자(`connectInfoTokenAllowed`)가 한다. 생략 = 종전(시험 호환). */
+  allowAutoToken?: boolean;
   /**
    * Incoming request Host (header or URL host). Used only when `hostname`
    * is a wildcard bind (`0.0.0.0` / `::` / empty) so advertised URLs are
@@ -168,27 +170,12 @@ export function buildConnectInfo(ctx: ConnectInfoCtx): ConnectInfoBody {
   const voiceUrl = `ws://${hostForUrl}:${port}/v1/voice/ws`;
   const serverLabel = ctx.serverLabel ?? `${host} (NEXUS ${ctx.nexusVersion})`;
 
-  let autoToken: string | null = null;
-  if (isLoopbackHost(ctx.hostname)) {
-    if (ctx.acpTokenOverride !== undefined) {
-      autoToken = ctx.acpTokenOverride;
-    } else {
-      const path = ctx.acpTokenPath ?? defaultAcpTokenPath();
-      if (existsSync(path)) {
-        try {
-          autoToken = readFileSync(path, 'utf-8').trim();
-          if (autoToken.length === 0) autoToken = null;
-        } catch {
-          autoToken = null;
-        }
-      }
-    }
-  }
-
+  // 🔐 2026-09-26(🅣 전수): 원시 bearer 를 HTTP 로 내보내지 않는다. «바인드가 루프백»은 «요청자가 이 기계»를 뜻하지 않는다 —
+  //   `tailscale serve --tls-terminated-tcp` 는 tailnet 요청을 localhost 로 프록시하므로 상대 주소도 127.0.0.1 로 보이고,
+  //   Origin 이 없는 요청(curl·Pod)은 교차 출처 검사를 안 탄다. 같은 uid 의 로컬 도구는 토큰 파일을 직접 읽는다(remotes-cli).
+  const autoToken: string | null = null;
   const tokenRequired = autoToken === null;
-  const tokenHint = autoToken
-    ? '~/.elanous/acp-token (auto-loaded · loopback only)'
-    : '~/.elanous/acp-token on the server host (paste content into bearer)';
+  const tokenHint = '~/.elanous/acp-token on the server host (paste content into bearer · same-host CLI reads the file)';
 
   return {
     acp_url: acpUrl,
@@ -282,3 +269,14 @@ export function handleConnectTokenMint(ctx: ConnectInfoCtx): Response {
   }
   return jsonResponse(body, 201);
 }
+
+/** 관리 토큰을 connect-info 에 실어도 되는 요청인가 — Origin 이 없거나(로컬 프로세스 · 토큰 파일을 어차피 읽을 수 있다),
+ *  이 데몬이 서빙한 페이지(Origin 호스트 == 요청 Host)거나, 루프백 출처(PWA 개발 서버)일 때만.
+ *  브라우저는 Origin 을 위조할 수 없으므로 다른 웹사이트는 셋 다 아니다. */
+export function connectInfoTokenAllowed(origin: string | null, requestHost: string | null): boolean {
+  if (!origin || origin === 'null') return origin === null;
+  let o: URL;
+  try { o = new URL(origin); } catch { return false; }
+  if (requestHost && o.host === requestHost) return true;
+  return o.hostname === 'localhost' || o.hostname === '127.0.0.1' || o.hostname === '[::1]' || o.hostname === '::1';
+}

package/src/nexus/api/context-url.ts

@@ -128,7 +128,7 @@ export async function handleContextFetchUrl(
   try {
     const res = await fetchImpl(url, {
       headers: {
-        'user-agent': 'elanous-context/1.0 (+https://github.com/ElanvitalAI/monad)',
+        'user-agent': 'elanous-context/1.0 (+https://github.com/ElanvitalAI/elanous)',
         accept: 'text/html, text/plain;q=0.9, */*;q=0.5',
       },
       signal: ctrl.signal,

package/src/nexus/api/design-check.ts

@@ -1,4 +1,4 @@
-// NEXUS · GET /v1/design-check — the craft-rulebook verdict, over the wire
+// NEXUS · GET /v1/design-check and POST /v1/design-direction
 //
 // `elanous repo design-check` already answers "which craft rulebooks does this
 // repository's DESIGN.md declare, and which of them cannot be found?" — but
@@ -6,48 +6,28 @@
 // `resolveDesignCheck`, not re-derived here) to the PWA, so the browser panel
 // and the CLI can never drift apart.
 //
-// ⭐ Two roots, deliberately different — this is the whole subtlety:
-//
-//   DESIGN.md       ← the ACTIVE REPOSITORY, found the way `/v1/worktrees`
-//                     finds it (`git rev-parse --show-toplevel` from the
-//                     daemon's cwd). The daemon watches one checkout; that
-//                     checkout's design document is the subject.
-//   craft/          ← ELANOUS'S INSTALLATION directory. `#11793` established
-//                     that the rulebooks travel with elanous, not with the
-//                     project under inspection, so a project outside the
-//                     elanous tree still resolves them.
-//
-// Reading either root from the other would reintroduce exactly the
-// `process.cwd()` coupling `#11793` removed.
-//
-// Wire shape:
-//   { repoRoot: string | null,
-//     ok: true,  documentPath, craftDirectory,
-//                availableRulebooks[], declaredRulebooks[], unavailableRulebooks[],
-//                exitCode: 0 | 1 }
-//   { repoRoot: string | null,
-//     ok: false, blockedOn: 'no-repository' | 'craft-directory' | 'design-document',
-//                path: string | null, exitCode: 1 }
-//
-// ⛔ `blockedOn` is carried through rather than flattened to an error string:
-//    a renderer must be able to tell "nothing is missing" from "I could not
-//    read the directory", and prose cannot be switched on reliably.
-//
-// Read-only · no auth (mirrors `/v1/worktrees` under the same same-origin
-// enforcement layer).
+// DESIGN.md comes from the configured harness.defaultRepo when present (no
+// fallback if it is invalid), otherwise the daemon's checkout. The craft and
+// bundled system directories always come from the elanous installation.
+// A blocked verdict is still a GET result, not an HTTP error. POST writes are
+// authenticated at http-server's /v1 owner-auth gate before this handler runs.
 
 import { readFileSync, readdirSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { isAbsolute, join, resolve } from 'node:path';
 
+import { debug } from '../../debug/log.js';
+import { applyDesignDirection, type ApplyDesignDirectionResult } from '../../design/apply-direction.js';
 import { designCheckExitCode, resolveDesignCheck, type DesignCheckDeps } from '../../design/design-check.js';
-import { directionFromDesignMd, listDesignDirections, parseDeclaredDirection } from '../../design/design-directions.js';
-import { jsonResponse } from './http-server.js';
+import { directionFromDesignMd, listAllDesignDirections, parseDeclaredDirection } from '../../design/design-directions.js';
+import { defaultDesignSystemsDir, listDesignSystems } from '../../design/design-systems.js';
+import { getUserConfig } from '../../user-config.js';
+import { jsonResponse } from './json-response.js';
 import { detectRepoRoot } from './worktrees.js';
 
 export interface DesignCheckRouteDeps extends DesignCheckDeps {
-  /** Active repository root, or null outside a checkout. Injected so the
-   *  route can be tested without spawning git. */
-  repoRoot: () => string | null;
+  /** Detect a checkout from the configured path, or from the daemon cwd. */
+  repoRoot: (cwd?: string) => string | null;
+  defaultRepo?: () => string | undefined;
   /** Absolute path of elanous's vendored craft rulebook directory. */
   craftDirectory: () => string;
 }
@@ -59,23 +39,44 @@ function installedCraftDirectory(): string {
   return resolve(import.meta.dir, '..', '..', '..', 'docs', 'design', 'craft');
 }
 
-const liveDeps: DesignCheckRouteDeps = {
+export const designCheckLiveDeps: DesignCheckRouteDeps = {
   readFile: (path, encoding) => readFileSync(path, encoding),
   readdir: (path) => readdirSync(path),
-  repoRoot: () => detectRepoRoot(),
+  repoRoot: (cwd) => detectRepoRoot(cwd === undefined ? {} : { cwd }),
+  defaultRepo: () => getUserConfig().harness?.defaultRepo,
   craftDirectory: installedCraftDirectory,
 };
 
-/** Pure — builds the wire body from injected reads. Exported for tests so the
- *  route's shape is pinned without booting an HTTP server. */
+const liveDeps: DesignCheckRouteDeps = designCheckLiveDeps;
+
+export interface DesignDirectionRouteDeps extends DesignCheckRouteDeps {
+  applyDirection: typeof applyDesignDirection;
+  logSelection: (repoRoot: string, direction: string) => void;
+}
+
+const directionDeps: Pick<DesignDirectionRouteDeps, 'applyDirection' | 'logSelection'> = {
+  applyDirection: applyDesignDirection,
+  logSelection: (repoRoot, direction) => debug.log('nexus.design-direction', 'selected', { repoRoot, direction }),
+};
+
+export type DesignRepository = { repoRoot: string | null; repoSource: 'config' | 'cwd' | null };
+
+/** Same repository the design-check verdict reads: harness.defaultRepo, else daemon cwd. */
+export function resolveDesignRepository(deps: DesignCheckRouteDeps): DesignRepository {
+  const configured = (deps.defaultRepo ?? (() => getUserConfig().harness?.defaultRepo))();
+  if (configured !== undefined) {
+    return { repoRoot: isAbsolute(configured) ? deps.repoRoot(configured) : null, repoSource: 'config' };
+  }
+  const repoRoot = deps.repoRoot();
+  return { repoRoot, repoSource: repoRoot ? 'cwd' : null };
+}
+
+/** Builds the wire body from injected reads. Exported for tests without booting HTTP. */
 export function buildDesignCheckView(overrides: Partial<DesignCheckRouteDeps> = {}): Record<string, unknown> {
   const deps = { ...liveDeps, ...overrides };
-  const repoRoot = deps.repoRoot();
+  const { repoRoot, repoSource } = resolveDesignRepository(deps);
   if (!repoRoot) {
-    // ⛔ Distinct from a read failure. "The daemon is not inside a checkout"
-    // is a deployment fact the operator can act on; collapsing it into
-    // `design-document` would send them hunting for a missing file instead.
-    return { repoRoot: null, ok: false, blockedOn: 'no-repository', path: null, exitCode: 1 };
+    return { repoRoot: null, repoSource, ok: false, blockedOn: 'no-repository', path: null, exitCode: 1 };
   }
   const outcome = resolveDesignCheck(
     join(repoRoot, 'DESIGN.md'),
@@ -84,7 +85,7 @@ export function buildDesignCheckView(overrides: Partial<DesignCheckRouteDeps> =
   );
   const exitCode = designCheckExitCode(outcome);
   if (!outcome.ok) {
-    return { repoRoot, ok: false, blockedOn: outcome.blockedOn, path: outcome.path, exitCode };
+    return { repoRoot, repoSource, ok: false, blockedOn: outcome.blockedOn, path: outcome.path, exitCode };
   }
   // B5 — 방향은 «같은 문서»에서 나온다. 두 번째 라우트를 만들면 두 번째
   // 「어느 저장소의 DESIGN.md 인가」 답이 생긴다. 여기서 같이 실어 보낸다.
@@ -95,23 +96,23 @@ export function buildDesignCheckView(overrides: Partial<DesignCheckRouteDeps> =
   try {
     document = deps.readFile(outcome.documentPath, 'utf8');
   } catch { /* 방금 읽힌 문서다. 사라졌으면 「선언 없음」과 같은 화면이 맞다. */ }
-  // ⭐ 방향은 «둘»에서 온다: 테마 레지스트리(여섯) ⊕ ***이 문서 자신***.
-  //    🩸 2026-09-08 실측: 여섯은 전부 «터미널 색 스킴»이라 웹 레퍼런스에서 뽑은 팔레트·서체는
-  //       ***어느 이름으로도 선언할 수 없었다*** — 선언하면 늘 `unavailable` 로 떨어졌다.
-  //    ⛔ 문서 방향을 «항상» 만들지 않는다. 선언이 테마에 없을 때만 «그 이름으로» 시도한다 —
-  //       그래야 오타가 조용히 「스스로 선언한 방향」으로 둔갑하지 않는다(팔레트를 못 읽으면 null).
-  const themeDirections = listDesignDirections();
-  const declaredAmongThemes = parseDeclaredDirection(document, themeDirections);
-  const documentDirection = declaredAmongThemes.unavailable === null
+  // Bundled terminal themes and web systems are selectable; a document-defined
+  // direction is added only when its declared ID is not already bundled and
+  // its palette supplies a usable swatch (never turn a typo into a direction).
+  const bundledDirections = listAllDesignDirections();
+  const declaredAmongBundled = parseDeclaredDirection(document, bundledDirections);
+  const documentDirection = declaredAmongBundled.unavailable === null
     ? null
-    : directionFromDesignMd(document, declaredAmongThemes.unavailable);
+    : directionFromDesignMd(document, declaredAmongBundled.unavailable);
   const availableDirections = documentDirection === null
-    ? themeDirections
-    : [...themeDirections, documentDirection];
+    ? bundledDirections
+    : [...bundledDirections, documentDirection];
+  const systemCategories = new Map(listDesignSystems(defaultDesignSystemsDir()).map((system) => [system.id, system.category]));
   const direction = parseDeclaredDirection(document, availableDirections);
 
   return {
     repoRoot,
+    repoSource,
     ok: true,
     documentPath: outcome.documentPath,
     craftDirectory: outcome.craftDirectory,
@@ -123,9 +124,9 @@ export function buildDesignCheckView(overrides: Partial<DesignCheckRouteDeps> =
       declared: direction.declared,
       unavailable: direction.unavailable,
       available: availableDirections.map((d) => ({
-        id: d.id, mood: d.mood, isDark: d.isDark, isPastel: d.isPastel, swatch: d.swatch,
-        // ⛔ 「테마에서 왔다」와 「이 문서가 스스로 정했다」를 화면이 가를 수 있어야 한다.
+        id: d.id, label: d.label, mood: d.mood, isDark: d.isDark, isPastel: d.isPastel, swatch: d.swatch,
         source: d.source ?? 'theme', typography: d.typography ?? null,
+        category: systemCategories.get(d.id) ?? null,
       })),
     },
   };
@@ -138,3 +139,33 @@ export function buildDesignCheckView(overrides: Partial<DesignCheckRouteDeps> =
 export function handleDesignCheck(): Response {
   return jsonResponse(buildDesignCheckView(), 200);
 }
+
+/** The HTTP dispatcher must run owner checkAuth before invoking this write handler. */
+export async function handleDesignDirectionPost(
+  req: Request,
+  overrides: Partial<DesignDirectionRouteDeps> = {},
+): Promise<Response> {
+  let body: unknown;
+  try { body = await req.json(); }
+  catch { return jsonResponse({ ok: false, reason: 'invalid-json' }, 400); }
+  if (!body || typeof body !== 'object' || Array.isArray(body)
+    || typeof (body as { id?: unknown }).id !== 'string'
+    || !(body as { id: string }).id.trim()) {
+    return jsonResponse({ ok: false, reason: 'id-required' }, 400);
+  }
+  const id = (body as { id: string }).id;
+  const deps = { ...liveDeps, ...directionDeps, ...overrides };
+  const { repoRoot, repoSource } = resolveDesignRepository(deps);
+  if (!repoRoot) return jsonResponse({ ok: false, reason: 'no-repository', repoRoot, repoSource }, 409);
+  let result: ApplyDesignDirectionResult;
+  try { result = deps.applyDirection(join(repoRoot, 'DESIGN.md'), id); }
+  catch (error) {
+    debug.log('nexus.design-direction', 'failed', { repoRoot, direction: id, error: String(error) }, { level: 'error' });
+    return jsonResponse({ ok: false, reason: 'cannot-write' }, 500);
+  }
+  if (!result.ok) {
+    return jsonResponse(result, result.reason === 'unknown-direction' ? 400 : result.reason === 'conflicting-system-file' ? 409 : 500);
+  }
+  deps.logSelection(repoRoot, id);
+  return jsonResponse({ ...result, repoRoot, repoSource }, 200);
+}

package/src/nexus/api/design-previews-route.ts

@@ -0,0 +1,182 @@
+// NEXUS · GET /v1/design-previews and GET /v1/design-previews/<system>
+//
+// RFC design loop §A2 — HTML previews written under
+// `<repo>/design/previews/<system>.html`. The repository is the same one
+// `GET /v1/design-check` reads (`resolveDesignRepository`). Preview HTML is
+// untrusted agent output: this route only returns the file bytes. The PWA
+// paints them in a sandboxed iframe with no scripts and no same-origin.
+
+import { readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+
+import { debug } from '../../debug/log.js';
+import {
+  designCheckLiveDeps,
+  resolveDesignRepository,
+} from './design-check.js';
+import { jsonResponse } from './json-response.js';
+import { DESIGN_PREVIEW_PATH_PREFIX, DESIGN_PREVIEWS_PATH } from './rest-route-paths.js';
+
+/** `<system>.html` — system id is the stem of this pattern. */
+export const PREVIEW_FILE_RE = /^[a-z0-9][a-z0-9-]*\.html$/;
+export const PREVIEW_SYSTEM_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+/** 512 KiB. Larger documents are refused rather than streamed into the PWA. */
+export const PREVIEW_MAX_BYTES = 512 * 1024;
+
+export interface DesignPreviewEntry {
+  system: string;
+  bytes: number;
+  modifiedAt: string;
+}
+
+export interface DesignPreviewsRouteDeps {
+  resolveRepository: () => { repoRoot: string | null; repoSource: 'config' | 'cwd' | null };
+  readdir: (path: string) => string[];
+  stat: (path: string) => { size: number; mtimeMs: number };
+  readFile: (path: string) => string;
+  realpath: (path: string) => string;
+}
+
+const liveDeps: DesignPreviewsRouteDeps = {
+  resolveRepository: () => resolveDesignRepository(designCheckLiveDeps),
+  readdir: (path) => readdirSync(path),
+  stat: (path) => {
+    const st = statSync(path);
+    return { size: st.size, mtimeMs: st.mtimeMs };
+  },
+  readFile: (path) => readFileSync(path, 'utf8'),
+  realpath: (path) => realpathSync(path),
+};
+
+function previewsDir(repoRoot: string): string {
+  return join(repoRoot, 'design', 'previews');
+}
+
+function isInsidePreviews(previewsRoot: string, candidate: string): boolean {
+  const root = previewsRoot.endsWith(sep) ? previewsRoot : previewsRoot + sep;
+  return candidate === previewsRoot || candidate.startsWith(root);
+}
+
+export function listDesignPreviews(
+  overrides: Partial<DesignPreviewsRouteDeps> = {},
+): { repoRoot: string | null; repoSource: 'config' | 'cwd' | null; previews: DesignPreviewEntry[] } {
+  const deps = { ...liveDeps, ...overrides };
+  const { repoRoot, repoSource } = deps.resolveRepository();
+  if (!repoRoot) {
+    debug.log('design.previews', 'listed', { repoRoot, reason: 'no-repository' });
+    return { repoRoot, repoSource, previews: [] };
+  }
+  const dir = previewsDir(repoRoot);
+  let names: string[];
+  try {
+    names = deps.readdir(dir);
+  } catch {
+    debug.log('design.previews', 'listed', { repoRoot, reason: 'no-directory' });
+    return { repoRoot, repoSource, previews: [] };
+  }
+  // The list must not reveal what serving refuses: a link that escapes
+  // design/previews/ would otherwise leak its target's size and time here.
+  let rootReal: string | null = null;
+  try { rootReal = resolve(deps.realpath(dir)); } catch { rootReal = null; }
+  const previews: DesignPreviewEntry[] = [];
+  for (const name of names) {
+    if (!PREVIEW_FILE_RE.test(name)) continue;
+    const file = join(dir, name);
+    let fileReal: string;
+    try { fileReal = resolve(deps.realpath(file)); }
+    catch { continue; }
+    if (!rootReal || !isInsidePreviews(rootReal, fileReal)) continue;
+    let st: { size: number; mtimeMs: number };
+    try { st = deps.stat(fileReal); }
+    catch { continue; }
+    previews.push({
+      system: name.slice(0, -'.html'.length),
+      bytes: st.size,
+      modifiedAt: new Date(st.mtimeMs).toISOString(),
+    });
+  }
+  previews.sort((a, b) => a.system.localeCompare(b.system));
+  debug.log('design.previews', 'listed', { repoRoot });
+  return { repoRoot, repoSource, previews };
+}
+
+export type ServePreviewResult =
+  | { status: 200; body: { system: string; html: string } }
+  | { status: 400 | 404 | 413; body: { error: string; reason: string } };
+
+export function serveDesignPreview(
+  system: string,
+  overrides: Partial<DesignPreviewsRouteDeps> = {},
+): ServePreviewResult {
+  const deps = { ...liveDeps, ...overrides };
+  const { repoRoot } = deps.resolveRepository();
+  if (!PREVIEW_SYSTEM_RE.test(system) || system.includes('..') || system.includes('/') || system.includes('\\')) {
+    debug.log('design.previews', 'refused', { repoRoot, system, reason: 'bad-name' });
+    return { status: 400, body: { error: 'bad-name', reason: 'bad-name' } };
+  }
+  if (!repoRoot) {
+    debug.log('design.previews', 'refused', { repoRoot, system, reason: 'no-repository' });
+    return { status: 404, body: { error: 'not-found', reason: 'no-repository' } };
+  }
+  const dir = previewsDir(repoRoot);
+  let rootReal: string;
+  try { rootReal = deps.realpath(dir); }
+  catch {
+    debug.log('design.previews', 'refused', { repoRoot, system, reason: 'not-found' });
+    return { status: 404, body: { error: 'not-found', reason: 'not-found' } };
+  }
+  const file = join(dir, `${system}.html`);
+  let fileReal: string;
+  try { fileReal = deps.realpath(file); }
+  catch {
+    debug.log('design.previews', 'refused', { repoRoot, system, reason: 'not-found' });
+    return { status: 404, body: { error: 'not-found', reason: 'not-found' } };
+  }
+  if (!isInsidePreviews(resolve(rootReal), resolve(fileReal))) {
+    debug.log('design.previews', 'refused', { repoRoot, system, reason: 'escape' });
+    return { status: 404, body: { error: 'not-found', reason: 'escape' } };
+  }
+  let st: { size: number; mtimeMs: number };
+  try { st = deps.stat(fileReal); }
+  catch {
+    debug.log('design.previews', 'refused', { repoRoot, system, reason: 'not-found' });
+    return { status: 404, body: { error: 'not-found', reason: 'not-found' } };
+  }
+  if (st.size > PREVIEW_MAX_BYTES) {
+    debug.log('design.previews', 'refused', { repoRoot, system, reason: 'too-large' });
+    return { status: 413, body: { error: 'too-large', reason: 'too-large' } };
+  }
+  let html: string;
+  try { html = deps.readFile(fileReal); }
+  catch {
+    debug.log('design.previews', 'refused', { repoRoot, system, reason: 'not-found' });
+    return { status: 404, body: { error: 'not-found', reason: 'not-found' } };
+  }
+  debug.log('design.previews', 'served', { repoRoot, system });
+  return { status: 200, body: { system, html } };
+}
+
+function systemFromPath(pathname: string): string | null {
+  if (pathname === DESIGN_PREVIEWS_PATH) return null;
+  if (!pathname.startsWith(DESIGN_PREVIEW_PATH_PREFIX)) return null;
+  const raw = pathname.slice(DESIGN_PREVIEW_PATH_PREFIX.length);
+  if (!raw || raw.includes('/')) return '';
+  try { return decodeURIComponent(raw); }
+  catch { return raw; }
+}
+
+/** GET dispatcher. Auth is the shared `/v1` owner gate in http-server. */
+export function handleDesignPreviews(pathname: string, overrides: Partial<DesignPreviewsRouteDeps> = {}): Response {
+  if (pathname === DESIGN_PREVIEWS_PATH) {
+    return jsonResponse(listDesignPreviews(overrides), 200);
+  }
+  const system = systemFromPath(pathname);
+  if (system === null || system === '') {
+    const { repoRoot } = (overrides.resolveRepository ?? liveDeps.resolveRepository)();
+    debug.log('design.previews', 'refused', { repoRoot, reason: 'bad-name' });
+    return jsonResponse({ error: 'bad-name', reason: 'bad-name' }, 400);
+  }
+  const result = serveDesignPreview(system, overrides);
+  return jsonResponse(result.body, result.status);
+}

package/src/nexus/api/design-system-create-route.ts

@@ -0,0 +1,123 @@
+// POST /v1/design-system — URL 또는 팔레트로 라이브러리에 시스템을 하나 만든다.
+// 소유자 인증은 디스패처가 본문을 읽기 전에 한다. 이 핸들러는 그 뒤에만 호출된다.
+// 한 번에 하나만: 진행 중이면 429.
+
+import { debug } from '../../debug/log.js';
+import {
+  createCustomSystemFromPalette,
+  createCustomSystemFromUrl,
+  type CustomSystemCreateDeps,
+  type CustomSystemCreateResult,
+} from '../../design/custom-system-create.js';
+import { jsonResponse } from './json-response.js';
+
+export interface DesignSystemCreateRouteDeps extends CustomSystemCreateDeps {
+  readonly log?: (event: 'created' | 'refused', data: Record<string, unknown>) => void;
+}
+
+let inFlight = false;
+
+export function designSystemCreateInFlight(): boolean {
+  return inFlight;
+}
+
+/** 시험이 프로세스 전역 잠금을 비운다. */
+export function resetDesignSystemCreateGate(): void {
+  inFlight = false;
+}
+
+function hostOnly(url: string): string | undefined {
+  try {
+    return new URL(url).hostname || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function statusFor(result: Extract<CustomSystemCreateResult, { ok: false }>): number {
+  switch (result.reason) {
+    case 'id-taken': return 409;
+    case 'extract-failed': return 502;
+    default: return 400;
+  }
+}
+
+function wire(result: CustomSystemCreateResult): Record<string, unknown> {
+  if (!result.ok) {
+    return { ok: false, reason: result.reason, ...(result.detail === undefined ? {} : { detail: result.detail }) };
+  }
+  return {
+    ok: true,
+    id: result.id,
+    dir: result.dir,
+    tokens: result.tokens,
+    unread: result.unread,
+    warnings: result.warnings,
+    ...(result.extractDir === undefined ? {} : { extractDir: result.extractDir }),
+  };
+}
+
+export async function handleDesignSystemCreate(
+  req: Request,
+  overrides: DesignSystemCreateRouteDeps = {},
+): Promise<Response> {
+  const log = overrides.log ?? ((event: 'created' | 'refused', data: Record<string, unknown>) => {
+    debug.log('design.custom', event, data);
+  });
+  if (inFlight) {
+    log('refused', { reason: 'busy' });
+    return jsonResponse({ ok: false, reason: 'busy' }, 429);
+  }
+  inFlight = true;
+  const started = Date.now();
+  try {
+    let body: unknown;
+    try { body = await req.json(); }
+    catch { return jsonResponse({ ok: false, reason: 'invalid-json' }, 400); }
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+      return jsonResponse({ ok: false, reason: 'invalid-body' }, 400);
+    }
+    const record = body as { kind?: unknown; url?: unknown; colors?: unknown; id?: unknown; name?: unknown; base?: unknown };
+    const id = typeof record.id === 'string' ? record.id : undefined;
+    const name = typeof record.name === 'string' ? record.name : undefined;
+    const base = typeof record.base === 'string' ? record.base : undefined;
+    const deps: CustomSystemCreateDeps = overrides;
+
+    let result: CustomSystemCreateResult;
+    let kind: 'url' | 'palette';
+    let host: string | undefined;
+    if (record.kind === 'url') {
+      kind = 'url';
+      if (typeof record.url !== 'string' || !record.url.trim()) {
+        log('refused', { kind, reason: 'bad-url', ms: Date.now() - started });
+        return jsonResponse({ ok: false, reason: 'bad-url' }, 400);
+      }
+      host = hostOnly(record.url);
+      result = await createCustomSystemFromUrl({ url: record.url, id, name, base }, deps);
+    } else if (record.kind === 'palette') {
+      kind = 'palette';
+      if (!Array.isArray(record.colors) || record.colors.some((color) => typeof color !== 'string')) {
+        log('refused', { kind, reason: 'no-colors', ms: Date.now() - started });
+        return jsonResponse({ ok: false, reason: 'no-colors' }, 400);
+      }
+      if (typeof record.id !== 'string' || !record.id.trim()) {
+        log('refused', { kind, reason: 'bad-id', ms: Date.now() - started });
+        return jsonResponse({ ok: false, reason: 'bad-id' }, 400);
+      }
+      result = await createCustomSystemFromPalette({ colors: record.colors, id: record.id, name, base }, deps);
+    } else {
+      log('refused', { reason: 'bad-kind', ms: Date.now() - started });
+      return jsonResponse({ ok: false, reason: 'bad-kind' }, 400);
+    }
+
+    const ms = Date.now() - started;
+    if (!result.ok) {
+      log('refused', { kind, ...(host ? { host } : {}), ...(result.detail && result.reason === 'id-taken' ? { id: result.detail } : {}), reason: result.reason, ms });
+      return jsonResponse(wire(result), statusFor(result));
+    }
+    log('created', { kind, id: result.id, ...(host ? { host } : {}), ms });
+    return jsonResponse(wire(result), 201);
+  } finally {
+    inFlight = false;
+  }
+}