@underdogai/mesh-app-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Underdog
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# @underdogai/mesh-app-sdk
+
+Matrix 채팅방에 붙는 앱을 **선언형으로** 만드는 SDK. 화면(카드·패널·컴포저·⌘K)과 동작(버튼·구독·호출)을 한 곳에서 정의하고, **봇 계정 토큰 하나로** 실행한다. 홈서버 관리자 권한이나 Application Service 등록 파일이 필요 없다.
+
+```bash
+npm i @underdogai/mesh-app-sdk zod
+```
+
+## 5줄 요약
+
+- 앱이 보내는 건 전부 **데이터**(Matrix 이벤트)다 — 클라이언트에서 남의 코드가 실행되지 않는다.
+- 화면은 방의 **상태 이벤트**로 저장된다 — 한 번 올리면 그 방의 모든 멤버에게 계속 보인다.
+- 버튼·폼 제출·앱 간 호출은 전부 하나의 와이어(`org.corp.ui.action`)로 흐른다.
+- 핸들러는 부작용을 직접 실행하지 않고 **효과(Effect)를 선언**한다 — 홈서버 없이 테스트할 수 있다.
+- 실행 방식(1회 발행 / 봇 / App Service)은 앱 코드를 바꾸지 않고 고른다.
+
+## 최소 예제
+
+```js
+import { z } from "zod";
+import { defineApp, defineAction, card, panel, serve } from "@underdogai/mesh-app-sdk";
+
+const open = defineAction({
+  id: "helpdesk.open",           // id 는 반드시 "<app>." 접두사 — 이게 라우팅 주소다
+  scope: "ticket:open",
+  values: z.object({}).passthrough(),
+});
+
+const app = defineApp({
+  id: "helpdesk", app: "helpdesk", entityTypes: ["ticket"],
+  actions: [open],
+  handlers: {
+    [open.id]: (c) => c.send(card.build("hello", [card.text("눌렀습니다")], { title: "Helpdesk" })),
+  },
+  sidebar: panel.sections([panel.fields("t", "Tickets", [{ label: "Open", value: "3" }])]),
+  composer: {
+    placeholder: "Message or /ticket…",
+    commands: [{ trigger: "/ticket", label: "Open ticket", action_id: open.id }],
+  },
+});
+
+await serve(app, { homeserver: "https://your-homeserver", accessToken: process.env.BOT_TOKEN });
+```
+
+봇을 방에 초대하고 **권한 등급 50(중재자)** 을 주면 화면이 뜬다. 권한을 나중에 줘도 봇을 다시 켤 필요가 없다.
+
+## 네 가지 통로
+
+| 통로 | 뜻 |
+|---|---|
+| `ctx.emit(type, content, { form })` | 사실을 발행 — `"event"`(조용) · `"message"`(카드) · `"state"`(방 상태) |
+| `on: { [type]: handler }` | 남이 낸 이벤트를 구독해 반응 |
+| `ctx.invoke(actionId, values)` | 다른 앱의 기능을 이름으로 호출 |
+| `handlers: { [actionId]: handler }` | 내 기능이 불리면 실행 (내 것이 아니면 조용히 무시) |
+
+## 실행 방식
+
+```js
+await publish(app, { homeserver, accessToken, roomId });  // 1회 발행, 프로세스 없음
+await serve(app, { homeserver, accessToken });            // 봇 상시 실행 (대부분 이걸로 충분)
+```
+
+되돌릴 수 없는 액션(`destructive: true`)은 기본적으로 **누른 사람의 권한 등급 50 이상**을 요구한다. 자체 정책은 `serve(app, { gate })` 로 대체할 수 있고, 초대 수락 범위는 `acceptInvite` 로 좁힐 수 있다.
+
+## 문서
+
+전체 가이드 — 설치부터 화면 지도, 권한 모델, 보안 수칙까지: **https://chatops.theunderdog.ai/sdk-guide**
+
+## 라이선스
+
+MIT

package/dist/action.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 액션 정의 — 카드 버튼(UI)과 서버 핸들러(동작)를 "하나의 id/scope/values"로 묶는 컨트랙트.
+ *
+ * 지금까지 흩어져 있던 것 — 카드 빌더의 `action_id` 문자열 ↔ 핸들러의 `if (action_id === ...)` ↔
+ * policy 의 `ACTION_SCOPE` 하드코딩 맵 — 을 defineAction 한 곳으로 모은다. 결과:
+ *  - 버튼의 action_id 가 정의에서 파생 → 카드와 핸들러가 컴파일타임에 연결(오타/리네임 안전).
+ *  - scope/destructive 는 데이터로 서버 게이트(evaluateAction)에 주입 → 보안은 서버가 소유, SDK 는 데이터만 공급.
+ */
+import { z } from "zod";
+import type { Block, ButtonStyle } from "@underdogai/mesh-event-schemas";
+/** UiCardContent 의 actions 블록 element 타입을 스키마에서 직접 파생(닫힌 집합과 100% 일치 보장). */
+type ActionsBlock = Extract<Block, {
+    type: "actions";
+}>;
+export type ButtonElement = ActionsBlock["elements"][number];
+export interface ActionButtonOpts {
+    style?: ButtonStyle;
+    /** true → 기본 확인 다이얼로그, 객체 → 커스텀 확인 문구. UI 게이트일 뿐(권한은 서버). */
+    confirm?: boolean | {
+        title: string;
+        text: string;
+    };
+    /** 버튼 고유 값(폼 입력 values 와 별개). */
+    value?: string;
+}
+export interface AppAction<V extends z.ZodTypeAny = z.ZodTypeAny> {
+    /** 안정적 action_id (org.corp.ui.action.action_id 로 회신된다). */
+    id: string;
+    /** 이 액션을 실행하려면 에이전트 capability 에 있어야 하는 scope(서버 게이트가 검사). */
+    scope: string;
+    /** 파괴적(되돌릴 수 없는) 여부 — 참이면 서버가 발신자 PL 게이트도 적용(HITL). */
+    destructive: boolean;
+    /** 폼 입력(values) 검증 스키마 — 핸들러에서 .parse(ctx.values) 로 타입 확보. */
+    values: V;
+    /**
+     * 이 액션의 핸들러가 `ctx.backend.call(tool)` 로 부를 수 있는 MCP 도구 화이트리스트(declaration = 데이터).
+     * 미선언(undefined/빈 배열)이면 이 액션 핸들러는 backend 도구를 *전혀* 못 부른다(fail-closed).
+     * confused-deputy 방어: 핸들러가 선언 밖 도구(예: delete_invoice)를 부르면 런타임이 거부한다(SDK 가 기계적 강제,
+     * 도구 구현·권한은 호스트가 소유 = GateFn 과 같은 의존성 역전). scope 가 "발신자 자격"이라면 tools 는 "앱 리소스 접근면".
+     */
+    tools?: string[];
+    /** 이 액션을 부르는 버튼 element(action_id 자동 연결). card.actions([...]) 에 넣는다. */
+    button(text: string, opts?: ActionButtonOpts): ButtonElement;
+}
+/** 액션을 한 번 정의 → 카드 버튼과 서버 핸들러가 같은 id/scope/values 를 공유한다. */
+export declare function defineAction<V extends z.ZodTypeAny = z.ZodTypeAny>(def: {
+    id: string;
+    scope: string;
+    destructive?: boolean;
+    values?: V;
+    /** 핸들러가 호출 가능한 MCP 도구 화이트리스트(미선언=backend 도구 호출 금지, fail-closed). */
+    tools?: string[];
+}): AppAction<V>;
+export {};
+//# sourceMappingURL=action.d.ts.map

package/dist/action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAEzE,6EAA6E;AAC7E,KAAK,YAAY,GAAG,OAAO,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,CAAC;AACxD,MAAM,MAAM,aAAa,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,OAAO,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACpD,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU;IAC9D,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,WAAW,EAAE,OAAO,CAAC;IACrB,8DAA8D;IAC9D,MAAM,EAAE,CAAC,CAAC;IACV;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,wEAAwE;IACxE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,aAAa,CAAC;CAC9D;AAED,6DAA6D;AAC7D,wBAAgB,YAAY,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,EAAE,GAAG,EAAE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,CAAC,CAAC;IACX,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,SAAS,CAAC,CAAC,CAAC,CAsBf"}

package/dist/action.js

@@ -0,0 +1,33 @@
+/**
+ * 액션 정의 — 카드 버튼(UI)과 서버 핸들러(동작)를 "하나의 id/scope/values"로 묶는 컨트랙트.
+ *
+ * 지금까지 흩어져 있던 것 — 카드 빌더의 `action_id` 문자열 ↔ 핸들러의 `if (action_id === ...)` ↔
+ * policy 의 `ACTION_SCOPE` 하드코딩 맵 — 을 defineAction 한 곳으로 모은다. 결과:
+ *  - 버튼의 action_id 가 정의에서 파생 → 카드와 핸들러가 컴파일타임에 연결(오타/리네임 안전).
+ *  - scope/destructive 는 데이터로 서버 게이트(evaluateAction)에 주입 → 보안은 서버가 소유, SDK 는 데이터만 공급.
+ */
+import { z } from "zod";
+/** 액션을 한 번 정의 → 카드 버튼과 서버 핸들러가 같은 id/scope/values 를 공유한다. */
+export function defineAction(def) {
+    const values = (def.values ?? z.object({}).passthrough());
+    return {
+        id: def.id,
+        scope: def.scope,
+        destructive: def.destructive ?? false,
+        values,
+        ...(def.tools ? { tools: def.tools } : {}),
+        button(text, opts) {
+            const confirm = opts?.confirm === true ? { title: text, text: "Are you sure?" } : opts?.confirm || undefined;
+            const el = {
+                type: "button",
+                action_id: def.id,
+                text,
+                ...(opts?.style ? { style: opts.style } : {}),
+                ...(confirm ? { confirm } : {}),
+                ...(opts?.value ? { value: opts.value } : {}),
+            };
+            return el;
+        },
+    };
+}
+//# sourceMappingURL=action.js.map

package/dist/action.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action.js","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAmCxB,6DAA6D;AAC7D,MAAM,UAAU,YAAY,CAAwC,GAOnE;IACC,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAiB,CAAC;IAC1E,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,WAAW,EAAE,GAAG,CAAC,WAAW,IAAI,KAAK;QACrC,MAAM;QACN,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1C,MAAM,CAAC,IAAI,EAAE,IAAI;YACf,MAAM,OAAO,GACX,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,IAAI,SAAS,CAAC;YAC/F,MAAM,EAAE,GAAG;gBACT,IAAI,EAAE,QAAiB;gBACvB,SAAS,EAAE,GAAG,CAAC,EAAE;gBACjB,IAAI;gBACJ,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC7C,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC/B,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC9C,CAAC;YACF,OAAO,EAAmB,CAAC;QAC7B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/app.d.ts

@@ -0,0 +1,126 @@
+/**
+ * defineApp — 한 "앱"(회사 ERP 등)을 한 폴더에서 선언한다.
+ *
+ * App 은 Plugin 의 상위집합이라, enabledPlugins(@chatops/app-plugins)에 한 줄 올리면 클라/AS/브리지가
+ * 같은 스키마를 등록한다(SEC-2 로드 경로 재사용 = "Matrix App Service 만 추가"의 봉합선).
+ *
+ * 한 앱이 묶는 삼각형:
+ *  - events:   커스텀 이벤트 → 카드(데이터) 결합("어떤 UI가 어떤 이벤트에"). messageForEvent 로 AS가 전송.
+ *  - actions/handlers: 카드 버튼 ↔ 서버 핸들러(동작). dispatchAction(runtime)이 게이트 후 실행.
+ *  - on:       구독 선언("남이 낸 이벤트가 오면 반응"). dispatchEvent(runtime)가 라우팅(이벤트 드리븐 통로).
+ *  - sidebar/header:   우측 셸 서피스(데이터). surfaceState 로 AS가 상태 이벤트(org.corp.app.surface)로 전송.
+ *  + theme: 회사별 토큰 오버라이드(데이터). 전부 "기존 어휘 조합 = 데이터" → 클라 무변경.
+ */
+import type { z } from "zod";
+import { buildUiMessageContent, type AgentDockSpec, type AppSurfaceContent, type CanvasSpec, type CommandPaletteSpec, type ComposerSpec, type HeaderSpec, type ModalSpec, type ObjectMapSpec, type PanelSpec, type Plugin, type Publisher, type UiCardContent } from "@underdogai/mesh-event-schemas";
+import type { AppAction } from "./action.js";
+import type { ActionHandler, EventHandler } from "./runtime.js";
+export interface AppEventDef<S extends z.ZodTypeAny = z.ZodTypeAny> {
+    /** 이 도메인 이벤트 content 스키마(레지스트리에 등록 → validateEvent/canPublish 가 인식). */
+    schema: S;
+    /** 이 이벤트가 들어오면 어떤 카드(기존 블록 조합)로 그릴지 — 이벤트 ↔ UI 결합. */
+    view: (content: z.infer<S>) => UiCardContent;
+    publishableBy?: Publisher[];
+}
+export interface AppDef {
+    /** 전역 고유 id(패키지 1개 = 1개). */
+    id: string;
+    /** room.binding/app.surface 의 app 키(작성자/도메인 식별자). */
+    app: string;
+    displayName?: string;
+    entityTypes: string[];
+    /**
+     * 코어 앱 여부 — true 면 이 앱의 액션은 *모든* 방에서 동작한다(room.binding 격리 면제). 에이전트 자신의
+     * 내장 능력(예: finance 의 invoice 승인)을 표현한다. false(기본)인 도메인 앱(acme/northwind 등)은
+     * 자기 방에 바인딩됐을 때만 동작한다(per-room 격리). 보안 게이트(scope/PL)는 코어 앱에도 그대로 적용된다.
+     * ⚠️ 신뢰 경계: core 는 격리를 면제하므로 *호스트가 신뢰하는* 1st-party 앱만 가져야 한다. 서드파티 로딩(G5)에선
+     * 앱이 self-declare 한 core 를 그대로 믿으면 안 되고, 호스트가 manifest 검수 단계에서 core 부여를 통제해야 한다.
+     */
+    core?: boolean;
+    /** 커스텀 이벤트 → 카드 결합(이벤트 타입 → { schema, view }). */
+    events?: Record<string, AppEventDef>;
+    /**
+     * 구독 선언 — "이 이벤트 타입이 오면 반응한다"(이벤트 타입 → 핸들러). events.view 가 *렌더링*이라면
+     * on 은 *반응*이다. 남(다른 앱·브리지)의 타입을 들어도 되고, 여러 앱이 같은 타입을 함께 들어도 된다
+     * (이벤트 드리븐 — 주소 없음). 라우팅은 호스트가 dispatchEvent 로 한다. org.corp.ui.action 구독은
+     * 정의 시점에 거부한다 — 액션의 유일한 진입로는 게이트를 지나는 dispatchAction 이다(권한 우회 차단).
+     */
+    on?: Record<string, EventHandler>;
+    /** 액션 컨트랙트(버튼 + scope). */
+    actions?: AppAction[];
+    /** action_id → 서버 핸들러(동작). actions 와 짝(서비스 면). */
+    handlers?: Record<string, ActionHandler>;
+    /** 우측 셸 패널(데이터). surfaceState 로 상태 이벤트화. */
+    sidebar?: PanelSpec;
+    /** 메인 영역 서피스(데이터, 선택) — 룸 본문에 탭으로 그릴 중앙 콘텐츠. sidebar 와 함께 발행된다. */
+    main?: PanelSpec;
+    /** 룸 헤더(데이터, 선택). */
+    header?: HeaderSpec;
+    /** 이벤트 캔버스(보드). */
+    canvas?: CanvasSpec;
+    /** 우측 에이전트 도크. */
+    dock?: AgentDockSpec;
+    /** 컴포저(슬래시 명령·퀵액션·@엔티티 자동완성). */
+    composer?: ComposerSpec;
+    /** ⌘K 커맨드 팔레트 엔트리. */
+    commandPalette?: CommandPaletteSpec;
+    /** 객체 맵(엔티티 관계 그래프). */
+    objectMap?: ObjectMapSpec;
+    /** 선언형 모달/시트(확인 다이얼로그) — 같은 id 의 셸 액션이 열고, 확인 시 confirm.action_id 발행. */
+    modals?: ModalSpec[];
+    /** 회사별 브랜드 토큰 오버라이드(데이터). */
+    theme?: Record<string, string>;
+    /**
+     * 핸들러 지연 등록(런타임 경계 물리화) — true 면 defineApp 은 핸들러 없이 App 을 만들고, 파괴적-액션-핸들러
+     * 링크검사를 미룬다. 호스트(AS)가 부팅 시 attachHandlers(app, handlers) 로 *service 서브패스*의 핸들러를 붙이며
+     * 그때 전체 링크검사를 한다. 효과: 핸들러(동작) 코드가 클라 번들에 실리지 않는다(클라는 contract/surface 만 로드).
+     */
+    deferHandlers?: boolean;
+}
+export interface App extends Plugin {
+    actions: Map<string, AppAction>;
+    handlers: Map<string, ActionHandler>;
+    events: Record<string, AppEventDef>;
+    /** 구독 선언(이벤트 타입 → 핸들러) — AppDef.on. 호스트가 dispatchEvent 로 라우팅한다. */
+    on: Map<string, EventHandler>;
+    /** 코어 앱(모든 방에서 동작, room.binding 격리 면제) 여부 — AppDef.core. 호스트 라우터가 격리 검사 때 본다. */
+    core: boolean;
+    /** 도메인 이벤트 content → 보낼 메시지(데이터, org.corp.ui 카드 포함). 미등록/검증실패 시 null. */
+    messageForEvent(type: string, content: unknown): ReturnType<typeof buildUiMessageContent> | null;
+    /** 우측 셸 서피스를 상태 이벤트 content(데이터)로. sidebar 없으면 null. */
+    surfaceState(): AppSurfaceContent | null;
+}
+export declare function defineApp(def: AppDef): App;
+/**
+ * service 핸들러를 (deferHandlers 로 만든) App 에 부착한다 — 런타임 경계 물리화의 호스트 측 절반.
+ * 클라는 contract/surface(핸들러 0)만 로드해 App 을 만들고, AS 만 `@chatops/app-<x>/service` 의 핸들러를 import 해
+ * 부팅 시 이걸 호출한다 → 핸들러(동작) 코드가 클라 번들에 실리지 않는다. 붙일 때 전체 링크검사를 수행한다(fail-fast).
+ * 같은 App 싱글톤의 handlers Map 을 채우므로 actionIndex/appsByName 가 참조하던 App 에 즉시 반영된다.
+ */
+export declare function attachHandlers(app: App, handlers: Record<string, ActionHandler>): App;
+/**
+ * 레거시 플러그인(forgejo/ops 등 = AppPack/템플릿으로 카드를 그리지만 핸들러가 없던 것)에 액션/핸들러를 부착해
+ * App(=actionIndex 가 픽업하는 상위집합)으로 증강한다. 플러그인의 register()(AppPack/템플릿/이벤트 등록)는
+ * 그대로 보존하므로 풍부한 서피스를 잃지 않는다 — defineApp 전체 전환 없이 "카드 버튼이 핸들러로 왕복"만 켠다.
+ *
+ * 코어 변경 0: enabledPlugins 의 원소를 plain plugin → withActions(plugin, …) 로 바꾸면 그 도메인의 버튼이 살아난다.
+ * 도메인 앱이므로 core=false(방의 room.binding 에 바인딩됐을 때만 동작) — 보안 게이트는 그대로 서버.
+ * App.surface(서피스-as-데이터)는 발행하지 않는다(레거시는 AppPack 클라 평면으로 렌더) → surfaceState=null.
+ */
+export declare function withActions(plugin: Plugin, opts: {
+    actions: AppAction[];
+    handlers: Record<string, ActionHandler>;
+}): App;
+/** Plugin 이 App(=defineApp 산출물)인지 판정 — 액션/핸들러/이벤트를 가진 상위집합. 라이브 AS 가 enabledPlugins 에서 App 만 추릴 때 쓴다. */
+export declare function isApp(p: Plugin): p is App;
+/** Plugin 목록(클라/AS 공통 enabledPlugins)에서 App 만 추린다. */
+export declare function enabledApps(plugins: Plugin[]): App[];
+/**
+ * action_id → 소유 App 인덱스 — 라이브 AS 가 들어온 org.corp.ui.action 을 어느 App 의 핸들러로 보낼지 결정한다
+ * (이게 onUiAction 을 도메인 하드코딩 대신 제너릭 dispatchAction 루프로 만드는 빠진 이음새였다).
+ * 충돌(같은 action_id 를 두 App 이 소유)은 부팅 시 즉시 throw(fail-fast) — registry 의 prefix-shadow
+ * 가드와 같은 보수적 거부 정책(조용한 first-writer-wins 금지). action_id 는 App 간 고유해야 하며,
+ * 앱은 자기 네임스페이스로 두는 게 안전하다.
+ */
+export declare function buildActionIndex(apps: App[]): Map<string, App>;
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/dist/app.js

@@ -0,0 +1,214 @@
+import { EventType, NS, buildAppSurface, buildUiMessageContent, registerEventEntry, } from "@underdogai/mesh-event-schemas";
+export function defineApp(def) {
+    const actions = new Map();
+    for (const a of def.actions ?? [])
+        actions.set(a.id, a);
+    const handlers = new Map();
+    for (const [id, h] of Object.entries(def.handlers ?? {}))
+        handlers.set(id, h);
+    const events = def.events ?? {};
+    const on = new Map();
+    for (const [type, h] of Object.entries(def.on ?? {}))
+        on.set(type, h);
+    // ui.action 구독 금지(fail-fast) — 액션은 권한 게이트를 지나는 dispatchAction 만이 진입로다.
+    // on 으로 받으면 scope/PL/발행자격 검사를 전부 우회하게 되므로 정의 시점에 거부한다.
+    if (on.has(EventType.UiAction)) {
+        throw new Error(`[app-sdk] 앱 '${def.app}': '${EventType.UiAction}' 은 on 으로 구독할 수 없습니다 — ` +
+            `액션 수신은 actions/handlers(권한 게이트 경유)로 선언하세요.`);
+    }
+    // 액션 id 네임스페이스 강제 — 핸들러 유무와 무관하게 정의 시점에 항상 검사한다(deferHandlers 여도).
+    assertActionNamespace(def.app, actions);
+    // 부팅 링크검사(fail-fast) — 흩어진 버튼/핸들러/스코프 연결의 정합성을 정의 시점에 확인한다.
+    // deferHandlers(런타임 경계 분리)면 핸들러는 나중에 attachHandlers 가 붙이며 그때 검사한다 → 여기선 건너뛴다.
+    if (!def.deferHandlers)
+        assertActionHandlerLinks(def.app, actions, handlers);
+    // 앱은 자기 네임스페이스(org.corp.<app>.) 안에서만 이벤트를 등록할 수 있다(소유 강제).
+    const nsPrefix = `${NS}.${def.app}.`;
+    // Plugin.register — 부팅 시 1회(registerPlugin 가 plugin.id 로 멱등 가드). 도메인 이벤트 스키마를 레지스트리에 등록(클라/AS 공통).
+    const register = () => {
+        for (const [type, ev] of Object.entries(events)) {
+            if (!type.startsWith(nsPrefix)) {
+                throw new Error(`[app-sdk] 앱 '${def.app}': 이벤트 타입 '${type}' 가 앱 네임스페이스 '${nsPrefix}' 밖입니다 — 남의 네임스페이스 등록 금지.`);
+            }
+            // register 는 멱등 가드 뒤라 1회만 호출되므로, false 는 *진짜 충돌*(다른 앱이 같은 타입/접두사 섀도잉)이다 → throw.
+            const ok = registerEventEntry({
+                type,
+                kind: "message",
+                schema: ev.schema,
+                publishableBy: ev.publishableBy ?? ["bridge", "agent"],
+                description: `${def.app} 앱 도메인 이벤트`,
+            });
+            if (!ok) {
+                throw new Error(`[app-sdk] 앱 '${def.app}': 이벤트 타입 '${type}' 등록 실패(이미 등록됨/접두사 충돌) — 타입 충돌을 확인하세요.`);
+            }
+        }
+        // 서피스는 데이터(org.corp.app.surface 상태 이벤트)로 흐르므로 registerAppPack(클라 평면) 불필요.
+    };
+    return {
+        id: def.id,
+        app: def.app,
+        displayName: def.displayName,
+        entityTypes: def.entityTypes,
+        core: def.core ?? false,
+        provides: { events: Object.keys(events) },
+        capabilities: deriveCapabilities(actions),
+        register,
+        actions,
+        handlers,
+        events,
+        on,
+        messageForEvent(type, content) {
+            const ev = events[type];
+            if (!ev)
+                return null;
+            const parsed = ev.schema.safeParse(content);
+            if (!parsed.success)
+                return null;
+            return buildUiMessageContent(ev.view(parsed.data));
+        },
+        surfaceState() {
+            // panel(=sidebar)은 필수 와이어 필드라 sidebar 없으면 서피스를 발행하지 않는다.
+            // main 은 sidebar 와 함께만 실어 보낸다(메인 영역 탭 콘텐츠). main 만 있는 앱은 v1 미지원.
+            if (!def.sidebar)
+                return null;
+            return buildAppSurface({
+                app: def.app,
+                display_name: def.displayName,
+                entity_type: def.entityTypes[0],
+                panel: def.sidebar,
+                main: def.main,
+                header: def.header,
+                canvas: def.canvas,
+                dock: def.dock,
+                composer: def.composer,
+                commandPalette: def.commandPalette,
+                objectMap: def.objectMap,
+                modals: def.modals,
+                theme: def.theme,
+            });
+        },
+    };
+}
+/**
+ * 액션↔핸들러 부팅 링크검사(fail-fast). defineApp 과 withActions 가 공유한다.
+ * (1) 핸들러 키가 액션에 없으면 = 오타/유령 핸들러 → throw(게이트는 통과하나 효과 0개로 status:"ran" 인데
+ *     아무 일도 안 일어나는 조용한 함정 차단). (2) 파괴적 액션에 핸들러 없으면 = 게이트만 통과하고 효과 없음 → throw.
+ */
+/**
+ * 액션 id 네임스페이스 강제(부팅 fail-fast) — 액션 id 는 `<app>.` 으로 시작해야 한다.
+ *
+ * 이벤트 타입에 이미 적용하던 소유 규칙(register 의 nsPrefix 검사)을 액션에도 똑같이 건다. action_id 는
+ * App 간 전역 고유해야 하고(buildActionIndex 가 충돌을 throw), 코어 프리미티브(approve/reject/cancel/send…)
+ * 와도 겹치면 안 되는데 — 평문 id 는 앱이 늘수록 충돌이 확정적이다(실제로 forgejo 의 PR 승인이 코어 invoice
+ * 의 "approve" 와 부딪혀 한 차례 우회한 전례가 있다). 소유자를 id 에 박아 구조적으로 막는다.
+ */
+function assertActionNamespace(label, actions) {
+    const prefix = `${label}.`;
+    for (const id of actions.keys()) {
+        if (!id.startsWith(prefix)) {
+            throw new Error(`[app-sdk] 앱 '${label}': 액션 id '${id}' 가 앱 네임스페이스 '${prefix}' 밖입니다 — ` +
+                `'${prefix}${id}' 처럼 앱 키를 접두사로 두세요(코어 프리미티브·타 앱과의 action_id 충돌 방지).`);
+        }
+    }
+}
+/**
+ * App 의 액션에서 capability 표면(scope/backendTools)을 자동 도출한다 — manifest.capabilities 로 게시되며,
+ * 코드(액션)와 선언이 한 출처라 어긋나지 않는다(서드파티 로딩 감사용 신분증). 액션 0개면 undefined.
+ */
+function deriveCapabilities(actions) {
+    const scopes = [...new Set([...actions.values()].map((a) => a.scope))];
+    const backendTools = [...new Set([...actions.values()].flatMap((a) => a.tools ?? []))];
+    if (!scopes.length && !backendTools.length)
+        return undefined;
+    return { ...(scopes.length ? { scopes } : {}), ...(backendTools.length ? { backendTools } : {}) };
+}
+function assertActionHandlerLinks(label, actions, handlers) {
+    for (const id of handlers.keys()) {
+        if (!actions.has(id)) {
+            throw new Error(`[app-sdk] 앱 '${label}': 핸들러 '${id}' 에 대응하는 액션이 없습니다(오타 가능). actions 에 정의하거나 핸들러 키를 고치세요.`);
+        }
+    }
+    for (const a of actions.values()) {
+        if (a.destructive && !handlers.has(a.id)) {
+            throw new Error(`[app-sdk] 앱 '${label}': 파괴적 액션 '${a.id}' 에 핸들러가 없습니다 — 핸들러를 정의하거나 destructive 를 내리세요.`);
+        }
+    }
+}
+/**
+ * service 핸들러를 (deferHandlers 로 만든) App 에 부착한다 — 런타임 경계 물리화의 호스트 측 절반.
+ * 클라는 contract/surface(핸들러 0)만 로드해 App 을 만들고, AS 만 `@chatops/app-<x>/service` 의 핸들러를 import 해
+ * 부팅 시 이걸 호출한다 → 핸들러(동작) 코드가 클라 번들에 실리지 않는다. 붙일 때 전체 링크검사를 수행한다(fail-fast).
+ * 같은 App 싱글톤의 handlers Map 을 채우므로 actionIndex/appsByName 가 참조하던 App 에 즉시 반영된다.
+ */
+export function attachHandlers(app, handlers) {
+    for (const [id, h] of Object.entries(handlers))
+        app.handlers.set(id, h);
+    assertActionHandlerLinks(app.app, app.actions, app.handlers);
+    return app;
+}
+/**
+ * 레거시 플러그인(forgejo/ops 등 = AppPack/템플릿으로 카드를 그리지만 핸들러가 없던 것)에 액션/핸들러를 부착해
+ * App(=actionIndex 가 픽업하는 상위집합)으로 증강한다. 플러그인의 register()(AppPack/템플릿/이벤트 등록)는
+ * 그대로 보존하므로 풍부한 서피스를 잃지 않는다 — defineApp 전체 전환 없이 "카드 버튼이 핸들러로 왕복"만 켠다.
+ *
+ * 코어 변경 0: enabledPlugins 의 원소를 plain plugin → withActions(plugin, …) 로 바꾸면 그 도메인의 버튼이 살아난다.
+ * 도메인 앱이므로 core=false(방의 room.binding 에 바인딩됐을 때만 동작) — 보안 게이트는 그대로 서버.
+ * App.surface(서피스-as-데이터)는 발행하지 않는다(레거시는 AppPack 클라 평면으로 렌더) → surfaceState=null.
+ */
+export function withActions(plugin, opts) {
+    const app = plugin.app ?? plugin.id;
+    const actions = new Map();
+    for (const a of opts.actions)
+        actions.set(a.id, a);
+    const handlers = new Map();
+    for (const [id, h] of Object.entries(opts.handlers))
+        handlers.set(id, h);
+    assertActionNamespace(app, actions);
+    assertActionHandlerLinks(app, actions, handlers);
+    return {
+        ...plugin,
+        app,
+        core: false,
+        // 레거시 manifest 의 capabilities 를 액션에서 도출한 값으로 덮어쓴다(withActions 로 부착한 액션의 실제 표면).
+        capabilities: deriveCapabilities(actions),
+        actions,
+        handlers,
+        events: {},
+        on: new Map(),
+        // 레거시 플러그인은 App.messageForEvent(이벤트→카드) 대신 자기 toCard/템플릿으로 렌더하고,
+        // 서피스는 AppPack(클라 평면)으로 등록한다 → App 의 데이터 평면 두 메서드는 비활성(null).
+        messageForEvent: () => null,
+        surfaceState: () => null,
+    };
+}
+/** Plugin 이 App(=defineApp 산출물)인지 판정 — 액션/핸들러/이벤트를 가진 상위집합. 라이브 AS 가 enabledPlugins 에서 App 만 추릴 때 쓴다. */
+export function isApp(p) {
+    const a = p;
+    return a.actions instanceof Map && a.handlers instanceof Map && typeof a.messageForEvent === "function";
+}
+/** Plugin 목록(클라/AS 공통 enabledPlugins)에서 App 만 추린다. */
+export function enabledApps(plugins) {
+    return plugins.filter(isApp);
+}
+/**
+ * action_id → 소유 App 인덱스 — 라이브 AS 가 들어온 org.corp.ui.action 을 어느 App 의 핸들러로 보낼지 결정한다
+ * (이게 onUiAction 을 도메인 하드코딩 대신 제너릭 dispatchAction 루프로 만드는 빠진 이음새였다).
+ * 충돌(같은 action_id 를 두 App 이 소유)은 부팅 시 즉시 throw(fail-fast) — registry 의 prefix-shadow
+ * 가드와 같은 보수적 거부 정책(조용한 first-writer-wins 금지). action_id 는 App 간 고유해야 하며,
+ * 앱은 자기 네임스페이스로 두는 게 안전하다.
+ */
+export function buildActionIndex(apps) {
+    const index = new Map();
+    for (const app of apps) {
+        for (const id of app.actions.keys()) {
+            const owner = index.get(id);
+            if (owner && owner !== app) {
+                throw new Error(`[app-sdk] action_id 충돌: '${id}' 를 앱 '${owner.app}' 와 '${app.app}' 가 모두 소유합니다. action_id 는 App 간 고유해야 합니다(앱 네임스페이스 권장).`);
+            }
+            if (!owner)
+                index.set(id, app);
+        }
+    }
+    return index;
+}
+//# sourceMappingURL=app.js.map

package/dist/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/dist/builders.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 카드/패널 빌더 — "이미 있는 닫힌 블록/바디"를 조합해 데이터(UiCardContent / PanelSpec)를 만든다.
+ *
+ * 핵심: 새 블록을 만들지 않는다(코어 어휘만 조합). 그래서 결과가 "데이터"로 남고 — App Service 가
+ * 그대로 와이어에 실어 보내면 클라가 가진 렌더러로 그린다(클라 무변경 = "AS만 추가해도 UI 등록").
+ */
+import { type Block, type PanelSpec, type SurfaceSection, type UiCardContent } from "@underdogai/mesh-event-schemas";
+import type { ButtonElement } from "./action.js";
+export interface CardOpts {
+    title?: string;
+    fallback?: string;
+    state?: UiCardContent["state"];
+    context?: UiCardContent["context"];
+}
+/** 타임라인 카드(UiCardContent) 빌더 — 기존 블록 조합 → 검증된 데이터. */
+export declare const card: {
+    /** 닫힌 블록 트리로 카드를 구성(반환 즉시 zod 검증된 UiCardContent). */
+    build(card_id: string, blocks: Block[], opts?: CardOpts): UiCardContent;
+    fields(items: {
+        label: string;
+        value: string;
+        short?: boolean;
+    }[]): Block;
+    text(text: string): Block;
+    actions(elements: ButtonElement[]): Block;
+    /** 텍스트/숫자/날짜 입력 — input 종류는 "text"(기본)·"textarea"·"number"·"date"·"datetime"·"time". */
+    input(name: string, opts?: {
+        label?: string;
+        input?: "text" | "textarea" | "number" | "date" | "datetime" | "time";
+        placeholder?: string;
+        required?: boolean;
+        value?: string;
+    }): Block;
+    /** 드롭다운 선택(단일/다중). */
+    select(name: string, options: {
+        value: string;
+        label: string;
+    }[], opts?: {
+        label?: string;
+        placeholder?: string;
+        value?: string;
+        multi?: boolean;
+    }): Block;
+    /** 라디오 그룹(옵션이 펼쳐져 보이는 단일 선택). */
+    radio(name: string, options: {
+        value: string;
+        label: string;
+    }[], opts?: {
+        label?: string;
+        value?: string;
+    }): Block;
+    /** 체크박스(불리언 수집). */
+    checkbox(name: string, label: string, opts?: {
+        checked?: boolean;
+    }): Block;
+    /** 토글 스위치(불리언 수집, on/off 어포던스). */
+    toggle(name: string, label: string, opts?: {
+        checked?: boolean;
+        onText?: string;
+        offText?: string;
+    }): Block;
+};
+/** 우측 셸 패널(PanelSpec) 빌더 — 닫힌 SurfaceBody 조합. value 문자열의 {{entity.path}} 는 클라가 바인딩. */
+export declare const panel: {
+    sections(sections: SurfaceSection[]): PanelSpec;
+    fields(id: string, title: string, items: {
+        label: string;
+        value: string;
+    }[]): SurfaceSection;
+    list(id: string, title: string, items: {
+        primary: string;
+        secondary?: string;
+    }[]): SurfaceSection;
+    memo(id: string, title: string, summary: string, updates?: string[]): SurfaceSection;
+    card(id: string, title: string, embedded: UiCardContent): SurfaceSection;
+};
+//# sourceMappingURL=builders.d.ts.map

package/dist/builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../src/builders.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAEL,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,QAAQ;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAC/B,OAAO,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;CACpC;AAED,sDAAsD;AACtD,eAAO,MAAM,IAAI;IACf,qDAAqD;mBACtC,MAAM,UAAU,KAAK,EAAE,SAAQ,QAAQ,GAAQ,aAAa;kBAU7D;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAAE,GAAG,KAAK;eAG9D,MAAM,GAAG,KAAK;sBAGP,aAAa,EAAE,GAAG,KAAK;IAMzC,wFAAwF;gBAC5E,MAAM,SAAQ;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAQ,KAAK;IAG1L,sBAAsB;iBACT,MAAM,WAAW;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,SAAQ;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAQ,KAAK;IAG9J,iCAAiC;gBACrB,MAAM,WAAW;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,SAAQ;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAQ,KAAK;IAGtH,oBAAoB;mBACL,MAAM,SAAS,MAAM,SAAQ;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAQ,KAAK;IAG9E,mCAAmC;iBACtB,MAAM,SAAS,MAAM,SAAQ;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAQ,KAAK;CAGhH,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,KAAK;uBACG,cAAc,EAAE,GAAG,SAAS;eAGpC,MAAM,SAAS,MAAM,SAAS;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,cAAc;aAGnF,MAAM,SAAS,MAAM,SAAS;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,cAAc;aAGxF,MAAM,SAAS,MAAM,WAAW,MAAM,YAAY,MAAM,EAAE,GAAG,cAAc;aAG3E,MAAM,SAAS,MAAM,YAAY,aAAa,GAAG,cAAc;CAGzE,CAAC"}