@ryan_nookpi/pi-skill-excalidraw 0.1.0

package/skills/excalidraw/references/skeleton.md

@@ -0,0 +1,84 @@
+# 스켈레톤 작성 규칙
+
+`version` 필드가 없는 요소는 스켈레톤으로 취급한다. 창이 열리면 앱이 공식 `convertToExcalidrawElements`(id 유지)로 정식 요소로 바꾸고 파일을 다시 저장한다. 그 뒤 파일에는 `version`, `seed`, `boundElements` 같은 필드가 붙는다. 스켈레톤과 정식 요소는 한 파일에 섞여 있어도 된다.
+
+공식 문서: <https://docs.excalidraw.com/docs/@excalidraw/excalidraw/api/excalidraw-element-skeleton>
+
+## 파일 뼈대
+
+```json
+{
+  "type": "excalidraw",
+  "version": 2,
+  "source": "pi-excalidraw",
+  "elements": [],
+  "appState": { "viewBackgroundColor": "#ffffff", "gridSize": 20 },
+  "files": {}
+}
+```
+
+## 도형과 라벨
+
+`rectangle` / `ellipse` / `diamond`. 모든 도형에 의미 있는 `id`와 `x`, `y`, `width`, `height`를 준다. 화살표 자동 연결과 lint가 이 값에 의존한다.
+
+```json
+{ "type": "rectangle", "id": "api", "x": 100, "y": 100, "width": 200, "height": 72,
+  "backgroundColor": "#a5d8ff", "fillStyle": "solid", "roundness": { "type": 3 },
+  "label": { "text": "API 서버" } }
+```
+
+- `label`: `text`(필수), `fontSize`(기본 20), `strokeColor`, `textAlign`(`left|center|right`), `verticalAlign`(`top|middle|bottom`). 줄바꿈은 `\n`.
+- `roundness: { "type": 3 }`: 모서리가 둥근 사각형. 생략하면 직각이다.
+
+## 텍스트
+
+```json
+{ "type": "text", "id": "title", "x": 100, "y": 20, "text": "결제 흐름", "fontSize": 28 }
+```
+
+크기는 앱이 측정하니 `width`/`height`는 생략한다.
+
+## 화살표와 선
+
+가장 쉬운 형태는 좌표 없이 연결할 두 요소의 id만 적는 것이다. 앱이 두 도형의 중심을 잇고 가장자리에서 끊어 좌표를 계산한 뒤 바인딩한다.
+
+```json
+{ "type": "arrow", "id": "api-db", "start": { "id": "api" }, "end": { "id": "db" }, "label": { "text": "SQL" } }
+```
+
+직접 경로를 지정하려면 `x`, `y`와 상대 좌표 `points`를 준다. 꺾인 선은 점을 3개 이상 둔다.
+
+```json
+{ "type": "arrow", "id": "loop", "x": 300, "y": 136, "points": [[0,0],[60,0],[60,-120],[-100,-120]],
+  "start": { "id": "b" }, "end": { "id": "a" } }
+```
+
+- `startArrowhead` / `endArrowhead`: `null | "arrow" | "triangle" | "bar" | "circle" | "diamond"`, ERD용 `"crowfoot_one" | "crowfoot_many" | "crowfoot_one_or_many"`. 화살표 기본값은 끝에만 `arrow`.
+- 연결 없는 선: `{ "type": "line", "x": 0, "y": 400, "points": [[0,0],[800,0]], "strokeStyle": "dashed" }`
+- 양방향: `"startArrowhead": "arrow"`
+
+## 프레임(묶음 박스)
+
+```json
+{ "type": "frame", "id": "vpc", "name": "VPC", "children": ["api", "db"] }
+```
+
+frame 크기는 자식과 자식에 연결된 화살표까지 감싸도록 자동 계산된다(`x`/`y`/`width`는 무시). 그래서 frame 밖으로 이어지는 화살표가 있으면 frame이 그쪽으로 늘어난다. 그런 경우와 단순히 영역만 보여주려면 프레임 대신 큰 `rectangle`(배경 투명, `strokeStyle: "dashed"`)을 먼저 배치하고 안에 도형을 둔다. 완전히 감싸는 도형끼리의 포함 관계는 lint가 겹침으로 보지 않는다.
+
+## 공통 스타일 속성
+
+| 속성 | 값 |
+|---|---|
+| `strokeColor` / `backgroundColor` | hex 또는 `"transparent"` |
+| `fillStyle` | `hachure`(기본, 빗금) · `cross-hatch` · `solid` · `zigzag` |
+| `strokeWidth` | `1` · `2`(기본) · `4` |
+| `strokeStyle` | `solid` · `dashed` · `dotted` |
+| `roughness` | `0` 반듯함 · `1` 손그림(기본) · `2` 더 거칠게 |
+| `opacity` | 0–100 |
+| `fontFamily` | `5` Excalifont(기본, 손글씨, 한글 손글씨 폰트 지원) · `6` Nunito · `8` Comic Shanns · `3` Cascadia(코드) |
+
+## 정식 요소를 고칠 때
+
+- 이동: 도형의 `x`/`y`만 바꾼다. 안의 라벨과 연결된 직선 화살표는 앱이 다시 맞춘다.
+- 라벨 텍스트: 도형을 스켈레톤으로 다시 쓰는 것이 가장 안전하다. `version`, `versionNonce`, `seed`, `boundElements`를 빼고 `id`, 좌표, 스타일, `label`만 남긴다. 기존 라벨 텍스트 요소는 앱이 지운다.
+- 화살표 경로 초기화: 화살표를 `{ "type": "arrow", "id": "<같은 id>", "start": {"id": …}, "end": {"id": …} }`로 다시 쓴다. 라벨이 있었다면 `label`도 다시 넣는다.

package/skills/excalidraw/references/style.md

@@ -0,0 +1,46 @@
+# 스타일과 레이아웃
+
+## 팔레트 (Excalidraw 기본 색)
+
+| 용도 | 배경 `backgroundColor` | 선 `strokeColor` |
+|---|---|---|
+| 기본 처리·서비스 | `#a5d8ff` | `#1971c2` |
+| 시작·성공·완료 | `#b2f2bb` | `#2f9e44` |
+| 판단·주의 | `#ffec99` | `#f08c00` |
+| 오류·실패·외부 위험 | `#ffc9c9` | `#e03131` |
+| 저장소·DB | `#d0bfff` | `#6741d9` |
+| 외부 시스템·사용자 | `#e9ecef` | `#495057` |
+| 강조 메모 | `#fff3bf` | `#e67700` |
+
+- 한 그림에 의미 색은 4개 이하로 쓴다. 나머지는 흰 배경에 기본 선(`#1e1e1e`).
+- 채움은 `fillStyle: "solid"`가 읽기 편하다. 손그림 느낌을 강하게 원하면 기본 `hachure`로 둔다.
+- 글꼴은 기본(Excalifont)을 유지한다. 한글도 손글씨 폰트로 나온다. 다른 폰트는 한글이 시스템 폰트로 대체된다.
+
+## 크기와 간격 (20px 그리드 기준)
+
+- 일반 노드 `200×72`, 긴 라벨 노드 `240×80`, 판단 다이아몬드 `220×120`, 시작/끝 타원 `160×64`.
+- 라벨 폰트 20, 제목 28–36, 보조 설명 16.
+- 라벨 폭 추정: 한글 한 글자 ≈ fontSize, 영문 ≈ 0.55×fontSize. 좌우 여백 24px를 더한 값이 `width`보다 크면 너비를 늘리거나 `\n`으로 줄을 나눈다.
+- 노드 사이 간격: 라벨 없는 화살표 60px 이상, 라벨 있는 화살표 120px 이상(라벨이 화살표 위에 올라간다).
+- 좌표는 20의 배수로 맞춘다. 같은 열의 노드는 `x`를, 같은 행은 `y`를 똑같이 둔다.
+
+## 레시피
+
+**세로 플로우차트**: 한 열에 `x` 고정, 노드 높이 72 + 간격 60 → 행 간격 140(라벨 화살표가 있으면 180). 분기는 다이아몬드 오른쪽으로 320px 떨어진 열에 둔다. 제목은 맨 위 `y=20`.
+
+**가로 파이프라인**: 한 행에 `y` 고정, 노드 폭 200 + 간격 100 → 열 간격 300. 5단계를 넘으면 두 줄로 접고 줄 끝에서 꺾인 화살표로 잇는다.
+
+**아키텍처(계층)**: 위에서 아래로 클라이언트 → 엣지/게이트웨이 → 서비스 → 데이터 계층. 계층마다 점선 `rectangle`(배경 투명, 선 `#868e96`)으로 감싸고 왼쪽 위에 16px 텍스트로 계층 이름을 둔다. 계층 간 세로 간격 80 이상.
+
+**시퀀스**: 참여자를 가로로 240px 간격에 두고, 각 아래로 점선 `line`(생명선)을 그린다. 메시지는 `y`를 50px씩 내리며 수평 `arrow`에 `label`을 단다. 응답은 `strokeStyle: "dashed"`. 참여자가 5개를 넘거나 메시지가 15개를 넘으면 Mermaid `sequenceDiagram`으로 가져온다.
+
+**마인드맵**: 중심 타원을 가운데 두고 1차 가지는 반지름 300 원 위에, 2차는 바깥 180px에 둔다. 가지별로 색을 하나씩 준다.
+
+**와이어프레임**: `roughness: 0`이 아니라 기본값 1을 유지해 스케치임을 드러낸다. 화면 프레임 `rectangle` 안에 영역 박스를 배치하고, 버튼은 `roundness: {type: 3}` 작은 사각형, 텍스트 자리는 회색 `line`으로 표현한다.
+
+## 셀프 체크 (snapshot 볼 때)
+
+- 라벨이 도형 밖으로 넘치거나 두 줄로 어색하게 접히지 않았는가
+- 화살표 라벨이 노드와 겹치지 않는가
+- 화살표가 다른 노드를 관통하지 않는가 (관통하면 노드를 옮기거나 `points`로 우회)
+- 색이 의미대로 쓰였는가, 제목이 있는가

package/skills/excalidraw/references/sync-protocol.md

@@ -0,0 +1,47 @@
+# 앱 내부 구조 (유지보수용)
+
+## 구성
+
+- `scripts/excal.mjs`: CLI. 빌드 확인, 데몬 기동, 파일 등록, Chrome `--app` 창 실행, lint/inspect.
+- `scripts/server.mjs`: Node 내장 모듈만 쓰는 데몬. `127.0.0.1`에만 바인딩. 기본 포트 47813(사용 중이면 임의 포트). 창 푸시는 최소 WebSocket 구현(서버→창 텍스트 프레임, 20초 ping). SSE는 Chrome의 origin당 HTTP/1.1 연결 6개를 창마다 하나씩 차지해 6번째 창부터 모든 요청이 막히므로 쓰지 않는다.
+- `app/`: Vite + React + `@excalidraw/excalidraw` 0.18.1 + `@excalidraw/mermaid-to-excalidraw`. `app/src/scene.js`에 변환·병합 순수 로직, `app/src/main.jsx`에 동기화 로직.
+- 상태: `~/.cache/pi-excalidraw/` (`EXCAL_STATE_DIR`로 변경). `server.json`(pid/port), `token`, `files.json`(id→경로), `history/<id>/`, `snapshots/`, `server.log`, `chrome-profile/`.
+
+## 환경 변수
+
+| 변수 | 용도 |
+|---|---|
+| `EXCAL_STATE_DIR` | 상태 디렉터리 |
+| `EXCAL_PORT` | 선호 포트 |
+| `EXCAL_IDLE_MINUTES` | 무접속 자동 종료(기본 30) |
+| `EXCAL_BROWSER=none` | 창을 띄우지 않음 |
+| `EXCAL_CHROME_ARGS` | Chrome 추가 인자 (예: `--remote-debugging-port=9333`) |
+
+## 동기화
+
+- 파일 id는 실제 경로의 sha1 앞 12자리. 창 URL은 `/?file=<id>&token=<token>`.
+- 창은 `ws://…/api/files/<id>/ws?clientId&token`에 붙는다. 메시지는 `{event, data}` JSON이고 event는 `hello`·`scene`·`snapshot`·`problem`. 끊기면 지수 백오프(최대 5초)로 재접속하고 `hello`를 받으면 최신 scene을 GET한다.
+- 서버는 파일이 아니라 디렉터리를 `fs.watch`한다(임시 파일 + rename 저장 대응). 80ms debounce 후 해시가 바뀌었고 JSON이 유효하면 `rev`를 올리고 `scene` 이벤트로 내용을 보낸다. 받아들이기 직전 내용은 `history/`에 백업한다.
+- 창은 PUT `/api/files/<id>/scene`에 `{baseRev, content, clientId}`를 보낸다. `baseRev`가 현재 `rev`와 다르면 409와 최신 내용을 돌려준다. 서버는 자기가 쓴 해시를 기억해 watch 에코를 무시한다.
+- 창의 원격 반영 순서:
+  1. `pendingMermaid`가 있으면 mermaid 결과로 요소 전체 교체.
+  2. 스켈레톤 정규화(`convertMixed`). 정식 frame에는 `children: []`를 넣어 변환기 크래시를 막는다.
+  3. `repairScene`: 도형 이동에 따른 직선 화살표 재계산, 바인딩 역참조 보강.
+  4. `restoreElements(remote, local, {refreshDimensions, repairBindings})`: 텍스트 재측정, 끊긴 바인딩 제거.
+  5. `recenterLabels`: 재측정된 크기로 라벨을 도형 안에 다시 정렬.
+  6. 저장 안 된 로컬 변경이 있으면 `threeWayMerge`.
+  7. 파일에서 사라진 요소는 `isDeleted` tombstone으로, 내용이 바뀐 요소는 `version+1`·새 `versionNonce`로 만든다. Excalidraw Store는 versionNonce로 변경을 감지하므로 이게 없으면 LLM 변경이 히스토리에 안 남고, 이후 Cmd+Z가 LLM 이전 값으로 되감긴다.
+  8. `updateScene({captureUpdate: IMMEDIATELY})`, 바뀐 요소는 토스트로만 알린다(선택 상태는 건드리지 않음).
+  9. 1–5단계에서 내용이 바뀌었거나 병합으로 로컬 변경이 남았으면 곧바로 파일에 다시 저장한다.
+- 3-way 기준선: 마지막 동기화 시점의 요소별 `{version, contentKey}`. 로컬만 바뀐 요소는 로컬, 원격이 바뀐 요소는 원격이 이긴다.
+- 로컬 편집 저장: `onChange`에서 요소 version 합이 바뀐 경우만 400ms debounce 후 PUT.
+- 스냅샷: CLI → POST `/snapshot` → 서버가 첫 번째 연결 창에 `snapshot {reqId, rev}` → 창이 해당 rev 반영까지 최대 5초 대기 후 `exportToBlob` → POST `/api/snapshots/<reqId>` → CLI가 PNG 저장. 창이 그 rev를 반영하지 못했으면(마지막 반영 오류 포함) PNG 대신 에러 JSON을 보내고 CLI는 실패로 끝난다.
+
+## 보안
+
+- `127.0.0.1` 바인딩, Host 헤더 검사(`127.0.0.1:<port>`, `localhost:<port>`만 허용, WebSocket upgrade 포함), `/api/*`는 토큰(`x-excal-token` 헤더 또는 `token` 쿼리) 필수.
+- 읽기·쓰기는 `excal open`으로 등록한 파일만 가능하다.
+
+## 폰트
+
+빌드할 때 `node_modules/@excalidraw/excalidraw/dist/prod/fonts`를 `dist/fonts`로 복사하고 `window.EXCALIDRAW_ASSET_PATH = "/"`로 로컬에서 서빙한다(오프라인 동작, 한글은 Xiaolai 손글씨 대체 폰트). 로컬 로드에 실패하면 Excalidraw가 CDN으로 폴백한다.

package/skills/excalidraw/scripts/excal.mjs

@@ -0,0 +1,416 @@
+#!/usr/bin/env node
+// excal: open .excalidraw files in a live-synced local Excalidraw window,
+// inspect/lint them, and take PNG snapshots for visual self-checks.
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import {
+	APP_DIR,
+	CHROME_PROFILE_DIR,
+	DIST_DIR,
+	emptyScene,
+	ensureStateDir,
+	fileIdFor,
+	HISTORY_DIR,
+	LOG_FILE,
+	readJSON,
+	readToken,
+	realPathOf,
+	SKILL_DIR,
+	SNAPSHOT_DIR,
+	STATE_FILE,
+	writeFileAtomic,
+} from "./lib.mjs";
+
+const USAGE = `usage:
+  excal open <file.excalidraw> [--from-mermaid <file.mmd>] [--no-window]
+  excal inspect <file.excalidraw>
+  excal lint <file.excalidraw>
+  excal snapshot <file.excalidraw> [-o out.png]
+  excal history <file.excalidraw>
+  excal status | stop | build`;
+
+const die = (msg, code = 1) => {
+	console.error(msg);
+	process.exit(code);
+};
+
+// ---------- build / server ----------
+
+function ensureBuilt(force = false) {
+	if (!force && fs.existsSync(path.join(DIST_DIR, "index.html"))) return;
+	const pm = spawnSync("pnpm", ["--version"]).status === 0 ? "pnpm" : "npm";
+	if (!fs.existsSync(path.join(APP_DIR, "node_modules"))) {
+		console.error(`[excal] 첫 실행: ${pm} install (1회만)`);
+		const r = spawnSync(pm, ["install"], { cwd: APP_DIR, stdio: ["ignore", 2, 2] });
+		if (r.status !== 0) die("[excal] install 실패");
+	}
+	console.error("[excal] 앱 빌드 중");
+	const r = spawnSync(pm, ["run", "build"], { cwd: APP_DIR, stdio: ["ignore", 2, 2] });
+	if (r.status !== 0) die("[excal] build 실패");
+}
+
+async function call(port, token, pathname, init = {}) {
+	return fetch(`http://127.0.0.1:${port}${pathname}`, {
+		...init,
+		headers: { "x-excal-token": token, "content-type": "application/json", ...(init.headers || {}) },
+	});
+}
+
+async function healthy(state, token) {
+	if (!state?.port) return false;
+	try {
+		const r = await call(state.port, token, "/api/health", { signal: AbortSignal.timeout(1000) });
+		return r.ok;
+	} catch {
+		return false;
+	}
+}
+
+async function ensureServer() {
+	ensureStateDir();
+	ensureBuilt();
+	const token = readToken();
+	let state = readJSON(STATE_FILE, null);
+	if (await healthy(state, token)) return { port: state.port, token };
+	const log = fs.openSync(LOG_FILE, "a");
+	spawn(process.execPath, [path.join(SKILL_DIR, "scripts", "server.mjs")], {
+		detached: true,
+		stdio: ["ignore", log, log],
+	}).unref();
+	for (let i = 0; i < 50; i++) {
+		await new Promise((r) => setTimeout(r, 200));
+		state = readJSON(STATE_FILE, null);
+		if (await healthy(state, token)) return { port: state.port, token };
+	}
+	die(`[excal] 서버 시작 실패. 로그: ${LOG_FILE}`);
+}
+
+async function register(srv, file) {
+	const r = await call(srv.port, srv.token, "/api/files", { method: "POST", body: JSON.stringify({ path: file }) });
+	if (!r.ok) die(`[excal] 파일 등록 실패: ${await r.text()}`);
+	return r.json();
+}
+
+function chromeCommand(url) {
+	const args = [
+		`--app=${url}`,
+		`--user-data-dir=${CHROME_PROFILE_DIR}`,
+		"--no-first-run",
+		"--no-default-browser-check",
+		"--window-size=1440,960",
+		...(process.env.EXCAL_CHROME_ARGS ? process.env.EXCAL_CHROME_ARGS.split(/\s+/).filter(Boolean) : []),
+	];
+	if (process.platform === "darwin") return ["open", ["-na", "Google Chrome", "--args", ...args]];
+	for (const bin of ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser"]) {
+		if (spawnSync("which", [bin]).status === 0) return [bin, args];
+	}
+	return null;
+}
+
+async function openWindow(srv, info) {
+	if (process.env.EXCAL_BROWSER === "none") return false;
+	const cmd = chromeCommand(info.url);
+	if (!cmd) {
+		console.error(`[excal] Chrome을 찾지 못했습니다. 직접 여세요: ${info.url}`);
+		return false;
+	}
+	spawn(cmd[0], cmd[1], { detached: true, stdio: "ignore" }).unref();
+	return waitForClient(srv, info.id, 20_000);
+}
+
+async function waitForClient(srv, id, timeoutMs) {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		const st = await (await call(srv.port, srv.token, "/api/status")).json();
+		if (st.files.find((f) => f.id === id)?.clients > 0) return true;
+		await new Promise((r) => setTimeout(r, 250));
+	}
+	return false;
+}
+
+function resolveFile(p, { create = false } = {}) {
+	if (!p) die(USAGE);
+	const abs = path.resolve(p);
+	if (!fs.existsSync(abs)) {
+		if (!create) die(`[excal] 파일이 없습니다: ${abs}`);
+		fs.mkdirSync(path.dirname(abs), { recursive: true });
+		fs.writeFileSync(abs, emptyScene());
+	}
+	return realPathOf(abs);
+}
+
+// ---------- scene analysis (inspect / lint) ----------
+
+function loadScene(file) {
+	let data;
+	try {
+		data = JSON.parse(fs.readFileSync(file, "utf8"));
+	} catch (err) {
+		return { error: `JSON 파싱 실패: ${err.message}` };
+	}
+	const elements = (Array.isArray(data.elements) ? data.elements : []).filter((e) => !e.isDeleted);
+	return { data, elements };
+}
+
+const isSkel = (e) => typeof e.version !== "number";
+const SHAPES = new Set(["rectangle", "ellipse", "diamond"]);
+const LINEAR = new Set(["arrow", "line"]);
+const round = (n) => (typeof n === "number" ? Math.round(n) : "?");
+
+function textWidthEstimate(text, fontSize = 20) {
+	let max = 0;
+	for (const line of String(text).split("\n")) {
+		let w = 0;
+		for (const ch of line)
+			w += /[\u1100-\u11ff\u3000-\u9fff\uac00-\ud7af\uff00-\uffef]/.test(ch) ? fontSize : fontSize * 0.55;
+		max = Math.max(max, w);
+	}
+	return max;
+}
+
+function labelOf(el, byId) {
+	if (el.label?.text) return el.label.text;
+	if (el.type === "text") return el.text;
+	const bound = (el.boundElements || []).find((b) => b.type === "text");
+	return bound ? byId.get(bound.id)?.text : undefined;
+}
+
+function arrowEnds(el) {
+	const s = el.start?.id ?? el.startBinding?.elementId;
+	const e = el.end?.id ?? el.endBinding?.elementId;
+	return [s, e];
+}
+
+function inspect(file) {
+	const { error, elements } = loadScene(file);
+	if (error) die(error);
+	const byId = new Map(elements.map((e) => [e.id, e]));
+	const visible = elements.filter((e) => !(e.type === "text" && e.containerId));
+	const count = (pred) => visible.filter(pred).length;
+	const boxes = visible.filter((e) => typeof e.x === "number" && typeof e.width === "number");
+	const minX = Math.min(...boxes.map((e) => e.x));
+	const minY = Math.min(...boxes.map((e) => e.y));
+	const maxX = Math.max(...boxes.map((e) => e.x + Math.abs(e.width)));
+	const maxY = Math.max(...boxes.map((e) => e.y + Math.abs(e.height ?? 0)));
+	console.log(
+		`${path.basename(file)}  요소 ${visible.length}개 (도형 ${count((e) => SHAPES.has(e.type))}, 화살표/선 ${count((e) => LINEAR.has(e.type))}, 텍스트 ${count((e) => e.type === "text")})` +
+			(boxes.length ? `  범위 x ${round(minX)}~${round(maxX)}, y ${round(minY)}~${round(maxY)}` : "") +
+			(elements.some(isSkel) ? "  [스켈레톤 포함: 창에서 열면 정규화됨]" : ""),
+	);
+	for (const el of visible) {
+		const label = labelOf(el, byId);
+		const lbl = label ? `  "${label.replace(/\n/g, "\\n")}"` : "";
+		const style = [
+			el.backgroundColor && el.backgroundColor !== "transparent" ? `bg=${el.backgroundColor}` : "",
+			el.strokeColor && el.strokeColor !== "#1e1e1e" ? `stroke=${el.strokeColor}` : "",
+		]
+			.filter(Boolean)
+			.join(" ");
+		if (LINEAR.has(el.type)) {
+			const [s, e] = arrowEnds(el);
+			console.log(
+				`[${el.type}] ${el.id}  ${s ?? "·"} → ${e ?? "·"}${lbl}  @(${round(el.x)},${round(el.y)})${style ? "  " + style : ""}`,
+			);
+		} else {
+			console.log(
+				`[${el.type}] ${el.id}  @(${round(el.x)},${round(el.y)} ${round(el.width)}×${round(el.height)})${lbl}${style ? "  " + style : ""}${el.frameId ? `  frame=${el.frameId}` : ""}`,
+			);
+		}
+	}
+}
+
+function lint(file) {
+	const { error, data, elements } = loadScene(file);
+	const errors = [];
+	const warns = [];
+	if (error) errors.push(error);
+	else {
+		if (data.type !== "excalidraw") errors.push(`최상위 type이 "excalidraw"가 아닙니다: ${data.type}`);
+		if (!Array.isArray(data.elements)) errors.push("최상위 elements 배열이 없습니다");
+		const all = Array.isArray(data.elements) ? data.elements : [];
+		const ids = new Map();
+		for (const e of all) {
+			if (!e.type) errors.push(`type 없는 요소: ${JSON.stringify(e).slice(0, 80)}`);
+			if (!e.id) {
+				if (isSkel(e) && !LINEAR.has(e.type)) warns.push(`id 없는 ${e.type} 요소 (나중에 수정·연결하려면 id 권장)`);
+				continue;
+			}
+			if (ids.has(e.id)) errors.push(`중복 id: ${e.id}`);
+			ids.set(e.id, e);
+		}
+		const ref = (owner, id, what) => {
+			if (id && !ids.has(id)) errors.push(`${owner.id ?? owner.type}의 ${what}가 없는 요소를 가리킴: ${id}`);
+		};
+		for (const e of elements) {
+			ref(e, e.containerId, "containerId");
+			ref(e, e.frameId, "frameId");
+			for (const b of e.boundElements || []) ref(e, b.id, "boundElements");
+			ref(e, e.startBinding?.elementId, "startBinding");
+			ref(e, e.endBinding?.elementId, "endBinding");
+			ref(e, e.start?.id, "start.id");
+			ref(e, e.end?.id, "end.id");
+			if (isSkel(e) && LINEAR.has(e.type)) {
+				const [s, t] = arrowEnds(e);
+				if (typeof e.x !== "number" && !(s && t))
+					errors.push(`${e.id ?? "arrow"}: x/y도 없고 start.id·end.id도 없습니다`);
+				if (typeof e.x !== "number" && s && t) {
+					for (const id of [s, t]) {
+						const target = ids.get(id);
+						if (target && (typeof target.width !== "number" || typeof target.height !== "number"))
+							errors.push(`${e.id ?? "arrow"}: 자동 연결 대상 ${id}에 width/height가 없습니다`);
+					}
+				}
+			}
+			if (isSkel(e) && SHAPES.has(e.type) && e.label?.text && typeof e.width === "number") {
+				const need = textWidthEstimate(e.label.text, e.label.fontSize ?? 20) + 24;
+				if (need > e.width)
+					warns.push(
+						`${e.id}: 라벨 "${e.label.text.split("\n")[0]}"이 너비 ${e.width}보다 길어 보임 (약 ${Math.round(need)}px 필요)`,
+					);
+			}
+		}
+		// partial overlaps between top-level boxes (containment is treated as intentional grouping)
+		const boxes = elements
+			.filter((e) => (SHAPES.has(e.type) || (e.type === "text" && !e.containerId)) && typeof e.x === "number")
+			.map((e) => {
+				const w =
+					typeof e.width === "number"
+						? e.width
+						: e.type === "text"
+							? textWidthEstimate(e.text, e.fontSize ?? 20)
+							: undefined;
+				const h =
+					typeof e.height === "number"
+						? e.height
+						: e.type === "text"
+							? (e.fontSize ?? 20) * 1.25 * String(e.text).split("\n").length
+							: undefined;
+				return w === undefined || h === undefined
+					? null
+					: { id: e.id ?? e.type, x1: e.x, y1: e.y, x2: e.x + w, y2: e.y + h };
+			})
+			.filter(Boolean);
+		const contains = (a, b) => a.x1 <= b.x1 && a.y1 <= b.y1 && a.x2 >= b.x2 && a.y2 >= b.y2;
+		for (let i = 0; i < boxes.length; i++)
+			for (let j = i + 1; j < boxes.length; j++) {
+				const a = boxes[i];
+				const b = boxes[j];
+				const ix = Math.min(a.x2, b.x2) - Math.max(a.x1, b.x1);
+				const iy = Math.min(a.y2, b.y2) - Math.max(a.y1, b.y1);
+				if (ix > 2 && iy > 2 && !contains(a, b) && !contains(b, a))
+					warns.push(`겹침: ${a.id} ↔ ${b.id} (${Math.round(ix)}×${Math.round(iy)})`);
+			}
+		for (const e of elements) {
+			if (e.type !== "arrow") continue;
+			const [s, t] = arrowEnds(e);
+			if (!s || !t) warns.push(`${e.id ?? "arrow"}: 한쪽 이상이 도형에 연결되지 않은 화살표`);
+		}
+	}
+	for (const m of errors) console.log(`ERROR ${m}`);
+	for (const m of warns) console.log(`WARN  ${m}`);
+	console.log(errors.length || warns.length ? `오류 ${errors.length}, 경고 ${warns.length}` : "OK");
+	process.exit(errors.length ? 1 : 0);
+}
+
+// ---------- commands ----------
+
+const [cmd, ...rest] = process.argv.slice(2);
+const flag = (name) => {
+	const i = rest.indexOf(name);
+	if (i === -1) return undefined;
+	const v = rest[i + 1];
+	rest.splice(i, 2);
+	return v;
+};
+const bool = (name) => {
+	const i = rest.indexOf(name);
+	if (i === -1) return false;
+	rest.splice(i, 1);
+	return true;
+};
+
+switch (cmd) {
+	case "open": {
+		const mermaid = flag("--from-mermaid");
+		const noWindow = bool("--no-window");
+		const file = resolveFile(rest[0], { create: true });
+		if (mermaid) {
+			const src = fs.readFileSync(path.resolve(mermaid), "utf8");
+			const data = JSON.parse(fs.readFileSync(file, "utf8"));
+			data.pendingMermaid = src;
+			writeFileAtomic(file, JSON.stringify(data, null, 2) + "\n");
+		}
+		const srv = await ensureServer();
+		const info = await register(srv, file);
+		let windowState = "already-open";
+		if (info.clients === 0) {
+			windowState = noWindow ? "not-opened" : (await openWindow(srv, info)) ? "opened" : "not-connected";
+		}
+		console.log(JSON.stringify({ file, url: info.url, window: windowState }, null, 2));
+		if (mermaid && windowState !== "not-opened")
+			console.error("[excal] mermaid 변환은 창에서 수행됩니다. 변환 후 파일이 정식 포맷으로 다시 저장됩니다.");
+		break;
+	}
+	case "inspect":
+		inspect(resolveFile(rest[0]));
+		break;
+	case "lint":
+		lint(resolveFile(rest[0]));
+		break;
+	case "snapshot": {
+		const out = flag("-o");
+		const file = resolveFile(rest[0]);
+		const srv = await ensureServer();
+		const info = await register(srv, file);
+		if (info.clients === 0 && !(await openWindow(srv, info)))
+			die("[excal] 창에 연결하지 못해 스냅샷을 찍을 수 없습니다");
+		const r = await call(srv.port, srv.token, `/api/files/${info.id}/snapshot`, { method: "POST" });
+		if (!r.ok) die(`[excal] 스냅샷 실패: ${await r.text()}`);
+		const target = out
+			? path.resolve(out)
+			: path.join(SNAPSHOT_DIR, `${path.basename(file, path.extname(file))}-${info.id}.png`);
+		fs.mkdirSync(path.dirname(target), { recursive: true });
+		fs.writeFileSync(target, Buffer.from(await r.arrayBuffer()));
+		console.log(target);
+		break;
+	}
+	case "history": {
+		const file = resolveFile(rest[0]);
+		const dir = path.join(HISTORY_DIR, fileIdFor(file));
+		const items = fs.existsSync(dir)
+			? fs
+					.readdirSync(dir)
+					.filter((f) => f.endsWith(".excalidraw"))
+					.sort()
+					.reverse()
+			: [];
+		if (!items.length) console.log("히스토리 없음");
+		for (const f of items)
+			console.log(`${new Date(Number(path.basename(f, ".excalidraw"))).toLocaleString("ko-KR")}  ${path.join(dir, f)}`);
+		break;
+	}
+	case "status": {
+		const token = readToken();
+		const state = readJSON(STATE_FILE, null);
+		if (!(await healthy(state, token))) {
+			console.log("서버 꺼짐");
+			break;
+		}
+		console.log(JSON.stringify(await (await call(state.port, token, "/api/status")).json(), null, 2));
+		break;
+	}
+	case "stop": {
+		const token = readToken();
+		const state = readJSON(STATE_FILE, null);
+		if (await healthy(state, token)) await call(state.port, token, "/api/shutdown", { method: "POST" });
+		console.log("stopped");
+		break;
+	}
+	case "build":
+		ensureBuilt(true);
+		console.log("built");
+		break;
+	default:
+		die(USAGE);
+}

package/skills/excalidraw/scripts/lib.mjs

@@ -0,0 +1,81 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const SKILL_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+export const APP_DIR = path.join(SKILL_DIR, "app");
+export const DIST_DIR = path.join(APP_DIR, "dist");
+export const STATE_DIR = process.env.EXCAL_STATE_DIR || path.join(os.homedir(), ".cache", "pi-excalidraw");
+export const STATE_FILE = path.join(STATE_DIR, "server.json");
+export const TOKEN_FILE = path.join(STATE_DIR, "token");
+export const REGISTRY_FILE = path.join(STATE_DIR, "files.json");
+export const HISTORY_DIR = path.join(STATE_DIR, "history");
+export const SNAPSHOT_DIR = path.join(STATE_DIR, "snapshots");
+export const LOG_FILE = path.join(STATE_DIR, "server.log");
+export const CHROME_PROFILE_DIR = path.join(STATE_DIR, "chrome-profile");
+
+export function ensureStateDir() {
+	fs.mkdirSync(STATE_DIR, { recursive: true, mode: 0o700 });
+}
+
+export function readToken() {
+	ensureStateDir();
+	try {
+		const token = fs.readFileSync(TOKEN_FILE, "utf8").trim();
+		if (token) return token;
+	} catch {}
+	const token = crypto.randomBytes(24).toString("hex");
+	fs.writeFileSync(TOKEN_FILE, token, { mode: 0o600 });
+	return token;
+}
+
+export function readJSON(file, fallback) {
+	try {
+		return JSON.parse(fs.readFileSync(file, "utf8"));
+	} catch {
+		return fallback;
+	}
+}
+
+export function sha(text) {
+	return crypto.createHash("sha256").update(text).digest("hex");
+}
+
+/** Stable id for a diagram file, derived from its real absolute path. */
+export function fileIdFor(absPath) {
+	return crypto.createHash("sha1").update(absPath).digest("hex").slice(0, 12);
+}
+
+export function realPathOf(p) {
+	const abs = path.resolve(p);
+	try {
+		return fs.realpathSync(abs);
+	} catch {
+		return abs;
+	}
+}
+
+export function emptyScene() {
+	return (
+		JSON.stringify(
+			{
+				type: "excalidraw",
+				version: 2,
+				source: "pi-excalidraw",
+				elements: [],
+				appState: { viewBackgroundColor: "#ffffff", gridSize: 20 },
+				files: {},
+			},
+			null,
+			2,
+		) + "\n"
+	);
+}
+
+export function writeFileAtomic(file, content) {
+	const tmp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);
+	fs.writeFileSync(tmp, content);
+	fs.renameSync(tmp, file);
+}