pubuilder 0.6.0 → 0.8.0

package/dist/publish-jobs.d.ts

@@ -0,0 +1,28 @@
+import type { AgentEvent } from './api';
+import type { BlockSelection } from './types';
+export type PublishStatus = 'idle' | 'running' | 'done' | 'error';
+/**
+ * 한 블록의 퍼블리싱 job 상태. selection에 종속된 로컬 state가 아니라
+ * store에 블록별로 보관되어, 다른 블록을 선택해도 실행 중인 job이 끊기지 않는다.
+ */
+export interface PublishJobState {
+    jobId: string | null;
+    status: PublishStatus;
+    events: AgentEvent[];
+    errorMessage: string | null;
+    errorCode: string | null;
+    serverDown: boolean;
+    /** isAlive/startPublish 왕복 중 로딩 플래그 */
+    checking: boolean;
+    cancelling: boolean;
+    /** 입력값도 블록별로 유지 — 전환 후 돌아와도 그대로 */
+    figmaUrl: string;
+    reply: string;
+}
+export declare const IDLE_PUBLISH_JOB: PublishJobState;
+/**
+ * 블록을 페이지 간에도 고유하게 식별하는 키.
+ * 서로 다른 페이지가 같은 selector를 가질 수 있으므로 pagePath까지 합친다.
+ * '\n'은 selector/pagePath에 나타나지 않아 구분자로 안전하다.
+ */
+export declare function blockKey(sel: BlockSelection): string;

package/dist/server/agent.d.ts

@@ -1,6 +1,31 @@
+/** 충돌 파일 정보: 사용자가 파일 단위로 revert/keep/edit 결정한다 */
+export interface SuspendConflict {
+    file: string;
+    baseline: string;
+    current: string;
+}
+export interface SuspendResult {
+    autoReverted: string[];
+    conflicts: SuspendConflict[];
+}
+export type SuspendResolution = {
+    file: string;
+    action: 'revert' | 'keep' | 'edit';
+    content?: string;
+};
+/** 테스트에서 fs/git 없이 로직만 검증할 수 있도록 주입 가능한 파일 연산 */
+interface SnapshotOps {
+    captureBaseline?: (cwd: string) => string | null;
+    readBaseline?: (cwd: string, ref: string, file: string) => string | null;
+    restoreFile?: (cwd: string, ref: string, file: string) => void;
+    readCurrent?: (cwd: string, file: string) => string;
+    writeFile?: (cwd: string, file: string, content: string) => void;
+}
 export interface AgentEvent {
     type: 'log' | 'tool' | 'error' | 'done';
     text: string;
+    /** tool 이벤트에서 Edit/Write 대상 파일 경로 (touchedFiles 추적용) */
+    file?: string;
 }
 export interface AgentRunOptions {
     prompt: string;
@@ -18,13 +43,20 @@ export interface AgentAdapter {
  */
 export declare function parseAgentLine(line: string): AgentEvent[];
 export declare const claudeAdapter: AgentAdapter;
-/** 동시 실행 1개 제한 (스펙). 이벤트는 저장 후 브로드캐스트 — 늦은 SSE 구독자는 replay */
+/** 이벤트는 저장 후 브로드캐스트 — 늦은 SSE 구독자는 replay */
 export declare class PublishJobManager {
     private readonly adapter;
     private jobs;
-    private active;
     private seq;
-    constructor(adapter: AgentAdapter);
+    private readonly capture;
+    private readonly readBaseline;
+    private readonly restoreFile;
+    private readonly readCurrent;
+    private readonly writeFile;
+    /** suspend 시 파일별 baseline ref를 보관 → resolve의 revert에서 사용 */
+    private pendingBaseline;
+    constructor(adapter: AgentAdapter, opts?: SnapshotOps);
+    private activeCount;
     start(opts: {
         prompt: string;
         cwd: string;
@@ -33,7 +65,24 @@ export declare class PublishJobManager {
     private evictFinishedJobs;
     /** SSE 핸들러가 헤더 전송 전에 job 존재를 확인할 때 사용 (subscribe는 replay 부작용이 있어 분리) */
     has(id: string): boolean;
+    /** job이 편집한 파일 목록 (상대경로, 정렬) */
+    touchedFiles(id: string): string[];
+    /** job 시작 시점 baseline ref */
+    baselineRef(id: string): string | null;
+    /**
+     * 진행 중(running)인 job을 전부 abort하고, 그들이 편집한 파일을 분류한다.
+     * - 자동 롤백: running job만 건드린 파일 → baseline으로 즉시 복원
+     * - 충돌: 완료(finished)된 job도 건드린 파일 → 사용자 해결 대상으로 반환
+     * 파일별 baseline은 그 파일을 건드린 running job 중 가장 이른(seq 최소) job의 것.
+     */
+    suspendRunning(cwd: string): SuspendResult;
+    /**
+     * 충돌 파일에 대한 사용자 결정을 적용한다.
+     * revert → baseline 복원, edit → content로 덮어쓰기, keep → 그대로 둔다.
+     */
+    applyResolutions(cwd: string, resolutions: SuspendResolution[]): void;
     subscribe(id: string, listener: (e: AgentEvent) => void): () => void;
     cancel(id: string): void;
     waitFor(id: string): Promise<void>;
 }
+export {};

package/dist/server/design-ir.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Figma REST /nodes document 트리 → 컴팩트 Design IR.
+ *
+ * 규칙 기반 순수 변환(LLM 토큰 0). raw Figma 노드는 노드마다 수십 개 필드
+ * (blendMode/constraints/absoluteRenderBounds/exportSettings 등)를 담아 프롬프트에
+ * 그대로 실으면 토큰을 크게 낭비한다. 퍼블리싱에 실제로 필요한 스타일 필드만 뽑고
+ * 숨김 노드를 제거해 60~80% 축소한다. LLM은 이 IR로 판단(토큰 매핑·코드 작성)만 한다.
+ */
+export interface DesignIRNode {
+    name: string;
+    type: string;
+    size?: {
+        w: number;
+        h: number;
+    };
+    layout?: {
+        mode: 'row' | 'col';
+        gap?: number;
+        padding?: [number, number, number, number];
+        align?: string;
+        justify?: string;
+    };
+    radius?: number | number[];
+    fills?: string[];
+    strokes?: string[];
+    effects?: string[];
+    text?: {
+        chars: string;
+        font?: string;
+        size?: number;
+        weight?: number;
+        lineHeight?: number;
+        letterSpacing?: number;
+    };
+    component?: Record<string, string>;
+    children?: DesignIRNode[];
+}
+export interface DesignIR {
+    root: DesignIRNode;
+    /** 색상 사용 빈도 (hex→token 매핑 결정용, 빈도 내림차순) */
+    colors: Array<{
+        rgba: string;
+        count: number;
+    }>;
+}
+export declare function extractDesignIR(document: unknown): DesignIR;

package/dist/server/http.d.ts

@@ -7,6 +7,8 @@ export interface PubuilderServerOptions {
     port?: number;
     adapter?: AgentAdapter;
     figmaFetch?: typeof fetch;
+    /** 패키지 번들 기본 스킬 디렉토리 (CLI가 dist 기준으로 해석해 전달) */
+    builtinDir?: string;
 }
 export interface PubuilderServerHandle {
     port: number;

package/dist/server/skills.d.ts

@@ -1,4 +1,4 @@
-export type SkillSource = 'project' | 'global' | 'uploaded';
+export type SkillSource = 'builtin' | 'project' | 'global' | 'uploaded';
 export interface SkillInfo {
     id: string;
     name: string;
@@ -9,16 +9,19 @@ export interface SkillInfo {
 export declare class SkillRegistry {
     private readonly projectRoot;
     private readonly homeDir;
+    /** 패키지에 번들되어 배포되는 기본 스킬 디렉토리 (없으면 스캔 안 함) */
+    private readonly builtinDir?;
     constructor(opts: {
         projectRoot: string;
         homeDir: string;
+        builtinDir?: string;
     });
     private settingsPath;
     private loadSettings;
     private saveSettings;
     private scanDir;
     private scanAll;
-    /** 기본값: project·uploaded on, global off (스펙 결정) */
+    /** 기본값: builtin·project·uploaded on, global off (스펙 결정) */
     list(): SkillInfo[];
     setEnabled(id: string, enabled: boolean): void;
     upload(filename: string, content: string): SkillInfo;

package/dist/server/snapshot.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 현재 작업 트리 상태를 커밋 오브젝트로 스냅샷하고 그 SHA를 반환한다.
+ * 워킹트리·stash 목록을 건드리지 않는다(`git stash create`).
+ * 트리가 clean이면 'HEAD'(동일 상태), 비-git이거나 실패하면 null(롤백 기능 degrade).
+ */
+export declare function captureBaseline(cwd: string): string | null;
+/** ref 시점의 file 내용. ref에 해당 파일이 없으면(스냅샷 이후 생성된 신규 파일) null. */
+export declare function readBaseline(cwd: string, ref: string, file: string): string | null;
+/** file을 baseline으로 복원한다. baseline에 없던(신규 생성) 파일이면 삭제한다. */
+export declare function restoreFile(cwd: string, ref: string, file: string): void;

package/dist/store.d.ts

@@ -1,3 +1,5 @@
+import type { AgentEvent, SuspendConflict, SuspendResolution } from './api';
+import { type PublishJobState } from './publish-jobs';
 import type { BlockSelection, Granularity } from './types';
 interface PubuilderStore {
     isMapOpen: boolean;
@@ -9,6 +11,11 @@ interface PubuilderStore {
     /** 선택된 블록의 outerHTML 스냅샷 (Phase 3 퍼블리싱 프롬프트용, 20K 상한) */
     selectedOuterHTML: string | null;
     skillDrawerOpen: boolean;
+    /**
+     * 블록별 퍼블리싱 job 상태 (key: blockKey). selection에서 분리되어 있어
+     * 다른 블록을 선택하거나 맵을 닫아도 실행 중인 job이 끊기지 않는다.
+     */
+    publishJobs: Record<string, PublishJobState>;
     openMap: () => void;
     closeMap: () => void;
     openViewer: (path: string) => void;
@@ -17,6 +24,17 @@ interface PubuilderStore {
     setInspectEnabled: (v: boolean) => void;
     setSelectionWithHTML: (s: BlockSelection | null, html: string | null) => void;
     toggleSkillDrawer: () => void;
+    /** 블록 job의 일부 필드를 갱신 (없으면 IDLE에서 시작) */
+    patchPublishJob: (key: string, partial: Partial<PublishJobState>) => void;
+    /** 블록 job의 이벤트 로그에 한 건 추가 */
+    appendPublishEvent: (key: string, event: AgentEvent) => void;
+    /** 일시 종료 후 사용자가 해결해야 하는 충돌 파일들 (없으면 패널 미표시) */
+    suspendConflicts: SuspendConflict[];
+    /** 충돌 파일별 사용자 결정 (file → resolution) */
+    suspendResolutions: Record<string, SuspendResolution>;
+    setSuspendConflicts: (conflicts: SuspendConflict[]) => void;
+    setConflictResolution: (file: string, action: SuspendResolution['action'], content?: string) => void;
+    clearSuspend: () => void;
 }
 export declare const usePubuilderStore: import("zustand").UseBoundStore<import("zustand").StoreApi<PubuilderStore>>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pubuilder",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "In-app IA minimap & block inspector for React — live iframe thumbnails of every page, plus a Next.js route scanner that drafts your ia.config (dev-only)",
   "license": "MIT",
   "author": "taehoon",
@@ -39,6 +39,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "CHANGELOG.md"
   ],
   "sideEffects": false,

package/skills/publish/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: publish
+description: Use when implementing a UI block from a Figma node — turning a Figma design into code inside an existing project, using that project's own style tokens and components.
+---
+
+# Figma 퍼블리싱 방법
+
+Figma 노드를 이 프로젝트의 코드로 구현할 때 따르는 방법이다. **프레임워크 무관** — 프로젝트가 이미 쓰는 스타일 시스템(Chakra / Tailwind / MUI / styled-components / CSS Modules 등)과 기존 컴포넌트를 그대로 활용한다.
+
+pubuilder가 이미 Figma를 **컴팩트 Design IR**(규칙 기반으로 스타일 필드만 추출, 숨김 노드 제외)과 렌더 이미지로 프롬프트에 전달한다. 이 스킬은 그것을 **어떤 태도와 순서로 코드에 옮길지**를 정의한다.
+
+## 핵심 원칙 (모든 단계에 우선)
+
+- **애매하거나 모르면 추측하지 말고 사용자에게 질문한다.** 추측으로 진행 금지.
+- **문제가 생기면 우회하지 말고 멈추고 보고한다.** 노드 누락 / 스펙 불일치 / 토큰 매칭 실패 / 컴포넌트 매핑 부재 — "비슷해 보이는 값"으로 대체하거나 "아마 이 뜻일 것"으로 넘어가지 않는다.
+- **기존 코드에서 UI 요소(컴포넌트·필드·컬럼 등)를 제거하기 전 반드시 확인한다.** 전달된 노드 JSON은 일부 노드만 담을 수 있으므로, 시안에 안 보인다고 없는 것으로 판단하지 않는다. 제거가 필요해 보이면 → 멈추고 이유와 함께 보고 → 확인 후 진행.
+- **letter를 어기는 것은 spirit을 어기는 것이다.** 위 규칙은 다른 어떤 편의보다 우선한다.
+
+## 1. 시안을 눈으로 먼저 본다
+
+- 전달된 Figma 렌더 이미지를 **Read 도구로 직접 연다.**
+- 노드 JSON의 수치를 1차 근거로 쓰되, **JSON에만 있고 이미지엔 안 보이는 요소**(hidden / opacity 0 / placeholder)는 구현하지 않는다.
+
+## 2. 스펙을 raw 값으로 읽는다 (토큰명 추론 금지)
+
+Design IR에서 아래를 **raw 값 그대로** 파악한다:
+
+- size / layout(mode·align·sizing·gap·padding) / cornerRadius
+- fills·strokes (rgba) / effects(shadow)
+- text: 내용 + typography 5필드(font family / size / weight / lineHeight / letterSpacing)
+- 컴포넌트 variant / INSTANCE_SWAP / BOOLEAN / TEXT 값
+- 아이콘 내부 vector·알림 dot 같은 **decorative 요소도 누락 금지**
+
+반복 요소(칩·카드·행)는 공통 스펙 + 인스턴스별 차이(width/text)를 **한 개도 빠짐없이** 확인한다.
+
+## 3. 프로젝트 규약으로 변환한다
+
+- raw 값을 **프로젝트가 이미 쓰는 토큰/유틸**로 매핑한다. 하드코딩보다 기존 토큰 우선.
+- 토큰이 불확실하면 **토큰 정의 파일을 열어 대조**한다 — 이름을 추측하지 않는다.
+- fill opacity < 1이면 시맨틱 토큰 대신 `rgba()`를 직접 쓴다.
+- 컴포넌트는 **기존 컴포넌트를 재사용**한다. 같은 패턴이 이미 있으면 새로 만들지 않는다.
+- 대상 소스 파일은 전달된 outerHTML 스냅샷과 라우트를 단서로 찾는다.
+
+## 4. 구현
+
+- 스타일·마크업만 시안에 맞추고, **기존 동작·이벤트 핸들러·데이터 로직은 유지**한다.
+
+## 5. 완료 게이트 (선언 전 필수)
+
+아래를 모두 확인한 뒤에만 "완료"라 한다. 한 칸이라도 미충족이면 완료 대신 사용자에게 보고한다:
+
+- [ ] hidden/placeholder 노드를 잘못 구현하지 않았는가
+- [ ] variant / INSTANCE_SWAP / 텍스트 값이 시안과 일치하는가
+- [ ] 반복 요소의 개수·내용이 맞는가
+- [ ] **색상·간격·타이포를 시안 이미지와 나란히 비교했는가** (코드만 보고 "맞다" 가정 금지)
+- [ ] 프로젝트의 타입체크가 통과하는가
+
+## 하지 않는 것
+
+- Figma 스펙 추측 코딩 / sublayer 건너뛰기
+- 시안 이미지에 없는 요소 추가 (비활성·숨김·placeholder 포함)
+- 확인 없이 기존 UI 제거
+- 이름을 추측한 토큰 사용