@obov/mext 0.5.0 → 0.7.1

package/dist/client/types.d.ts

@@ -0,0 +1,225 @@
+import type * as z from "zod";
+import type { Command, InputSchema } from "../command.ts";
+import type { ContentBlock, ResultValue } from "../content.ts";
+import type { ToolExposure } from "../mcp/dispatch.ts";
+import type { InputRequestObject } from "../remote/client.ts";
+import type { CallError } from "./typed.ts";
+/**
+ * 타입 client (@obov/mext/client, specs/client.md) 의 타입. 런타임 코드 없음.
+ * 이 파일의 import 는 전부 타입 import: 브라우저 번들에 Zod · 명령어 코드가 들어가지 않는다
+ */
+export type JsonSchema = Record<string, unknown>;
+/** 명령어 하나의 입력 · 출력 타입 */
+export interface CommandShape {
+    input: unknown;
+    output: unknown;
+}
+/** 타입 인자 없는 createClient() 의 명령어 표: ID = string, 입력 = 객체, 반환 = unknown */
+export type AnyCommands = Record<string, {
+    input: Record<string, unknown>;
+    output: unknown;
+}>;
+/** 명령어 표 제약. interface (생성 파일의 Commands) 도 통과한다 (index signature 를 요구하지 않는다) */
+export type CommandMap<C> = {
+    [K in keyof C]: CommandShape;
+};
+/**
+ * defineCommand 결과의 타입 → { input, output } (specs/client.md §3).
+ * input = z.input<input 스키마>. output = output 스키마가 있으면 z.output, 없으면 execute 반환 타입. 둘 다 JSON 으로 전송된 모양.
+ * 결과 콘텐츠 (mext.md §4) = withContent 의 값 타입, 콘텐츠만 = null (콘텐츠는 CallOptions.onContent)
+ */
+export type CommandTypes<T> = T extends Command<infer I extends InputSchema, infer R, infer O extends z.ZodType> ? {
+    input: z.input<I>;
+    output: Jsonify<z.ZodType extends O ? ResultValue<Awaited<R>> : z.output<O>>;
+} : never;
+export type InputOf<C extends CommandMap<C>, K extends keyof C> = C[K]["input"];
+export type OutputOf<C extends CommandMap<C>, K extends keyof C> = C[K]["output"];
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type JsonPrimitive = string | number | boolean | null;
+/** JSON.stringify 가 속성을 빼는 값 (함수 · symbol) */
+type Dropped = ((...args: never[]) => unknown) | symbol;
+/**
+ * JSON 으로 전송된 값의 타입: Date (toJSON) → string · undefined · void 반환 → null · undefined 속성 → 선택 ·
+ * 함수 · symbol 속성 제거 · Map · Set → 빈 객체 · bigint → never (직렬화할 수 없다). any · unknown 은 그대로
+ */
+export type Jsonify<T> = IsAny<T> extends true ? T : unknown extends T ? unknown : T extends JsonPrimitive ? T : T extends undefined | void ? null : T extends bigint ? never : T extends {
+    toJSON(): infer J;
+} ? Jsonify<J> : T extends Dropped ? never : T extends ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> ? Record<string, never> : T extends readonly unknown[] ? {
+    -readonly [K in keyof T]: Jsonify<T[K]>;
+} : T extends object ? JsonifyObject<T> : never;
+type JsonKey<T, K extends keyof T> = K extends string | number ? (Exclude<T[K], undefined> extends Dropped ? never : K) : never;
+type JsonifyObject<T> = Simplify<{
+    [K in keyof T as undefined extends T[K] ? never : JsonKey<T, K>]: Jsonify<T[K]>;
+} & {
+    [K in keyof T as undefined extends T[K] ? JsonKey<T, K> : never]?: Jsonify<Exclude<T[K], undefined>>;
+}>;
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+export interface ClientOptions {
+    /** MCP 엔드포인트 (http(s)://host/mcp). 브라우저 = 상대 경로 ("/mcp") 가능 */
+    url: string;
+    /** Authorization: Bearer <값>. 요청마다 호출 (함수). client 는 저장 · 갱신하지 않는다 */
+    token?: string | (() => string | undefined | Promise<string | undefined>);
+    /** 추가 요청 헤더. 요청마다 호출 */
+    headers?: Record<string, string> | (() => Record<string, string> | undefined | Promise<Record<string, string> | undefined>);
+    /** 자가 신고 clientInfo (ctx.caller.client). 기본 { name: "mext-client", version: mext 버전 상수 } */
+    clientInfo?: {
+        name: string;
+        version: string;
+    };
+    /** 서버 도구 노출 방식. 지정하면 server/discover 왕복을 생략한다 */
+    tools?: ToolExposure;
+    /** 기본 = 전역 fetch */
+    fetch?: typeof fetch;
+}
+export interface RequestOptions {
+    signal?: AbortSignal;
+}
+export interface ProgressUpdate {
+    progress?: number;
+    total?: number;
+    message?: string;
+}
+/** 서버의 입력 요청 하나 (ctx.ask · requiresConfirmation, MRTR · task input_required) */
+export interface InputRequestInfo {
+    /** 요청 키 (응답을 묶는 값) */
+    key: string;
+    /** confirm = 예 · 아니오, form = schema 에 맞는 값, url = URL 열기 동의 */
+    kind: "confirm" | "form" | "url";
+    message: string;
+    /** confirm · form: 요청한 값의 JSON Schema */
+    schema?: JsonSchema;
+    /** url: 사용자가 열 URL */
+    url?: string;
+    /** 호출한 명령어 ID (client.task(...).wait = "") */
+    command: string;
+    /** 서버가 보낸 요청 그대로 */
+    raw: InputRequestObject;
+}
+/**
+ * 입력 요청의 답. true = 승인 (confirm) · URL 열기 동의 (url) · 빈 값으로 수락 (form). false = 거절.
+ * 값을 보낼 때 = { action: "accept", content }
+ */
+export type InputAnswer = boolean | {
+    action: "accept";
+    content?: Record<string, unknown>;
+} | {
+    action: "decline" | "cancel";
+};
+export interface TaskStatus {
+    taskId: string;
+    /** working · input_required · completed · failed · cancelled */
+    status: string;
+    statusMessage?: string;
+}
+export interface CallOptions extends RequestOptions {
+    /** ctx.progress (SSE) · task statusMessage. 있으면 progressToken 을 싣는다 */
+    onProgress?: (update: ProgressUpdate) => void;
+    /** 입력 요청 처리. 없으면 입력 요청 = CallError INPUT_UNAVAILABLE */
+    onInput?: (request: InputRequestInfo) => InputAnswer | Promise<InputAnswer>;
+    /**
+     * 사람이 이 호출을 확인했다는 호출 코드의 선언 (specs/client.md §2.2 확인). 기본 false.
+     * 요청 _meta["dev.mext/approval"] = { confirmed: true } + confirm 입력 요청에 묻지 않고 승인
+     */
+    confirmed?: boolean;
+    /** task 로 실행될 때 (mext.md §12.6): 생성 · 상태 변화마다 */
+    onTask?: (task: TaskStatus) => void;
+    /** 결과 콘텐츠 (mext.md §4): 값 외 MCP 블록 (image · audio · resource_link). 있을 때 1회, call 이 값을 돌려주기 전 */
+    onContent?: (content: ContentBlock[]) => void;
+}
+export interface NamespaceSummary {
+    id: string;
+    /** _index.md 첫 줄 */
+    description?: string;
+}
+export interface CommandSummary {
+    id: string;
+    description: string;
+    readOnly: boolean;
+    destructive: boolean;
+    requiresConfirmation: boolean;
+    /** 승인 필요 (mext.md §4 승인). 서버가 주면 그대로 */
+    needsApproval?: true | "conditional";
+    /** split 노출에서 이 명령어를 호출할 도구 (query · mutate) */
+    tool?: string;
+    /** 서버가 준 그 밖의 필드 (client 보다 새 서버) */
+    [key: string]: unknown;
+}
+export interface CommandInfo extends CommandSummary {
+    aliases: string[];
+    scopes: string[];
+    positional: string[];
+    examples: unknown[];
+    /** JSON Schema 2020-12 */
+    inputSchema: JsonSchema;
+    outputSchema?: JsonSchema;
+    task?: {
+        ttlMs: number;
+    };
+    /** 이 명령어 호출이 돌려줄 수 있는 구조화 오류 code */
+    errors: string[];
+}
+export interface CommandList {
+    /** commands/_index.md */
+    description?: string;
+    /** 루트 제외, ID 순 */
+    namespaces: NamespaceSummary[];
+    /** ID 순 */
+    commands: CommandSummary[];
+}
+export interface ServerInfo {
+    /** 도구 노출 방식 */
+    tools: ToolExposure;
+    /** 이 호출자에게 보이는 명령어 기준 manifestHash (mext.md §5) */
+    manifestHash?: string;
+    /** serverInfo.name · version */
+    name?: string;
+    version?: string;
+    instructions?: string;
+    /** tasks 확장 선언 여부 (이 호출자 기준) */
+    tasks: boolean;
+}
+export interface TaskHandle {
+    readonly taskId: string;
+    /** tasks/get 1회 */
+    get(options?: RequestOptions): Promise<TaskStatus>;
+    /** 종료까지 폴링. 반환 · 오류 = call 과 같다 (입력 요청 · 진행률 · 취소 포함) */
+    wait(options?: CallOptions): Promise<unknown>;
+    /** tasks/cancel */
+    cancel(options?: RequestOptions): Promise<void>;
+}
+/** notifications/resources/updated 1건 */
+export interface ResourceUpdate {
+    uri: string;
+}
+export interface SubscribeOptions extends RequestOptions {
+    /** 갱신 알림마다. close · abort 뒤에는 부르지 않는다. 예외는 스트림에 영향 없음 */
+    onUpdate?: (update: ResourceUpdate) => void;
+}
+/** 스트림 종료. client = close() · signal abort, server = 서버 완료 · 스트림 종료 (재시작 · 배포), error = ack 뒤 연결 오류 */
+export type SubscriptionEnd = {
+    reason: "client";
+} | {
+    reason: "server";
+} | {
+    reason: "error";
+    error: CallError;
+};
+export interface Subscription {
+    /** 서버가 받아들인 URI (ack). subscribe 자원이 아니거나 scopes 가 없는 URI 는 빠진다 */
+    readonly resources: string[];
+    /** 스트림이 끝나면 resolve (reject 하지 않는다). 자동 재연결 없음 */
+    readonly closed: Promise<SubscriptionEnd>;
+    close(): void;
+}
+/** 입력이 전부 선택 필드면 입력 인자 생략 가능 */
+export type CallArgs<I> = {} extends I ? [input?: I, options?: CallOptions] : [input: I, options?: CallOptions];
+export type SafeResult<T, E> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+export {};

package/dist/client/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/client/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"","sourcesContent":["import type * as z from \"zod\"\nimport type { Command, InputSchema } from \"../command.ts\"\nimport type { ContentBlock, ResultValue } from \"../content.ts\"\nimport type { ToolExposure } from \"../mcp/dispatch.ts\"\nimport type { InputRequestObject } from \"../remote/client.ts\"\nimport type { CallError } from \"./typed.ts\"\n\n/**\n * 타입 client (@obov/mext/client, specs/client.md) 의 타입. 런타임 코드 없음.\n * 이 파일의 import 는 전부 타입 import: 브라우저 번들에 Zod · 명령어 코드가 들어가지 않는다\n */\n\nexport type JsonSchema = Record<string, unknown>\n\n/* 명령어 ID → 입력 · 출력 타입 */\n\n/** 명령어 하나의 입력 · 출력 타입 */\nexport interface CommandShape {\n  input: unknown\n  output: unknown\n}\n\n/** 타입 인자 없는 createClient() 의 명령어 표: ID = string, 입력 = 객체, 반환 = unknown */\nexport type AnyCommands = Record<string, { input: Record<string, unknown>; output: unknown }>\n\n/** 명령어 표 제약. interface (생성 파일의 Commands) 도 통과한다 (index signature 를 요구하지 않는다) */\nexport type CommandMap<C> = { [K in keyof C]: CommandShape }\n\n/**\n * defineCommand 결과의 타입 → { input, output } (specs/client.md §3).\n * input = z.input<input 스키마>. output = output 스키마가 있으면 z.output, 없으면 execute 반환 타입. 둘 다 JSON 으로 전송된 모양.\n * 결과 콘텐츠 (mext.md §4) = withContent 의 값 타입, 콘텐츠만 = null (콘텐츠는 CallOptions.onContent)\n */\nexport type CommandTypes<T> =\n  T extends Command<infer I extends InputSchema, infer R, infer O extends z.ZodType>\n    ? { input: z.input<I>; output: Jsonify<z.ZodType extends O ? ResultValue<Awaited<R>> : z.output<O>> }\n    : never\n\nexport type InputOf<C extends CommandMap<C>, K extends keyof C> = C[K][\"input\"]\nexport type OutputOf<C extends CommandMap<C>, K extends keyof C> = C[K][\"output\"]\n\ntype IsAny<T> = 0 extends 1 & T ? true : false\ntype JsonPrimitive = string | number | boolean | null\n/** JSON.stringify 가 속성을 빼는 값 (함수 · symbol) */\ntype Dropped = ((...args: never[]) => unknown) | symbol\n\n/**\n * JSON 으로 전송된 값의 타입: Date (toJSON) → string · undefined · void 반환 → null · undefined 속성 → 선택 ·\n * 함수 · symbol 속성 제거 · Map · Set → 빈 객체 · bigint → never (직렬화할 수 없다). any · unknown 은 그대로\n */\nexport type Jsonify<T> =\n  IsAny<T> extends true\n    ? T\n    : unknown extends T\n      ? unknown\n      : T extends JsonPrimitive\n        ? T\n        : T extends undefined | void\n          ? null\n          : T extends bigint\n            ? never\n            : T extends { toJSON(): infer J }\n              ? Jsonify<J>\n              : T extends Dropped\n                ? never\n                : T extends ReadonlyMap<unknown, unknown> | ReadonlySet<unknown>\n                  ? Record<string, never>\n                : T extends readonly unknown[]\n                  ? { -readonly [K in keyof T]: Jsonify<T[K]> }\n                  : T extends object\n                    ? JsonifyObject<T>\n                    : never\n\ntype JsonKey<T, K extends keyof T> = K extends string | number ? (Exclude<T[K], undefined> extends Dropped ? never : K) : never\n\ntype JsonifyObject<T> = Simplify<\n  { [K in keyof T as undefined extends T[K] ? never : JsonKey<T, K>]: Jsonify<T[K]> } & {\n    [K in keyof T as undefined extends T[K] ? JsonKey<T, K> : never]?: Jsonify<Exclude<T[K], undefined>>\n  }\n>\n\ntype Simplify<T> = { [K in keyof T]: T[K] } & {}\n\n/* 옵션 */\n\nexport interface ClientOptions {\n  /** MCP 엔드포인트 (http(s)://host/mcp). 브라우저 = 상대 경로 (\"/mcp\") 가능 */\n  url: string\n  /** Authorization: Bearer <값>. 요청마다 호출 (함수). client 는 저장 · 갱신하지 않는다 */\n  token?: string | (() => string | undefined | Promise<string | undefined>)\n  /** 추가 요청 헤더. 요청마다 호출 */\n  headers?: Record<string, string> | (() => Record<string, string> | undefined | Promise<Record<string, string> | undefined>)\n  /** 자가 신고 clientInfo (ctx.caller.client). 기본 { name: \"mext-client\", version: mext 버전 상수 } */\n  clientInfo?: { name: string; version: string }\n  /** 서버 도구 노출 방식. 지정하면 server/discover 왕복을 생략한다 */\n  tools?: ToolExposure\n  /** 기본 = 전역 fetch */\n  fetch?: typeof fetch\n}\n\nexport interface RequestOptions {\n  signal?: AbortSignal\n}\n\nexport interface ProgressUpdate {\n  progress?: number\n  total?: number\n  message?: string\n}\n\n/** 서버의 입력 요청 하나 (ctx.ask · requiresConfirmation, MRTR · task input_required) */\nexport interface InputRequestInfo {\n  /** 요청 키 (응답을 묶는 값) */\n  key: string\n  /** confirm = 예 · 아니오, form = schema 에 맞는 값, url = URL 열기 동의 */\n  kind: \"confirm\" | \"form\" | \"url\"\n  message: string\n  /** confirm · form: 요청한 값의 JSON Schema */\n  schema?: JsonSchema\n  /** url: 사용자가 열 URL */\n  url?: string\n  /** 호출한 명령어 ID (client.task(...).wait = \"\") */\n  command: string\n  /** 서버가 보낸 요청 그대로 */\n  raw: InputRequestObject\n}\n\n/**\n * 입력 요청의 답. true = 승인 (confirm) · URL 열기 동의 (url) · 빈 값으로 수락 (form). false = 거절.\n * 값을 보낼 때 = { action: \"accept\", content }\n */\nexport type InputAnswer = boolean | { action: \"accept\"; content?: Record<string, unknown> } | { action: \"decline\" | \"cancel\" }\n\nexport interface TaskStatus {\n  taskId: string\n  /** working · input_required · completed · failed · cancelled */\n  status: string\n  statusMessage?: string\n}\n\nexport interface CallOptions extends RequestOptions {\n  /** ctx.progress (SSE) · task statusMessage. 있으면 progressToken 을 싣는다 */\n  onProgress?: (update: ProgressUpdate) => void\n  /** 입력 요청 처리. 없으면 입력 요청 = CallError INPUT_UNAVAILABLE */\n  onInput?: (request: InputRequestInfo) => InputAnswer | Promise<InputAnswer>\n  /**\n   * 사람이 이 호출을 확인했다는 호출 코드의 선언 (specs/client.md §2.2 확인). 기본 false.\n   * 요청 _meta[\"dev.mext/approval\"] = { confirmed: true } + confirm 입력 요청에 묻지 않고 승인\n   */\n  confirmed?: boolean\n  /** task 로 실행될 때 (mext.md §12.6): 생성 · 상태 변화마다 */\n  onTask?: (task: TaskStatus) => void\n  /** 결과 콘텐츠 (mext.md §4): 값 외 MCP 블록 (image · audio · resource_link). 있을 때 1회, call 이 값을 돌려주기 전 */\n  onContent?: (content: ContentBlock[]) => void\n}\n\n/* 목록 · 스키마 */\n\nexport interface NamespaceSummary {\n  id: string\n  /** _index.md 첫 줄 */\n  description?: string\n}\n\nexport interface CommandSummary {\n  id: string\n  description: string\n  readOnly: boolean\n  destructive: boolean\n  requiresConfirmation: boolean\n  /** 승인 필요 (mext.md §4 승인). 서버가 주면 그대로 */\n  needsApproval?: true | \"conditional\"\n  /** split 노출에서 이 명령어를 호출할 도구 (query · mutate) */\n  tool?: string\n  /** 서버가 준 그 밖의 필드 (client 보다 새 서버) */\n  [key: string]: unknown\n}\n\nexport interface CommandInfo extends CommandSummary {\n  aliases: string[]\n  scopes: string[]\n  positional: string[]\n  examples: unknown[]\n  /** JSON Schema 2020-12 */\n  inputSchema: JsonSchema\n  outputSchema?: JsonSchema\n  task?: { ttlMs: number }\n  /** 이 명령어 호출이 돌려줄 수 있는 구조화 오류 code */\n  errors: string[]\n}\n\nexport interface CommandList {\n  /** commands/_index.md */\n  description?: string\n  /** 루트 제외, ID 순 */\n  namespaces: NamespaceSummary[]\n  /** ID 순 */\n  commands: CommandSummary[]\n}\n\nexport interface ServerInfo {\n  /** 도구 노출 방식 */\n  tools: ToolExposure\n  /** 이 호출자에게 보이는 명령어 기준 manifestHash (mext.md §5) */\n  manifestHash?: string\n  /** serverInfo.name · version */\n  name?: string\n  version?: string\n  instructions?: string\n  /** tasks 확장 선언 여부 (이 호출자 기준) */\n  tasks: boolean\n}\n\n/* client */\n\nexport interface TaskHandle {\n  readonly taskId: string\n  /** tasks/get 1회 */\n  get(options?: RequestOptions): Promise<TaskStatus>\n  /** 종료까지 폴링. 반환 · 오류 = call 과 같다 (입력 요청 · 진행률 · 취소 포함) */\n  wait(options?: CallOptions): Promise<unknown>\n  /** tasks/cancel */\n  cancel(options?: RequestOptions): Promise<void>\n}\n\n/* 자원 갱신 구독 (specs/client.md §2.4) */\n\n/** notifications/resources/updated 1건 */\nexport interface ResourceUpdate {\n  uri: string\n}\n\nexport interface SubscribeOptions extends RequestOptions {\n  /** 갱신 알림마다. close · abort 뒤에는 부르지 않는다. 예외는 스트림에 영향 없음 */\n  onUpdate?: (update: ResourceUpdate) => void\n}\n\n/** 스트림 종료. client = close() · signal abort, server = 서버 완료 · 스트림 종료 (재시작 · 배포), error = ack 뒤 연결 오류 */\nexport type SubscriptionEnd = { reason: \"client\" } | { reason: \"server\" } | { reason: \"error\"; error: CallError }\n\nexport interface Subscription {\n  /** 서버가 받아들인 URI (ack). subscribe 자원이 아니거나 scopes 가 없는 URI 는 빠진다 */\n  readonly resources: string[]\n  /** 스트림이 끝나면 resolve (reject 하지 않는다). 자동 재연결 없음 */\n  readonly closed: Promise<SubscriptionEnd>\n  close(): void\n}\n\n/** 입력이 전부 선택 필드면 입력 인자 생략 가능 */\nexport type CallArgs<I> = {} extends I ? [input?: I, options?: CallOptions] : [input: I, options?: CallOptions]\n\nexport type SafeResult<T, E> = { ok: true; value: T } | { ok: false; error: E }\n"]}

package/dist/command.d.ts

@@ -1,4 +1,6 @@
 import type * as z from "zod";
+import { type AuditTarget } from "./audit.ts";
+import { type Caller, type Exposure } from "./caller.ts";
 import type { Principal } from "./principal.ts";
 /**
  * 도입 프로젝트가 declaration merging 으로 채우는 ctx.app 타입.
@@ -36,6 +38,11 @@ export interface Ask {
 }
 export interface CommandContext {
     principal: Principal;
+    /**
+     * 호출자 맥락 (spec §4): 표면 (surface · transport) · 행위자 (actor) · client.
+     * surface · actor = 서버가 정한 값, client = 자가 신고 값 (판정 근거로 쓰지 않는다)
+     */
+    caller: Caller;
     signal: AbortSignal;
     progress(update: ProgressUpdate): void;
     ask: Ask;
@@ -48,16 +55,38 @@ export interface CommandContext {
 }
 export type InputSchema = z.ZodObject;
 type InputKey<I extends InputSchema> = keyof z.input<I> & string;
-export interface CommandDefinition<I extends InputSchema, R> {
+/**
+ * 명령어의 감사 옵션 (spec §11.1). config.audit.sink 가 있을 때만 쓰인다.
+ * result = 핸들러 반환값 (output 파싱 후). 실패 · 거부 = undefined.
+ * 타입이 unknown 인 이유: 반환 타입으로 두면 audit 을 execute 앞에 쓸 때 반환 타입 추론이 unknown 으로 굳는다
+ */
+export interface CommandAudit<I extends InputSchema = InputSchema> {
+    /** 대상. type · id 외 값 (버전 해시 등) 을 자유롭게 싣는다. undefined = 대상 없음 */
+    target?: (input: z.output<I>, result: unknown) => AuditTarget | undefined;
+    /** 사람이 읽는 한 줄 */
+    summary?: string | ((input: z.output<I>, result: unknown) => string | undefined);
+    /** 입력 기록. 함수 = 가린 값 (실행 전에 계산), false = 기록하지 않는다. 기본 = 검증된 입력 그대로 */
+    input?: boolean | ((input: z.output<I>) => unknown);
+}
+export interface CommandDefinition<I extends InputSchema, R, O extends z.ZodType = z.ZodType> {
     /** 필수. help · MCP 설명의 원본 */
     description: string;
     /** 필수. 최상위 z.object */
     input: I;
     /** 선택. MCP outputSchema 의 원본 (tools: "command"). 있으면 모든 어댑터가 반환값을 검증 (실패 = EXECUTION_ERROR) */
-    output?: z.ZodType;
+    output?: O;
     readOnly?: boolean;
     destructive?: boolean;
+    /** needsApproval: true 와 같다 (이전 이름). 둘 중 하나라도 필요하면 필요 */
     requiresConfirmation?: boolean;
+    /**
+     * 사람의 승인이 필요한 호출 (spec §4 승인). true = 항상. 조건식 = false 를 돌려줄 때만 승인 불필요
+     * (그 외 반환값 · 예외 = 승인 필요, 예외는 onCommandError 보고). 입력 검증 · authorize 뒤, execute 전에 판정한다.
+     * 승인이 필요하면 표면의 확인 방식 (mext.config.ts approval.surfaces, 기본 ask) 으로 확인한다:
+     * ask = ctx.ask (CLI 프롬프트 · --yes, MCP MRTR), client = 요청 _meta 의 확인 표시 + human 행위자.
+     * 서버가 agent 로 정한 행위자는 승인할 수 없다 (APPROVAL_REQUIRED). MRTR 재시도마다 다시 판정되므로 부작용 없는 판정만
+     */
+    needsApproval?: boolean | ((input: z.output<I>, ctx: CommandContext) => boolean | Promise<boolean>);
     /** 실행에 필요한 scopes. 전부 보유해야 실행 */
     scopes?: readonly string[];
     examples?: readonly z.input<I>[];
@@ -72,6 +101,21 @@ export interface CommandDefinition<I extends InputSchema, R> {
     task?: boolean | {
         ttlMs: number;
     };
+    /** 감사 이벤트의 대상 · 요약 · 입력 가림 (spec §11.1) */
+    audit?: CommandAudit<I>;
+    /**
+     * 표면별 노출 (spec §4). 기본 = 모든 표면. 숨긴 표면에서는 목록 (help · tools/list) 에 없고 호출 = UNKNOWN_COMMAND.
+     * 판정 기준 = 요청 주체의 표면 (ctx.caller.surface: principal.surface, 없으면 어댑터 기본 cli · mcp · stdio)
+     */
+    expose?: Exposure;
+    /**
+     * 실행 가드 (spec §4). 입력 검증 뒤 · 확인 (requiresConfirmation) 과 execute 전에 호출한다. scopes 검사는 그 전에 그대로.
+     * true 만 통과. 그 외 반환값 (false · undefined · 반환 없음) · 예외 = PERMISSION_DENIED (reason "authorize").
+     * 반환 타입이 boolean 이라 반환 없는 가드 · `return user?.isAdmin` (boolean | undefined) 은 컴파일 오류다.
+     * CommandError 를 던지면 그 message 가 거부 message. 그 외 예외 = 거부 + onCommandError 보고.
+     * ctx = execute 와 같은 ctx (ctx.caller 의 표면 · 행위자). MRTR 재시도마다 다시 호출되므로 부작용 없는 판정만
+     */
+    authorize?(input: z.output<I>, ctx: CommandContext): boolean | Promise<boolean>;
     execute(input: z.output<I>, ctx: CommandContext): R | Promise<R>;
 }
 /** task 명령어의 기본 ttlMs (1시간) */
@@ -81,22 +125,34 @@ export interface TaskOptions {
     ttlMs: number;
 }
 export declare const COMMAND: unique symbol;
-export interface Command<I extends InputSchema = InputSchema, R = unknown> {
+export interface Command<I extends InputSchema = InputSchema, R = unknown, O extends z.ZodType = z.ZodType> {
     readonly [COMMAND]: true;
     readonly description: string;
     readonly input: I;
-    readonly output: z.ZodType | undefined;
+    readonly output: O | undefined;
     readonly readOnly: boolean;
     readonly destructive: boolean;
+    /** 항상 승인 필요 (requiresConfirmation: true · needsApproval: true) */
     readonly requiresConfirmation: boolean;
+    /**
+     * 승인 조건식 (needsApproval 이 함수일 때만. 항상 필요 = requiresConfirmation). manifest · help = needsApproval: "conditional".
+     * lazy Registry 의 메타데이터 명령어 = 호출할 수 없는 자리 표시 (모듈 로드 후의 명령어에서 부른다)
+     */
+    needsApproval?(input: z.output<I>, ctx: CommandContext): boolean | Promise<boolean>;
     readonly scopes: readonly string[];
     readonly examples: readonly z.input<I>[];
     readonly positional: readonly string[];
     readonly aliases: readonly string[];
     /** task 명령어 (§12.6). 없음 = 항상 동기 */
     readonly task?: TaskOptions;
+    /** 감사 옵션 (§11.1). 없음 = 기본 (검증된 입력 그대로, 대상 · 요약 없음) */
+    readonly audit?: Readonly<CommandAudit<I>>;
+    /** 표면별 노출 (§4). 없음 = 모든 표면 */
+    readonly expose?: Exposure;
+    /** 실행 가드 (§4). 없음 = 가드 없음. lazy Registry 의 메타데이터 명령어에는 없다 (모듈 로드 후의 명령어에서 읽는다) */
+    authorize?(input: z.output<I>, ctx: CommandContext): boolean | Promise<boolean>;
     execute(input: z.output<I>, ctx: CommandContext): R | Promise<R>;
 }
-export declare function defineCommand<I extends InputSchema, R>(definition: CommandDefinition<I, R>): Command<I, R>;
+export declare function defineCommand<I extends InputSchema, R, O extends z.ZodType = z.ZodType>(definition: CommandDefinition<I, R, O>): Command<I, R, O>;
 export declare function isCommand(value: unknown): value is Command;
 export {};

package/dist/command.js

@@ -1,3 +1,5 @@
+import { commandAuditProblem } from "./audit.js";
+import { exposeProblem } from "./caller.js";
 /** task 명령어의 기본 ttlMs (1시간) */
 export const DEFAULT_TASK_TTL_MS = 3_600_000;
 export const COMMAND = Symbol.for("@obov/mext/command");
@@ -19,6 +21,29 @@ export function defineCommand(definition) {
         }
     }
     const task = taskOptions(d.task);
+    if (d.audit !== undefined) {
+        const problem = commandAuditProblem(d.audit);
+        if (problem !== undefined)
+            throw new TypeError(`defineCommand: ${problem}`);
+    }
+    const audit = d.audit === undefined ? undefined : Object.freeze({ ...d.audit });
+    if (d.expose !== undefined) {
+        const problem = exposeProblem(d.expose);
+        if (problem !== undefined)
+            throw new TypeError(`defineCommand: ${problem}`);
+    }
+    // 빈 객체 = 규칙 없음 (없는 것과 같다)
+    const expose = d.expose === undefined || Object.keys(d.expose).length === 0 ? undefined : Object.freeze({ ...d.expose });
+    if (d.authorize !== undefined && typeof d.authorize !== "function") {
+        throw new TypeError("defineCommand: authorize must be a function");
+    }
+    const authorize = d.authorize;
+    if (d.needsApproval !== undefined && typeof d.needsApproval !== "boolean" && typeof d.needsApproval !== "function") {
+        throw new TypeError("defineCommand: needsApproval must be a boolean or a function");
+    }
+    // 항상 필요 = requiresConfirmation (정규형). 조건식은 항상 필요가 아닐 때만 남긴다
+    const alwaysApproval = d.requiresConfirmation === true || d.needsApproval === true;
+    const approvalCondition = !alwaysApproval && typeof d.needsApproval === "function" ? d.needsApproval : undefined;
     const execute = d.execute;
     return Object.freeze({
         [COMMAND]: true,
@@ -27,12 +52,28 @@ export function defineCommand(definition) {
         output: d.output,
         readOnly: d.readOnly === true,
         destructive: d.destructive === true,
-        requiresConfirmation: d.requiresConfirmation === true,
+        requiresConfirmation: alwaysApproval,
+        ...(approvalCondition
+            ? {
+                needsApproval(input, ctx) {
+                    return approvalCondition.call(definition, input, ctx);
+                },
+            }
+            : {}),
         scopes: Object.freeze([...(d.scopes ?? [])]),
         examples: Object.freeze([...(d.examples ?? [])]),
         positional: Object.freeze([...(d.positional ?? [])]),
         aliases: Object.freeze([...(d.aliases ?? [])]),
         ...(task ? { task } : {}),
+        ...(audit ? { audit } : {}),
+        ...(expose ? { expose } : {}),
+        ...(authorize
+            ? {
+                authorize(input, ctx) {
+                    return authorize.call(definition, input, ctx);
+                },
+            }
+            : {}),
         execute(input, ctx) {
             return execute.call(definition, input, ctx);
         },

package/dist/command.js.map

@@ -1 +1 @@
-{"version":3,"file":"command.js","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"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","sourcesContent":["import type * as z from \"zod\"\nimport type { Principal } from \"./principal.ts\"\n\n/**\n * 도입 프로젝트가 declaration merging 으로 채우는 ctx.app 타입.\n *\n *   declare module \"@obov/mext\" { interface MextApp { db: Db } }\n */\nexport interface MextApp {}\n\nexport interface ProgressUpdate {\n  progress: number\n  total?: number\n  message?: string\n}\n\nexport interface ConfirmRequest {\n  kind: \"confirm\"\n  message: string\n}\n\nexport interface InputRequest<S extends z.ZodObject = z.ZodObject> {\n  kind: \"input\"\n  message: string\n  schema: S\n}\n\n/** URL 모드 (spec §12.4). 제3자 인가 · API 키 · 결제처럼 클라이언트를 거치면 안 되는 입력. url = http(s) 절대 URL */\nexport interface UrlRequest {\n  kind: \"url\"\n  message: string\n  url: string\n}\n\nexport type AskRequest = ConfirmRequest | InputRequest | UrlRequest\n\n/** ctx.ask. confirm = boolean, input = schema 로 검증된 값, url = boolean (accept = URL 열기 동의. 완료 의미 아님) */\nexport interface Ask {\n  (request: ConfirmRequest): Promise<boolean>\n  (request: UrlRequest): Promise<boolean>\n  <S extends z.ZodObject>(request: InputRequest<S>): Promise<z.output<S>>\n}\n\nexport interface CommandContext {\n  principal: Principal\n  signal: AbortSignal\n  progress(update: ProgressUpdate): void\n  ask: Ask\n  app: MextApp\n  /**\n   * 자원 갱신 알림 (§12.5) → 구독 중인 subscriptions/listen 스트림에 notifications/resources/updated.\n   * state 없음 · 구독 없음 · 로컬 CLI 실행 = no-op. bus 발행 실패 = stderr 1줄 (거부하지 않음)\n   */\n  resourceUpdated(uri: string): Promise<void>\n}\n\nexport type InputSchema = z.ZodObject\n\ntype InputKey<I extends InputSchema> = keyof z.input<I> & string\n\nexport interface CommandDefinition<I extends InputSchema, R> {\n  /** 필수. help · MCP 설명의 원본 */\n  description: string\n  /** 필수. 최상위 z.object */\n  input: I\n  /** 선택. MCP outputSchema 의 원본 (tools: \"command\"). 있으면 모든 어댑터가 반환값을 검증 (실패 = EXECUTION_ERROR) */\n  output?: z.ZodType\n  readOnly?: boolean\n  destructive?: boolean\n  requiresConfirmation?: boolean\n  /** 실행에 필요한 scopes. 전부 보유해야 실행 */\n  scopes?: readonly string[]\n  examples?: readonly z.input<I>[]\n  /** CLI positional 인자로 받을 input 키 순서 */\n  positional?: readonly InputKey<I>[]\n  /** 같은 네임스페이스 안 kebab-case 세그먼트. commands/users/get.ts 의 \"fetch\" → users.fetch */\n  aliases?: readonly string[]\n  /**\n   * 장시간 명령어. 조건 (state.store · 클라이언트 선언) 이 맞으면 MCP tasks 확장으로 실행 (§12.6).\n   * true = 기본 ttlMs (DEFAULT_TASK_TTL_MS). ttlMs = 종료 후 tasks/get 으로 조회할 수 있는 시간\n   */\n  task?: boolean | { ttlMs: number }\n  execute(input: z.output<I>, ctx: CommandContext): R | Promise<R>\n}\n\n/** task 명령어의 기본 ttlMs (1시간) */\nexport const DEFAULT_TASK_TTL_MS = 3_600_000\n\n/** defineCommand 의 task 정규형 */\nexport interface TaskOptions {\n  ttlMs: number\n}\n\nexport const COMMAND: unique symbol = Symbol.for(\"@obov/mext/command\") as never\n\nexport interface Command<I extends InputSchema = InputSchema, R = unknown> {\n  readonly [COMMAND]: true\n  readonly description: string\n  readonly input: I\n  readonly output: z.ZodType | undefined\n  readonly readOnly: boolean\n  readonly destructive: boolean\n  readonly requiresConfirmation: boolean\n  readonly scopes: readonly string[]\n  readonly examples: readonly z.input<I>[]\n  readonly positional: readonly string[]\n  readonly aliases: readonly string[]\n  /** task 명령어 (§12.6). 없음 = 항상 동기 */\n  readonly task?: TaskOptions\n  execute(input: z.output<I>, ctx: CommandContext): R | Promise<R>\n}\n\nexport function defineCommand<I extends InputSchema, R>(definition: CommandDefinition<I, R>): Command<I, R> {\n  const d = definition as Partial<CommandDefinition<I, R>>\n  if (typeof d.description !== \"string\" || d.description.trim() === \"\") {\n    throw new TypeError(\"defineCommand: description must be a non-empty string\")\n  }\n  if (!isObjectSchema(d.input)) {\n    throw new TypeError(\"defineCommand: input must be a top-level z.object schema\")\n  }\n  if (typeof d.execute !== \"function\") {\n    throw new TypeError(\"defineCommand: execute must be a function\")\n  }\n  const shapeKeys = Object.keys(d.input.shape)\n  for (const key of d.positional ?? []) {\n    if (!shapeKeys.includes(key)) {\n      throw new TypeError(`defineCommand: positional \"${key}\" is not an input key`)\n    }\n  }\n  const task = taskOptions(d.task)\n  const execute = d.execute\n  return Object.freeze({\n    [COMMAND]: true as const,\n    description: d.description,\n    input: d.input,\n    output: d.output,\n    readOnly: d.readOnly === true,\n    destructive: d.destructive === true,\n    requiresConfirmation: d.requiresConfirmation === true,\n    scopes: Object.freeze([...(d.scopes ?? [])]),\n    examples: Object.freeze([...(d.examples ?? [])]),\n    positional: Object.freeze([...(d.positional ?? [])]),\n    aliases: Object.freeze([...(d.aliases ?? [])]),\n    ...(task ? { task } : {}),\n    execute(input: z.output<I>, ctx: CommandContext) {\n      return execute.call(definition, input, ctx)\n    },\n  })\n}\n\n/** task: true | { ttlMs } → TaskOptions. false · undefined = 없음, 그 외 = TypeError */\nfunction taskOptions(value: unknown): TaskOptions | undefined {\n  if (value === undefined || value === false) return undefined\n  if (value === true) return Object.freeze({ ttlMs: DEFAULT_TASK_TTL_MS })\n  const ttlMs = (value as { ttlMs?: unknown } | null)?.ttlMs\n  if (typeof value !== \"object\" || !Number.isSafeInteger(ttlMs) || (ttlMs as number) <= 0) {\n    throw new TypeError(\"defineCommand: task must be true or { ttlMs: <positive integer> }\")\n  }\n  return Object.freeze({ ttlMs: ttlMs as number })\n}\n\nexport function isCommand(value: unknown): value is Command {\n  return typeof value === \"object\" && value !== null && (value as Record<symbol, unknown>)[COMMAND] === true\n}\n\nfunction isObjectSchema(value: unknown): value is InputSchema {\n  const def = (value as { _zod?: { def?: { type?: unknown } } } | undefined)?._zod?.def\n  return def?.type === \"object\" && typeof (value as { safeParseAsync?: unknown }).safeParseAsync === \"function\"\n}\n"]}
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"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","sourcesContent":["import type * as z from \"zod\"\nimport { commandAuditProblem, type AuditTarget } from \"./audit.ts\"\nimport { exposeProblem, type Caller, type Exposure } from \"./caller.ts\"\nimport type { Principal } from \"./principal.ts\"\n\n/**\n * 도입 프로젝트가 declaration merging 으로 채우는 ctx.app 타입.\n *\n *   declare module \"@obov/mext\" { interface MextApp { db: Db } }\n */\nexport interface MextApp {}\n\nexport interface ProgressUpdate {\n  progress: number\n  total?: number\n  message?: string\n}\n\nexport interface ConfirmRequest {\n  kind: \"confirm\"\n  message: string\n}\n\nexport interface InputRequest<S extends z.ZodObject = z.ZodObject> {\n  kind: \"input\"\n  message: string\n  schema: S\n}\n\n/** URL 모드 (spec §12.4). 제3자 인가 · API 키 · 결제처럼 클라이언트를 거치면 안 되는 입력. url = http(s) 절대 URL */\nexport interface UrlRequest {\n  kind: \"url\"\n  message: string\n  url: string\n}\n\nexport type AskRequest = ConfirmRequest | InputRequest | UrlRequest\n\n/** ctx.ask. confirm = boolean, input = schema 로 검증된 값, url = boolean (accept = URL 열기 동의. 완료 의미 아님) */\nexport interface Ask {\n  (request: ConfirmRequest): Promise<boolean>\n  (request: UrlRequest): Promise<boolean>\n  <S extends z.ZodObject>(request: InputRequest<S>): Promise<z.output<S>>\n}\n\nexport interface CommandContext {\n  principal: Principal\n  /**\n   * 호출자 맥락 (spec §4): 표면 (surface · transport) · 행위자 (actor) · client.\n   * surface · actor = 서버가 정한 값, client = 자가 신고 값 (판정 근거로 쓰지 않는다)\n   */\n  caller: Caller\n  signal: AbortSignal\n  progress(update: ProgressUpdate): void\n  ask: Ask\n  app: MextApp\n  /**\n   * 자원 갱신 알림 (§12.5) → 구독 중인 subscriptions/listen 스트림에 notifications/resources/updated.\n   * state 없음 · 구독 없음 · 로컬 CLI 실행 = no-op. bus 발행 실패 = stderr 1줄 (거부하지 않음)\n   */\n  resourceUpdated(uri: string): Promise<void>\n}\n\nexport type InputSchema = z.ZodObject\n\ntype InputKey<I extends InputSchema> = keyof z.input<I> & string\n\n/**\n * 명령어의 감사 옵션 (spec §11.1). config.audit.sink 가 있을 때만 쓰인다.\n * result = 핸들러 반환값 (output 파싱 후). 실패 · 거부 = undefined.\n * 타입이 unknown 인 이유: 반환 타입으로 두면 audit 을 execute 앞에 쓸 때 반환 타입 추론이 unknown 으로 굳는다\n */\nexport interface CommandAudit<I extends InputSchema = InputSchema> {\n  /** 대상. type · id 외 값 (버전 해시 등) 을 자유롭게 싣는다. undefined = 대상 없음 */\n  target?: (input: z.output<I>, result: unknown) => AuditTarget | undefined\n  /** 사람이 읽는 한 줄 */\n  summary?: string | ((input: z.output<I>, result: unknown) => string | undefined)\n  /** 입력 기록. 함수 = 가린 값 (실행 전에 계산), false = 기록하지 않는다. 기본 = 검증된 입력 그대로 */\n  input?: boolean | ((input: z.output<I>) => unknown)\n}\n\nexport interface CommandDefinition<I extends InputSchema, R, O extends z.ZodType = z.ZodType> {\n  /** 필수. help · MCP 설명의 원본 */\n  description: string\n  /** 필수. 최상위 z.object */\n  input: I\n  /** 선택. MCP outputSchema 의 원본 (tools: \"command\"). 있으면 모든 어댑터가 반환값을 검증 (실패 = EXECUTION_ERROR) */\n  output?: O\n  readOnly?: boolean\n  destructive?: boolean\n  /** needsApproval: true 와 같다 (이전 이름). 둘 중 하나라도 필요하면 필요 */\n  requiresConfirmation?: boolean\n  /**\n   * 사람의 승인이 필요한 호출 (spec §4 승인). true = 항상. 조건식 = false 를 돌려줄 때만 승인 불필요\n   * (그 외 반환값 · 예외 = 승인 필요, 예외는 onCommandError 보고). 입력 검증 · authorize 뒤, execute 전에 판정한다.\n   * 승인이 필요하면 표면의 확인 방식 (mext.config.ts approval.surfaces, 기본 ask) 으로 확인한다:\n   * ask = ctx.ask (CLI 프롬프트 · --yes, MCP MRTR), client = 요청 _meta 의 확인 표시 + human 행위자.\n   * 서버가 agent 로 정한 행위자는 승인할 수 없다 (APPROVAL_REQUIRED). MRTR 재시도마다 다시 판정되므로 부작용 없는 판정만\n   */\n  needsApproval?: boolean | ((input: z.output<I>, ctx: CommandContext) => boolean | Promise<boolean>)\n  /** 실행에 필요한 scopes. 전부 보유해야 실행 */\n  scopes?: readonly string[]\n  examples?: readonly z.input<I>[]\n  /** CLI positional 인자로 받을 input 키 순서 */\n  positional?: readonly InputKey<I>[]\n  /** 같은 네임스페이스 안 kebab-case 세그먼트. commands/users/get.ts 의 \"fetch\" → users.fetch */\n  aliases?: readonly string[]\n  /**\n   * 장시간 명령어. 조건 (state.store · 클라이언트 선언) 이 맞으면 MCP tasks 확장으로 실행 (§12.6).\n   * true = 기본 ttlMs (DEFAULT_TASK_TTL_MS). ttlMs = 종료 후 tasks/get 으로 조회할 수 있는 시간\n   */\n  task?: boolean | { ttlMs: number }\n  /** 감사 이벤트의 대상 · 요약 · 입력 가림 (spec §11.1) */\n  audit?: CommandAudit<I>\n  /**\n   * 표면별 노출 (spec §4). 기본 = 모든 표면. 숨긴 표면에서는 목록 (help · tools/list) 에 없고 호출 = UNKNOWN_COMMAND.\n   * 판정 기준 = 요청 주체의 표면 (ctx.caller.surface: principal.surface, 없으면 어댑터 기본 cli · mcp · stdio)\n   */\n  expose?: Exposure\n  /**\n   * 실행 가드 (spec §4). 입력 검증 뒤 · 확인 (requiresConfirmation) 과 execute 전에 호출한다. scopes 검사는 그 전에 그대로.\n   * true 만 통과. 그 외 반환값 (false · undefined · 반환 없음) · 예외 = PERMISSION_DENIED (reason \"authorize\").\n   * 반환 타입이 boolean 이라 반환 없는 가드 · `return user?.isAdmin` (boolean | undefined) 은 컴파일 오류다.\n   * CommandError 를 던지면 그 message 가 거부 message. 그 외 예외 = 거부 + onCommandError 보고.\n   * ctx = execute 와 같은 ctx (ctx.caller 의 표면 · 행위자). MRTR 재시도마다 다시 호출되므로 부작용 없는 판정만\n   */\n  authorize?(input: z.output<I>, ctx: CommandContext): boolean | Promise<boolean>\n  execute(input: z.output<I>, ctx: CommandContext): R | Promise<R>\n}\n\n/** task 명령어의 기본 ttlMs (1시간) */\nexport const DEFAULT_TASK_TTL_MS = 3_600_000\n\n/** defineCommand 의 task 정규형 */\nexport interface TaskOptions {\n  ttlMs: number\n}\n\nexport const COMMAND: unique symbol = Symbol.for(\"@obov/mext/command\") as never\n\nexport interface Command<I extends InputSchema = InputSchema, R = unknown, O extends z.ZodType = z.ZodType> {\n  readonly [COMMAND]: true\n  readonly description: string\n  readonly input: I\n  readonly output: O | undefined\n  readonly readOnly: boolean\n  readonly destructive: boolean\n  /** 항상 승인 필요 (requiresConfirmation: true · needsApproval: true) */\n  readonly requiresConfirmation: boolean\n  /**\n   * 승인 조건식 (needsApproval 이 함수일 때만. 항상 필요 = requiresConfirmation). manifest · help = needsApproval: \"conditional\".\n   * lazy Registry 의 메타데이터 명령어 = 호출할 수 없는 자리 표시 (모듈 로드 후의 명령어에서 부른다)\n   */\n  needsApproval?(input: z.output<I>, ctx: CommandContext): boolean | Promise<boolean>\n  readonly scopes: readonly string[]\n  readonly examples: readonly z.input<I>[]\n  readonly positional: readonly string[]\n  readonly aliases: readonly string[]\n  /** task 명령어 (§12.6). 없음 = 항상 동기 */\n  readonly task?: TaskOptions\n  /** 감사 옵션 (§11.1). 없음 = 기본 (검증된 입력 그대로, 대상 · 요약 없음) */\n  readonly audit?: Readonly<CommandAudit<I>>\n  /** 표면별 노출 (§4). 없음 = 모든 표면 */\n  readonly expose?: Exposure\n  /** 실행 가드 (§4). 없음 = 가드 없음. lazy Registry 의 메타데이터 명령어에는 없다 (모듈 로드 후의 명령어에서 읽는다) */\n  authorize?(input: z.output<I>, ctx: CommandContext): boolean | Promise<boolean>\n  execute(input: z.output<I>, ctx: CommandContext): R | Promise<R>\n}\n\nexport function defineCommand<I extends InputSchema, R, O extends z.ZodType = z.ZodType>(\n  definition: CommandDefinition<I, R, O>,\n): Command<I, R, O> {\n  const d = definition as Partial<CommandDefinition<I, R, O>>\n  if (typeof d.description !== \"string\" || d.description.trim() === \"\") {\n    throw new TypeError(\"defineCommand: description must be a non-empty string\")\n  }\n  if (!isObjectSchema(d.input)) {\n    throw new TypeError(\"defineCommand: input must be a top-level z.object schema\")\n  }\n  if (typeof d.execute !== \"function\") {\n    throw new TypeError(\"defineCommand: execute must be a function\")\n  }\n  const shapeKeys = Object.keys(d.input.shape)\n  for (const key of d.positional ?? []) {\n    if (!shapeKeys.includes(key)) {\n      throw new TypeError(`defineCommand: positional \"${key}\" is not an input key`)\n    }\n  }\n  const task = taskOptions(d.task)\n  if (d.audit !== undefined) {\n    const problem = commandAuditProblem(d.audit)\n    if (problem !== undefined) throw new TypeError(`defineCommand: ${problem}`)\n  }\n  const audit = d.audit === undefined ? undefined : Object.freeze({ ...d.audit })\n  if (d.expose !== undefined) {\n    const problem = exposeProblem(d.expose)\n    if (problem !== undefined) throw new TypeError(`defineCommand: ${problem}`)\n  }\n  // 빈 객체 = 규칙 없음 (없는 것과 같다)\n  const expose = d.expose === undefined || Object.keys(d.expose).length === 0 ? undefined : (Object.freeze({ ...d.expose }) as Exposure)\n  if (d.authorize !== undefined && typeof d.authorize !== \"function\") {\n    throw new TypeError(\"defineCommand: authorize must be a function\")\n  }\n  const authorize = d.authorize\n  if (d.needsApproval !== undefined && typeof d.needsApproval !== \"boolean\" && typeof d.needsApproval !== \"function\") {\n    throw new TypeError(\"defineCommand: needsApproval must be a boolean or a function\")\n  }\n  // 항상 필요 = requiresConfirmation (정규형). 조건식은 항상 필요가 아닐 때만 남긴다\n  const alwaysApproval = d.requiresConfirmation === true || d.needsApproval === true\n  const approvalCondition = !alwaysApproval && typeof d.needsApproval === \"function\" ? d.needsApproval : undefined\n  const execute = d.execute\n  return Object.freeze({\n    [COMMAND]: true as const,\n    description: d.description,\n    input: d.input,\n    output: d.output,\n    readOnly: d.readOnly === true,\n    destructive: d.destructive === true,\n    requiresConfirmation: alwaysApproval,\n    ...(approvalCondition\n      ? {\n          needsApproval(input: z.output<I>, ctx: CommandContext) {\n            return approvalCondition.call(definition, input, ctx)\n          },\n        }\n      : {}),\n    scopes: Object.freeze([...(d.scopes ?? [])]),\n    examples: Object.freeze([...(d.examples ?? [])]),\n    positional: Object.freeze([...(d.positional ?? [])]),\n    aliases: Object.freeze([...(d.aliases ?? [])]),\n    ...(task ? { task } : {}),\n    ...(audit ? { audit } : {}),\n    ...(expose ? { expose } : {}),\n    ...(authorize\n      ? {\n          authorize(input: z.output<I>, ctx: CommandContext) {\n            return authorize.call(definition, input, ctx)\n          },\n        }\n      : {}),\n    execute(input: z.output<I>, ctx: CommandContext) {\n      return execute.call(definition, input, ctx)\n    },\n  })\n}\n\n/** task: true | { ttlMs } → TaskOptions. false · undefined = 없음, 그 외 = TypeError */\nfunction taskOptions(value: unknown): TaskOptions | undefined {\n  if (value === undefined || value === false) return undefined\n  if (value === true) return Object.freeze({ ttlMs: DEFAULT_TASK_TTL_MS })\n  const ttlMs = (value as { ttlMs?: unknown } | null)?.ttlMs\n  if (typeof value !== \"object\" || !Number.isSafeInteger(ttlMs) || (ttlMs as number) <= 0) {\n    throw new TypeError(\"defineCommand: task must be true or { ttlMs: <positive integer> }\")\n  }\n  return Object.freeze({ ttlMs: ttlMs as number })\n}\n\nexport function isCommand(value: unknown): value is Command {\n  return typeof value === \"object\" && value !== null && (value as Record<symbol, unknown>)[COMMAND] === true\n}\n\nfunction isObjectSchema(value: unknown): value is InputSchema {\n  const def = (value as { _zod?: { def?: { type?: unknown } } } | undefined)?._zod?.def\n  return def?.type === \"object\" && typeof (value as { safeParseAsync?: unknown }).safeParseAsync === \"function\"\n}\n"]}

package/dist/config.d.ts

@@ -1,7 +1,10 @@
+import { type ApprovalConfig } from "./approval.ts";
+import { type AuditConfig } from "./audit.ts";
 import type { CliErrorFormatter } from "./cli/output.ts";
 import type { MextApp } from "./command.ts";
-import type { OAuthResourceOptions } from "./mcp/http.ts";
+import type { McpAuthRequest, OAuthResourceOptions } from "./mcp/http.ts";
 import { type Principal } from "./principal.ts";
+import { type RouteOptions } from "./route.ts";
 import { type MextState } from "./state.ts";
 /** mext.config.ts 의 default export */
 export interface MextConfig {
@@ -11,23 +14,38 @@ export interface MextConfig {
     resourcesDir?: string;
     /** MCP 프롬프트 폴더 (§12.3). 설정 파일 위치 (cwd) 기준. 기본 "prompts". 폴더 없음 = 프롬프트 없음 */
     promptsDir?: string;
+    /**
+     * 명령어 타입 생성 파일 (specs/client.md §4). true = ./mext.gen.ts, 문자열 = 그 경로 (프로젝트 루트 기준).
+     * 있으면 mext dev · mext build 가 생성한다. 없음 · false = 만들지 않는다 (mext types 는 설정 없이도 동작)
+     */
+    types?: boolean | string;
     /** ctx.app 팩토리. 실행 프로세스당 1회 */
     app?: () => MextApp | Promise<MextApp>;
-    /** HTTP 전용. 요청마다 Authorization 헤더로 주체 생성. 잘못된 토큰 = unauthenticated() throw */
-    auth?: (req: {
-        authorization: string | undefined;
-    }) => Principal | Promise<Principal>;
+    /**
+     * HTTP 전용. 요청마다 주체 생성. 잘못된 토큰 = unauthenticated() throw.
+     * req = { authorization, headers, surface, client } (McpAuthRequest). client 는 자가 신고 값 (판정 근거 아님).
+     * 반환 Principal 의 actor · surface 가 ctx.caller 의 행위자 · 논리 표면을 정한다 (spec §4)
+     */
+    auth?: (req: McpAuthRequest) => Principal | Promise<Principal>;
     /** MCP 노출 방식. 기본 "execute". command = 명령어별 도구 (§12.2) */
     tools?: "execute" | "split" | "command";
+    /**
+     * HTTP 서버. maxBodyBytes = POST /mcp 본문 상한 (기본 4 MiB). routes/ 는 상한 없음 (route 의 export maxBodyBytes = true 가 이 값을 쓴다)
+     */
     server?: {
         host?: string;
         port?: number;
         allowedOrigins?: string[];
+        allowedHosts?: string[];
+        maxBodyBytes?: number;
     };
     /** HTTP 전용. OAuth 보호 자원 메타데이터 (인가 서버 위치). mext login · MCP 클라이언트의 discovery */
     oauth?: OAuthResourceOptions;
-    /** 로컬 실행 (mext run · stdio) 주체. 기본 localPrincipal() */
-    localPrincipal?: Principal | (() => Principal | Promise<Principal>);
+    /**
+     * 로컬 실행 (mext run · 로컬 bin · stdio) 주체. 기본 localPrincipal().
+     * 함수 인자 surface = 어댑터 기본 표면 (mext run · 로컬 bin = "cli", stdio = "stdio"): 표면별로 actor 를 다르게 정할 수 있다
+     */
+    localPrincipal?: Principal | ((req: LocalPrincipalRequest) => Principal | Promise<Principal>);
     /** 고객 CLI (mext build → .mext/cli/). 없으면 고객 CLI 를 만들지 않는다 */
     cli?: CliConfig;
     /** MCP 서버 선언 (serverInfo.name · instructions · capabilities) · stdio 서버 발신 알림 (§6) */
@@ -44,6 +62,26 @@ export interface MextConfig {
     state?: MextState;
     /** HTTP 경로 폴더 (§12.4). 설정 파일 위치 (cwd) 기준. 기본 "routes". 폴더 없음 = route 없음 */
     routesDir?: string;
+    /**
+     * 모든 route 의 auth · origin · maxBodyBytes 기본값 (§12.4). route 모듈의 export 가 있으면 그 값 (false 포함).
+     * 없음 = route 마다 export 로 켠다 (기본 = 인증 · Origin 검사 · 본문 상한 없음)
+     */
+    routes?: RouteOptions;
+    /**
+     * 감사 (§11.1). sink = 변경 명령어 호출 1건마다 AuditEvent 1건 (모든 어댑터). 없으면 감사 없음.
+     * mext 는 저장소에 의존하지 않는다: 저장 · 조회는 sink 가 한다
+     */
+    audit?: AuditConfig;
+    /**
+     * 승인의 표면별 확인 방식 (§4 승인). 없으면 모든 표면 ask (ctx.ask 확인 = requiresConfirmation 의 기존 동작).
+     * surfaces: { web: "client" } = web 표면은 클라이언트가 확인받고 요청에 확인 표시를 싣는다
+     */
+    approval?: ApprovalConfig;
+}
+/** localPrincipal 함수의 인자 */
+export interface LocalPrincipalRequest {
+    /** 어댑터 기본 표면. mext run · 로컬 bin = "cli", stdio (mext dev --stdio · mext start --stdio · <bin> mcp serve) = "stdio" */
+    surface: "cli" | "stdio";
 }
 /** mext.config.ts 의 mcp (§6 서버 선언 · 서버 발신 알림) */
 export interface McpConfig {
@@ -124,20 +162,31 @@ export declare function resolveResourcesDir(cwd: string, config: MextConfig): st
 export declare function resolvePromptsDir(cwd: string, config: MextConfig): string;
 /** routes/ 절대 경로 */
 export declare function resolveRoutesDir(cwd: string, config: MextConfig): string;
-/** 로컬 실행 주체: config.localPrincipal (값 · 함수) 또는 localPrincipal() */
-export declare function resolveLocalPrincipal(config: MextConfig): Promise<Principal>;
+/**
+ * 로컬 실행 주체: config.localPrincipal (값 · 함수) 또는 localPrincipal().
+ * surface = 어댑터 기본 표면 (함수 인자). 함수 결과의 actor · surface 형식 오류 = TypeError
+ */
+export declare function resolveLocalPrincipal(config: MextConfig, surface?: LocalPrincipalRequest["surface"]): Promise<Principal>;
 /**
  * 서버 비밀: config.secret > MEXT_SECRET > undefined (프로세스별 임의 키).
  * 환경변수 값이 짧으면 TypeError (config.secret 은 설정 로드 시 검사)
  */
 export declare function resolveSecret(config: MextConfig, env?: Record<string, string | undefined>): string | undefined;
-/** 서버 선언 (모든 transport): config.mcp 의 name · instructions · capabilities + secret (requestStateKey) + state. onConnect 는 stdio 만 따로 */
+/** 서버 선언 (모든 transport): config.mcp 의 name · instructions · capabilities + secret (requestStateKey) + state + audit. onConnect 는 stdio 만 따로 */
 export declare function mcpDeclarations(config: MextConfig, env?: Record<string, string | undefined>): {
     name?: string;
     instructions?: string;
     capabilities?: McpCapabilities;
     requestStateKey?: string;
     state?: MextState;
+    audit?: AuditConfig;
+    approval?: ApprovalConfig;
+};
+/** HTTP 처리기의 server 옵션 (host · port 제외): allowedOrigins · allowedHosts · maxBodyBytes */
+export declare function httpServerOptions(config: MextConfig): {
+    allowedOrigins?: string[];
+    allowedHosts?: string[];
+    maxBodyBytes?: number;
 };
 /** stdio 옵션 = 선언 + onConnect */
 export declare function mcpStdioDeclarations(config: MextConfig, env?: Record<string, string | undefined>): ReturnType<typeof mcpDeclarations> & {