@obov/mext 0.0.0-stage → 0.1.0

package/dist/invoke.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.js","sourceRoot":"","sources":["../src/invoke.ts"],"names":[],"mappings":"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","sourcesContent":["import * as z from \"zod\"\nimport type { Ask, AskRequest, CommandContext, InputSchema, MextApp, ProgressUpdate } from \"./command.ts\"\nimport { inputDeclined, MextError, type ArgumentIssue } from \"./errors.ts\"\nimport { observeCommand, reportCommandError, type Instrumentation, type Transport } from \"./instrumentation.ts\"\nimport { findCommand } from \"./lookup.ts\"\nimport { hasScope, type Principal } from \"./principal.ts\"\nimport { loadCommand, type JsonSchema, type RegisteredCommand, type Registry } from \"./registry.ts\"\n\n/** 어댑터가 주입하는 ctx.ask 구현. command = 정식 ID */\nexport type AskHandler = (request: AskHandlerRequest) => Promise<unknown>\n\nexport type AskHandlerRequest =\n  | { command: string; kind: \"confirm\"; message: string }\n  | { command: string; kind: \"input\"; message: string; schema: InputSchema; requestedSchema: JsonSchema }\n\nexport interface InvokeOptions {\n  principal: Principal\n  /** 기본 = abort 되지 않는 signal */\n  signal?: AbortSignal\n  /** 기본 = 무시 */\n  progress?: (update: ProgressUpdate) => void\n  /** 기본 = ctx.ask 호출 시 INPUT_UNAVAILABLE */\n  ask?: AskHandler\n  app?: MextApp\n  /** readOnly 명령어만 허용 (split 의 query 도구). 그 외 = PERMISSION_DENIED */\n  readOnly?: boolean\n  /** loadInstrumentation 결과. onCommandError · mext.command span. 기본 = 없음 */\n  instrumentation?: Instrumentation\n  /** 실행 어댑터 (onCommandError · span 속성). 기본 \"local\" */\n  transport?: Transport\n  /** W3C trace context carrier (MCP params._meta 의 traceparent · tracestate). span 의 부모 */\n  traceContext?: Record<string, unknown>\n}\n\nexport interface InvokeResult {\n  /** 정식 ID (별칭으로 호출해도) */\n  command: string\n  value: unknown\n}\n\n/**\n * 어댑터 공통 실행기: ID 해석 (별칭 포함) → 권한 → (lazy 면 모듈 import) → Zod safeParse 1회 → 확인 (requiresConfirmation) → execute.\n * 실패는 MextError (UNKNOWN_COMMAND · PERMISSION_DENIED · INVALID_ARGUMENT · INPUT_UNAVAILABLE · INPUT_DECLINED).\n * 핸들러 예외는 그대로 전파 (instrumentation 있으면 onCommandError 보고 후).\n * instrumentation.otel 있으면 findCommand 뒤 전체를 `mext.command <id>` span 으로 감싼다.\n */\nexport async function invoke(\n  registry: Registry,\n  id: string,\n  rawInput: unknown,\n  options: InvokeOptions,\n): Promise<InvokeResult> {\n  const entry = findCommand(registry, id)\n  return observeCommand(entry.id, options, () => options.signal, async () => {\n    authorize(entry, options.principal, { readOnly: options.readOnly })\n    // lazy Registry (mext start) = 여기서 명령어 모듈 import. 권한 · ID 오류는 import 없이\n    const command = await loadCommand(entry)\n    const input = await parseInput(entry, rawInput)\n    const ctx = createContext(entry, options)\n    ctx.signal.throwIfAborted()\n    if (entry.command.requiresConfirmation) {\n      // 확인은 ctx.ask 경유 (CLI = 프롬프트 · --yes, MCP = MRTR). ask 미주입 = INPUT_UNAVAILABLE\n      const confirmed = await ctx.ask({ kind: \"confirm\", message: confirmationMessage(entry, input) })\n      if (!confirmed) throw inputDeclined(entry.id, \"confirm\")\n      ctx.signal.throwIfAborted()\n    }\n    try {\n      const value = await command.execute(input, ctx)\n      return { command: entry.id, value }\n    } catch (error) {\n      await reportCommandError(error, entry.id, options, ctx.signal)\n      throw error\n    }\n  })\n}\n\n/** ID · 별칭 → 명령어. 없으면 UNKNOWN_COMMAND (suggested · usage). 구현 = lookup.ts (help · 고객 CLI 공용) */\nexport { findCommand }\n\n/**\n * 안전성 메타데이터를 주체에 대해 강제.\n * readOnly 전용 호출 = readOnly 명령어만 · anonymous = readOnly 명령어만 · command.scopes 전부 보유 (\"*\" = 전체).\n */\nexport function authorize(entry: RegisteredCommand, principal: Principal, options: { readOnly?: boolean } = {}): void {\n  const c = entry.command\n  const deny = (reason: \"anonymous\" | \"read_only\" | \"scope\", message: string): never =>\n    throwError(\n      new MextError(\"PERMISSION_DENIED\", message, {\n        command: entry.id,\n        reason,\n        required_scopes: [...c.scopes],\n        held_scopes: [...principal.scopes],\n      }),\n    )\n  if (options.readOnly && !c.readOnly) deny(\"read_only\", `${entry.id} is not read-only and cannot run here.`)\n  if (principal.kind === \"anonymous\" && !c.readOnly) {\n    deny(\"anonymous\", `${entry.id} is not read-only and requires an authenticated principal.`)\n  }\n  const missing = c.scopes.filter((s) => !hasScope(principal, s))\n  if (missing.length > 0) deny(\"scope\", `${entry.id} requires scopes: ${missing.join(\", \")}.`)\n}\n\n/** Zod safeParse 1회. 실패 = INVALID_ARGUMENT (missing_fields · issues · expected_schema · examples) */\nexport async function parseInput(entry: RegisteredCommand, rawInput: unknown): Promise<z.output<InputSchema>> {\n  const raw = rawInput === undefined ? {} : rawInput\n  const result = await (await loadCommand(entry)).input.safeParseAsync(raw)\n  if (result.success) return result.data\n  throw invalidArgument(entry.id, raw, result.error.issues, entry.inputSchema, [...entry.command.examples])\n}\n\n/** ctx 생성. ask · progress · signal 은 어댑터 주입 */\nexport function createContext(entry: RegisteredCommand, options: InvokeOptions): CommandContext {\n  const handler = options.ask\n  const ask = async (request: AskRequest): Promise<unknown> => {\n    if (!handler) {\n      throw new MextError(\"INPUT_UNAVAILABLE\", `${entry.id} requested input, but this environment cannot ask.`, {\n        command: entry.id,\n      })\n    }\n    if (request.kind === \"confirm\") {\n      return (await handler({ command: entry.id, kind: \"confirm\", message: request.message })) === true\n    }\n    const requestedSchema = z.toJSONSchema(request.schema, { target: \"draft-2020-12\", io: \"input\" }) as JsonSchema\n    const response = await handler({\n      command: entry.id,\n      kind: \"input\",\n      message: request.message,\n      schema: request.schema,\n      requestedSchema,\n    })\n    const parsed = await request.schema.safeParseAsync(response)\n    if (parsed.success) return parsed.data\n    throw invalidArgument(entry.id, response, parsed.error.issues, requestedSchema, [])\n  }\n  return {\n    principal: options.principal,\n    signal: options.signal ?? new AbortController().signal,\n    progress: options.progress ?? (() => {}),\n    ask: ask as Ask,\n    app: options.app ?? ({} as MextApp),\n  }\n}\n\n/** requiresConfirmation 확인 문구. 검증된 입력을 포함 (무엇을 승인하는지) */\nexport function confirmationMessage(entry: RegisteredCommand, input: unknown): string {\n  let args: string\n  try {\n    args = JSON.stringify(input) ?? \"{}\"\n  } catch {\n    args = \"{}\"\n  }\n  return `Run ${entry.id} with ${args}?${entry.command.destructive ? \" This command is destructive.\" : \"\"}`\n}\n\nfunction invalidArgument(\n  command: string,\n  raw: unknown,\n  zodIssues: readonly z.core.$ZodIssue[],\n  expectedSchema: JsonSchema,\n  examples: unknown[],\n): MextError<\"INVALID_ARGUMENT\"> {\n  const issues: ArgumentIssue[] = zodIssues.map((i) => ({\n    path: i.path.map(String).join(\".\"),\n    code: i.code,\n    message: i.message,\n  }))\n  const missing = new Set<string>()\n  for (const i of zodIssues) {\n    if (i.code === \"invalid_type\" && i.path.length > 0 && isAbsent(raw, i.path)) missing.add(i.path.map(String).join(\".\"))\n  }\n  const missing_fields = [...missing]\n  const summary =\n    missing_fields.length > 0\n      ? `missing required: ${missing_fields.join(\", \")}`\n      : issues.map((i) => (i.path ? `${i.path}: ${i.message}` : i.message)).join(\"; \")\n  return new MextError(\"INVALID_ARGUMENT\", `Invalid arguments for ${command}: ${summary}`, {\n    command,\n    missing_fields,\n    issues,\n    expected_schema: expectedSchema,\n    examples,\n  })\n}\n\n/** 원본 입력에 경로가 없는지 (값 undefined 포함) */\nfunction isAbsent(raw: unknown, path: readonly PropertyKey[]): boolean {\n  let cur: unknown = raw\n  for (const key of path) {\n    if (cur === null || typeof cur !== \"object\") return true\n    cur = (cur as Record<PropertyKey, unknown>)[key]\n    if (cur === undefined) return true\n  }\n  return false\n}\n\nfunction throwError(error: MextError): never {\n  throw error\n}\n"]}

package/dist/lookup.d.ts

@@ -0,0 +1,9 @@
+import { MextError } from "./errors.ts";
+import type { RegisteredCommand, Registry } from "./registry.ts";
+/**
+ * ID · 별칭 → 명령어. 없으면 UNKNOWN_COMMAND (suggested · usage).
+ * Zod · 실행 코드에 의존하지 않는다 (help 렌더러 · 고객 CLI 번들이 import)
+ */
+export declare function findCommand(registry: Registry, id: string): RegisteredCommand;
+/** UNKNOWN_COMMAND. candidates = [비교 이름, 정식 ID], usage = 존재하는 가장 가까운 상위 네임스페이스의 help */
+export declare function unknownCommand(id: string, candidates: Iterable<readonly [string, string]>, hasNamespace: (id: string) => boolean): MextError<"UNKNOWN_COMMAND">;

package/dist/lookup.js

@@ -0,0 +1,27 @@
+import { MextError } from "./errors.js";
+import { parentNamespace } from "./ids.js";
+import { closest } from "./suggest.js";
+/**
+ * ID · 별칭 → 명령어. 없으면 UNKNOWN_COMMAND (suggested · usage).
+ * Zod · 실행 코드에 의존하지 않는다 (help 렌더러 · 고객 CLI 번들이 import)
+ */
+export function findCommand(registry, id) {
+    const entry = registry.commands.get(id) ?? registry.commands.get(registry.aliases.get(id) ?? "");
+    if (entry)
+        return entry;
+    throw unknownCommand(id, [
+        ...[...registry.commands.keys()].map((c) => [c, c]),
+        ...[...registry.aliases].map(([alias, c]) => [alias, c]),
+    ], (ns) => registry.namespaces.has(ns));
+}
+/** UNKNOWN_COMMAND. candidates = [비교 이름, 정식 ID], usage = 존재하는 가장 가까운 상위 네임스페이스의 help */
+export function unknownCommand(id, candidates, hasNamespace) {
+    const suggested = closest(id, candidates);
+    let ns = id;
+    while (ns !== "" && !hasNamespace(ns))
+        ns = parentNamespace(ns);
+    const usage = ns === "" ? "help" : `help ${ns}`;
+    const hint = suggested.length > 0 ? ` Did you mean: ${suggested.join(", ")}?` : "";
+    return new MextError("UNKNOWN_COMMAND", `Unknown command "${id}".${hint}`, { command: id, suggested, usage });
+}
+//# sourceMappingURL=lookup.js.map

package/dist/lookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup.js","sourceRoot":"","sources":["../src/lookup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAE1C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,QAAkB,EAAE,EAAU;IACxD,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAA;IAChG,IAAI,KAAK;QAAE,OAAO,KAAK,CAAA;IACvB,MAAM,cAAc,CAClB,EAAE,EACF;QACE,GAAG,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAoB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACrE,GAAG,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAoB,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;KAC3E,EACD,CAAC,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CACpC,CAAA;AACH,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,cAAc,CAC5B,EAAU,EACV,UAA+C,EAC/C,YAAqC;IAErC,MAAM,SAAS,GAAG,OAAO,CAAC,EAAE,EAAE,UAAU,CAAC,CAAA;IACzC,IAAI,EAAE,GAAG,EAAE,CAAA;IACX,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;QAAE,EAAE,GAAG,eAAe,CAAC,EAAE,CAAC,CAAA;IAC/D,MAAM,KAAK,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAA;IAC/C,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,kBAAkB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;IAClF,OAAO,IAAI,SAAS,CAAC,iBAAiB,EAAE,oBAAoB,EAAE,KAAK,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAA;AAC/G,CAAC","sourcesContent":["import { MextError } from \"./errors.ts\"\nimport { parentNamespace } from \"./ids.ts\"\nimport type { RegisteredCommand, Registry } from \"./registry.ts\"\nimport { closest } from \"./suggest.ts\"\n\n/**\n * ID · 별칭 → 명령어. 없으면 UNKNOWN_COMMAND (suggested · usage).\n * Zod · 실행 코드에 의존하지 않는다 (help 렌더러 · 고객 CLI 번들이 import)\n */\nexport function findCommand(registry: Registry, id: string): RegisteredCommand {\n  const entry = registry.commands.get(id) ?? registry.commands.get(registry.aliases.get(id) ?? \"\")\n  if (entry) return entry\n  throw unknownCommand(\n    id,\n    [\n      ...[...registry.commands.keys()].map((c): [string, string] => [c, c]),\n      ...[...registry.aliases].map(([alias, c]): [string, string] => [alias, c]),\n    ],\n    (ns) => registry.namespaces.has(ns),\n  )\n}\n\n/** UNKNOWN_COMMAND. candidates = [비교 이름, 정식 ID], usage = 존재하는 가장 가까운 상위 네임스페이스의 help */\nexport function unknownCommand(\n  id: string,\n  candidates: Iterable<readonly [string, string]>,\n  hasNamespace: (id: string) => boolean,\n): MextError<\"UNKNOWN_COMMAND\"> {\n  const suggested = closest(id, candidates)\n  let ns = id\n  while (ns !== \"\" && !hasNamespace(ns)) ns = parentNamespace(ns)\n  const usage = ns === \"\" ? \"help\" : `help ${ns}`\n  const hint = suggested.length > 0 ? ` Did you mean: ${suggested.join(\", \")}?` : \"\"\n  return new MextError(\"UNKNOWN_COMMAND\", `Unknown command \"${id}\".${hint}`, { command: id, suggested, usage })\n}\n"]}

package/dist/manifest.d.ts

@@ -0,0 +1,68 @@
+import type { JsonSchema, RegisteredCommand, Registry } from "./registry.ts";
+export declare const MANIFEST_SCHEMA_VERSION = 1;
+export interface ManifestCommand {
+    id: string;
+    description: string;
+    /** 별칭 전체 ID */
+    aliases: string[];
+    /** commands/ 기준 상대 경로 (posix) */
+    file?: string;
+    readOnly: boolean;
+    destructive: boolean;
+    requiresConfirmation: boolean;
+    scopes: string[];
+    positional: string[];
+    examples: unknown[];
+    /** JSON Schema 2020-12 */
+    inputSchema: JsonSchema;
+    outputSchema?: JsonSchema;
+}
+export interface ManifestNamespace {
+    id: string;
+    /** _index.md 내용 */
+    description?: string;
+}
+export interface Manifest {
+    schemaVersion: typeof MANIFEST_SCHEMA_VERSION;
+    /** commands/_index.md 내용 */
+    description?: string;
+    /** 루트 제외, ID 순 */
+    namespaces: ManifestNamespace[];
+    /** ID 순 */
+    commands: ManifestCommand[];
+}
+/** 명령어 하나의 메타데이터 (manifest · help 공통) */
+export declare function describeCommand(entry: RegisteredCommand): ManifestCommand;
+export declare function buildManifest(registry: Registry): Manifest;
+/** 빌드 시 manifest 생성: commands/ 스캔 → Manifest (JSON 직렬화 가능) */
+export declare function generateManifest(dir: string): Promise<Manifest>;
+/** mext build 의 .mext/manifest.json 명령어: Manifest 명령어 + 번들 모듈 경로 */
+export interface BuildManifestCommand extends ManifestCommand {
+    /** .mext/ 기준 상대 경로 (posix). commands/users/get.ts → "commands/users/get.js". default export = defineCommand 결과 */
+    module: string;
+}
+/**
+ * .mext/manifest.json (mext build 산출, mext start · handler.js 가 읽는다).
+ * namespaces · description = Manifest 와 같음
+ */
+export interface BuildManifest extends Omit<Manifest, "commands"> {
+    /** 빌드한 @obov/mext 버전. 실행 시 설치된 버전과 다르면 시작 오류 */
+    mextVersion: string;
+    /** 빌드 식별자 (D3: mextVersion · manifestHash · 번들 코드의 sha256 앞 16자, 같은 입력 = 같은 값) */
+    buildId: string;
+    /** manifestHash(commands) */
+    manifestHash: string;
+    /** mext.config.ts 번들 (.mext/ 기준). 설정 파일이 없으면 생략 */
+    config?: string;
+    /** instrumentation.ts 번들 (.mext/ 기준). 없으면 생략 */
+    instrumentation?: string;
+    /** ID 순 */
+    commands: BuildManifestCommand[];
+}
+/**
+ * 명령어 계약의 지문: ID · 별칭 · positional · 입력 스키마 · 안전성 메타데이터 (readOnly · destructive ·
+ * requiresConfirmation · scopes) 의 정규화 JSON (키 정렬, ID 순) sha256 hex.
+ * 설명 · examples · outputSchema · 파일 경로는 제외 (클라이언트의 help 캐시 · 플래그 파싱에 영향 없음).
+ * 빌드 manifest · 서버 (_meta["dev.mext/manifestHash"]) · 클라이언트가 같은 함수로 계산한다
+ */
+export declare function manifestHash(commands: readonly ManifestCommand[]): string;

package/dist/manifest.js

@@ -0,0 +1,77 @@
+import { createHash } from "node:crypto";
+import { loadRegistry } from "./scan.js";
+export const MANIFEST_SCHEMA_VERSION = 1;
+/** 명령어 하나의 메타데이터 (manifest · help 공통) */
+export function describeCommand(entry) {
+    const c = entry.command;
+    const out = {
+        id: entry.id,
+        description: c.description,
+        aliases: [...entry.aliases],
+        readOnly: c.readOnly,
+        destructive: c.destructive,
+        requiresConfirmation: c.requiresConfirmation,
+        scopes: [...c.scopes],
+        positional: [...c.positional],
+        examples: [...c.examples],
+        inputSchema: entry.inputSchema,
+    };
+    if (entry.file !== undefined)
+        out.file = entry.file;
+    if (entry.outputSchema !== undefined)
+        out.outputSchema = entry.outputSchema;
+    return out;
+}
+export function buildManifest(registry) {
+    const manifest = {
+        schemaVersion: MANIFEST_SCHEMA_VERSION,
+        namespaces: [],
+        commands: [...registry.commands.values()].map(describeCommand),
+    };
+    for (const ns of registry.namespaces.values()) {
+        if (ns.id === "") {
+            if (ns.description !== undefined)
+                manifest.description = ns.description;
+            continue;
+        }
+        manifest.namespaces.push(ns.description === undefined ? { id: ns.id } : { id: ns.id, description: ns.description });
+    }
+    return manifest;
+}
+/** 빌드 시 manifest 생성: commands/ 스캔 → Manifest (JSON 직렬화 가능) */
+export async function generateManifest(dir) {
+    return buildManifest(await loadRegistry(dir));
+}
+/**
+ * 명령어 계약의 지문: ID · 별칭 · positional · 입력 스키마 · 안전성 메타데이터 (readOnly · destructive ·
+ * requiresConfirmation · scopes) 의 정규화 JSON (키 정렬, ID 순) sha256 hex.
+ * 설명 · examples · outputSchema · 파일 경로는 제외 (클라이언트의 help 캐시 · 플래그 파싱에 영향 없음).
+ * 빌드 manifest · 서버 (_meta["dev.mext/manifestHash"]) · 클라이언트가 같은 함수로 계산한다
+ */
+export function manifestHash(commands) {
+    const normalized = [...commands]
+        .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+        .map((c) => ({
+        id: c.id,
+        aliases: [...c.aliases].sort(),
+        positional: c.positional,
+        inputSchema: c.inputSchema,
+        readOnly: c.readOnly,
+        destructive: c.destructive,
+        requiresConfirmation: c.requiresConfirmation,
+        scopes: [...c.scopes].sort(),
+    }));
+    return createHash("sha256").update(canonicalJson(normalized)).digest("hex");
+}
+/** 키 정렬 JSON (배열 순서 유지, undefined 속성 생략) */
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map((v) => (v === undefined ? "null" : canonicalJson(v))).join(",")}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
+}
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\"\nimport type { JsonSchema, RegisteredCommand, Registry } from \"./registry.ts\"\nimport { loadRegistry } from \"./scan.ts\"\n\nexport const MANIFEST_SCHEMA_VERSION = 1\n\nexport interface ManifestCommand {\n  id: string\n  description: string\n  /** 별칭 전체 ID */\n  aliases: string[]\n  /** commands/ 기준 상대 경로 (posix) */\n  file?: string\n  readOnly: boolean\n  destructive: boolean\n  requiresConfirmation: boolean\n  scopes: string[]\n  positional: string[]\n  examples: unknown[]\n  /** JSON Schema 2020-12 */\n  inputSchema: JsonSchema\n  outputSchema?: JsonSchema\n}\n\nexport interface ManifestNamespace {\n  id: string\n  /** _index.md 내용 */\n  description?: string\n}\n\nexport interface Manifest {\n  schemaVersion: typeof MANIFEST_SCHEMA_VERSION\n  /** commands/_index.md 내용 */\n  description?: string\n  /** 루트 제외, ID 순 */\n  namespaces: ManifestNamespace[]\n  /** ID 순 */\n  commands: ManifestCommand[]\n}\n\n/** 명령어 하나의 메타데이터 (manifest · help 공통) */\nexport function describeCommand(entry: RegisteredCommand): ManifestCommand {\n  const c = entry.command\n  const out: ManifestCommand = {\n    id: entry.id,\n    description: c.description,\n    aliases: [...entry.aliases],\n    readOnly: c.readOnly,\n    destructive: c.destructive,\n    requiresConfirmation: c.requiresConfirmation,\n    scopes: [...c.scopes],\n    positional: [...c.positional],\n    examples: [...c.examples],\n    inputSchema: entry.inputSchema,\n  }\n  if (entry.file !== undefined) out.file = entry.file\n  if (entry.outputSchema !== undefined) out.outputSchema = entry.outputSchema\n  return out\n}\n\nexport function buildManifest(registry: Registry): Manifest {\n  const manifest: Manifest = {\n    schemaVersion: MANIFEST_SCHEMA_VERSION,\n    namespaces: [],\n    commands: [...registry.commands.values()].map(describeCommand),\n  }\n  for (const ns of registry.namespaces.values()) {\n    if (ns.id === \"\") {\n      if (ns.description !== undefined) manifest.description = ns.description\n      continue\n    }\n    manifest.namespaces.push(ns.description === undefined ? { id: ns.id } : { id: ns.id, description: ns.description })\n  }\n  return manifest\n}\n\n/** 빌드 시 manifest 생성: commands/ 스캔 → Manifest (JSON 직렬화 가능) */\nexport async function generateManifest(dir: string): Promise<Manifest> {\n  return buildManifest(await loadRegistry(dir))\n}\n\n/** mext build 의 .mext/manifest.json 명령어: Manifest 명령어 + 번들 모듈 경로 */\nexport interface BuildManifestCommand extends ManifestCommand {\n  /** .mext/ 기준 상대 경로 (posix). commands/users/get.ts → \"commands/users/get.js\". default export = defineCommand 결과 */\n  module: string\n}\n\n/**\n * .mext/manifest.json (mext build 산출, mext start · handler.js 가 읽는다).\n * namespaces · description = Manifest 와 같음\n */\nexport interface BuildManifest extends Omit<Manifest, \"commands\"> {\n  /** 빌드한 @obov/mext 버전. 실행 시 설치된 버전과 다르면 시작 오류 */\n  mextVersion: string\n  /** 빌드 식별자 (D3: mextVersion · manifestHash · 번들 코드의 sha256 앞 16자, 같은 입력 = 같은 값) */\n  buildId: string\n  /** manifestHash(commands) */\n  manifestHash: string\n  /** mext.config.ts 번들 (.mext/ 기준). 설정 파일이 없으면 생략 */\n  config?: string\n  /** instrumentation.ts 번들 (.mext/ 기준). 없으면 생략 */\n  instrumentation?: string\n  /** ID 순 */\n  commands: BuildManifestCommand[]\n}\n\n/**\n * 명령어 계약의 지문: ID · 별칭 · positional · 입력 스키마 · 안전성 메타데이터 (readOnly · destructive ·\n * requiresConfirmation · scopes) 의 정규화 JSON (키 정렬, ID 순) sha256 hex.\n * 설명 · examples · outputSchema · 파일 경로는 제외 (클라이언트의 help 캐시 · 플래그 파싱에 영향 없음).\n * 빌드 manifest · 서버 (_meta[\"dev.mext/manifestHash\"]) · 클라이언트가 같은 함수로 계산한다\n */\nexport function manifestHash(commands: readonly ManifestCommand[]): string {\n  const normalized = [...commands]\n    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))\n    .map((c) => ({\n      id: c.id,\n      aliases: [...c.aliases].sort(),\n      positional: c.positional,\n      inputSchema: c.inputSchema,\n      readOnly: c.readOnly,\n      destructive: c.destructive,\n      requiresConfirmation: c.requiresConfirmation,\n      scopes: [...c.scopes].sort(),\n    }))\n  return createHash(\"sha256\").update(canonicalJson(normalized)).digest(\"hex\")\n}\n\n/** 키 정렬 JSON (배열 순서 유지, undefined 속성 생략) */\nfunction canonicalJson(value: unknown): string {\n  if (value === null || typeof value !== \"object\") return JSON.stringify(value) ?? \"null\"\n  if (Array.isArray(value)) return `[${value.map((v) => (v === undefined ? \"null\" : canonicalJson(v))).join(\",\")}]`\n  const entries = Object.entries(value as Record<string, unknown>)\n    .filter(([, v]) => v !== undefined)\n    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))\n  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(\",\")}}`\n}\n"]}

package/dist/mcp/constants.d.ts

@@ -0,0 +1,9 @@
+/** MCP 엔드포인트 경로 (POST 만) */
+export declare const MCP_PATH = "/mcp";
+export declare const DEFAULT_HOST = "127.0.0.1";
+export declare const DEFAULT_PORT = 3100;
+/**
+ * server/discover · tools/call 결과 _meta 의 현재 manifestHash 키 (스키마 drift 감지, §5).
+ * 고객 CLI 번들도 import (의존 없는 모듈)
+ */
+export declare const MANIFEST_HASH_META_KEY = "dev.mext/manifestHash";

package/dist/mcp/constants.js

@@ -0,0 +1,10 @@
+/** MCP 엔드포인트 경로 (POST 만) */
+export const MCP_PATH = "/mcp";
+export const DEFAULT_HOST = "127.0.0.1";
+export const DEFAULT_PORT = 3100;
+/**
+ * server/discover · tools/call 결과 _meta 의 현재 manifestHash 키 (스키마 drift 감지, §5).
+ * 고객 CLI 번들도 import (의존 없는 모듈)
+ */
+export const MANIFEST_HASH_META_KEY = "dev.mext/manifestHash";
+//# sourceMappingURL=constants.js.map

package/dist/mcp/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/mcp/constants.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAA;AAC9B,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAA;AACvC,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAA;AAEhC;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,uBAAuB,CAAA","sourcesContent":["/** MCP 엔드포인트 경로 (POST 만) */\nexport const MCP_PATH = \"/mcp\"\nexport const DEFAULT_HOST = \"127.0.0.1\"\nexport const DEFAULT_PORT = 3100\n\n/**\n * server/discover · tools/call 결과 _meta 의 현재 manifestHash 키 (스키마 drift 감지, §5).\n * 고객 CLI 번들도 import (의존 없는 모듈)\n */\nexport const MANIFEST_HASH_META_KEY = \"dev.mext/manifestHash\"\n"]}

package/dist/mcp/dispatch.d.ts

@@ -0,0 +1,66 @@
+import { type InvokeOptions } from "../invoke.ts";
+import type { JsonSchema, Registry } from "../registry.ts";
+import { type InputRequiredResult, type InputRound, type RequestStateSigner } from "./mrtr.ts";
+/**
+ * MCP 어댑터의 transport 무관 부분: dispatcher 도구 정의 · tools/call 실행 · help · 오류 → 결과 변환.
+ * SDK · HTTP 에 의존하지 않는다 (HTTP · stdio 가 공유).
+ */
+/** execute = 도구 1개 (기본), split = query (readOnly · help) + mutate (그 외) */
+export type ToolExposure = "execute" | "split";
+export type DispatcherToolName = "execute" | "query" | "mutate";
+/** MCP ToolAnnotations 중 mext 가 쓰는 항목 */
+export interface DispatcherAnnotations {
+    title?: string;
+    readOnlyHint: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+export interface DispatcherTool {
+    name: DispatcherToolName;
+    description: string;
+    /** JSON Schema 2020-12. command 에 x-mcp-header: "Command" */
+    inputSchema: JsonSchema;
+    annotations: DispatcherAnnotations;
+    /** readOnly 명령어만 실행 (split 의 query). 그 외 = PERMISSION_DENIED */
+    readOnly: boolean;
+}
+export interface TextContent {
+    type: "text";
+    text: string;
+}
+/** MCP CallToolResult 와 같은 형태 (SDK 타입 비의존) */
+export interface ToolCallResult {
+    content: TextContent[];
+    /** 성공 = 핸들러 반환값 (undefined 는 null), 오류 = { error: MextError.toJSON() } */
+    structuredContent: unknown;
+    isError?: true;
+}
+/** 핸들러 예외 (MextError 외) 의 결과 code. CLI --json 과 같음 */
+export declare const EXECUTION_ERROR = "EXECUTION_ERROR";
+/** 노출 방식별 dispatcher 도구 (정렬 순서 고정: execute · query, mutate) */
+export declare function dispatcherTools(registry: Registry, exposure?: ToolExposure): DispatcherTool[];
+export declare function findDispatcherTool(tools: readonly DispatcherTool[], name: string): DispatcherTool | undefined;
+export interface DispatchOptions extends Omit<InvokeOptions, "readOnly"> {
+    /** help 의 tool 표시용. dispatcherTools 결과 */
+    tools?: readonly DispatcherTool[];
+    /**
+     * MRTR (MCP 2026-07-28). 지정하면 ctx.ask = InputRequiredResult 반환 · 재시도의 inputResponses 로 resolve
+     * (ask 옵션 무시). requiresConfirmation 확인도 이 경로
+     */
+    input?: InputRound & {
+        signer: RequestStateSigner;
+    };
+}
+/** tools/call 결과: 완료 (CallToolResult 형태) 또는 입력 요청 (InputRequiredResult) */
+export type DispatchResult = ToolCallResult | InputRequiredResult;
+/**
+ * dispatcher 도구 호출: { command, args } → help 또는 invoke.
+ * MextError · 핸들러 예외는 isError 결과로 (throw 하지 않음). 인증 (UNAUTHENTICATED → 401) 은 transport 몫.
+ * options.input 이 있으면 ctx.ask 가 InputRequiredResult 를 돌려준다 (mrtr.ts).
+ */
+export declare function callDispatcher(registry: Registry, tool: DispatcherTool, rawArguments: unknown, options: DispatchOptions): Promise<DispatchResult>;
+/** 오류 → isError 결과. MextError = toJSON, 그 외 = EXECUTION_ERROR */
+export declare function errorResult(error: unknown): ToolCallResult;
+/** dispatcher 도구 inputSchema. command 를 Mcp-Param-Command 헤더로 복사 (SEP-2243) */
+export declare function dispatcherInputSchema(): JsonSchema;

package/dist/mcp/dispatch.js

@@ -0,0 +1,249 @@
+import { isMextError, MextError } from "../errors.js";
+import { invoke } from "../invoke.js";
+import { formatHelp, help, HELP_COMMAND } from "./help.js";
+import { createAskSession, hasPending, inputRequiredResult, } from "./mrtr.js";
+/** 핸들러 예외 (MextError 외) 의 결과 code. CLI --json 과 같음 */
+export const EXECUTION_ERROR = "EXECUTION_ERROR";
+/** 도구 설명에 나열할 명령어 수 상한. 넘으면 help 안내만 */
+const DESCRIPTION_COMMAND_LIMIT = 50;
+/** 노출 방식별 dispatcher 도구 (정렬 순서 고정: execute · query, mutate) */
+export function dispatcherTools(registry, exposure = "execute") {
+    const all = [...registry.commands.values()];
+    if (exposure === "split") {
+        const reads = all.filter((e) => e.command.readOnly);
+        const writes = all.filter((e) => !e.command.readOnly);
+        return [
+            {
+                name: "query",
+                description: describeTool("query", "Run a read-only command.", reads, 'Commands that are not read-only are rejected here; call them with the "mutate" tool.'),
+                inputSchema: dispatcherInputSchema(),
+                annotations: { title: "Query", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+                readOnly: true,
+            },
+            {
+                name: "mutate",
+                description: describeTool("mutate", "Run a command that changes state.", writes),
+                inputSchema: dispatcherInputSchema(),
+                annotations: { title: "Mutate", readOnlyHint: false, destructiveHint: true },
+                readOnly: false,
+            },
+        ];
+    }
+    const readOnly = all.every((e) => e.command.readOnly);
+    return [
+        {
+            name: "execute",
+            description: describeTool("execute", "Run a command.", all),
+            inputSchema: dispatcherInputSchema(),
+            // 단일 dispatcher 는 최악값 (researches/others.md 9)
+            annotations: readOnly
+                ? { title: "Execute", readOnlyHint: true, destructiveHint: false }
+                : { title: "Execute", readOnlyHint: false, destructiveHint: all.some((e) => e.command.destructive) },
+            readOnly: false,
+        },
+    ];
+}
+export function findDispatcherTool(tools, name) {
+    return tools.find((t) => t.name === name);
+}
+/**
+ * dispatcher 도구 호출: { command, args } → help 또는 invoke.
+ * MextError · 핸들러 예외는 isError 결과로 (throw 하지 않음). 인증 (UNAUTHENTICATED → 401) 은 transport 몫.
+ * options.input 이 있으면 ctx.ask 가 InputRequiredResult 를 돌려준다 (mrtr.ts).
+ */
+export async function callDispatcher(registry, tool, rawArguments, options) {
+    try {
+        const { command, args } = parseDispatcherArguments(tool, rawArguments);
+        if (command === HELP_COMMAND) {
+            const target = args?.target;
+            if (target !== undefined && typeof target !== "string") {
+                throw dispatcherArgumentError(tool, "help", "args.target must be a string", [], {
+                    path: "args.target",
+                    code: "invalid_type",
+                    message: "expected string",
+                });
+            }
+            const toolFor = splitToolFor(options.tools);
+            const value = help(registry, target, toolFor ? { toolFor } : {});
+            return { content: [{ type: "text", text: formatHelp(value, tool.name) }], structuredContent: value };
+        }
+        const { input, tools: _tools, ...invokeOptions } = options;
+        const result = input
+            ? await invokeRound(registry, tool, command, args, invokeOptions, input)
+            : await invoke(registry, command, args, { ...invokeOptions, readOnly: tool.readOnly });
+        if ("resultType" in result)
+            return result;
+        const value = result.value === undefined ? null : result.value;
+        return { content: [{ type: "text", text: stringify(value) }], structuredContent: value };
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+}
+/**
+ * MRTR 한 라운드: requestState 검증 → ask 세션으로 invoke. 답 없는 ask 가 있으면 (핸들러가 오류를 삼켜도)
+ * 결과를 버리고 InputRequiredResult. elicitation 미선언 클라이언트 = ask 미주입 (INPUT_UNAVAILABLE)
+ */
+async function invokeRound(registry, tool, command, args, options, input) {
+    const { ask: _ask, ...rest } = options;
+    if (!input.elicitation)
+        return invoke(registry, command, args, { ...rest, readOnly: tool.readOnly });
+    const binding = {
+        principal: `${options.principal.kind}:${options.principal.id}`,
+        tool: tool.name,
+        command,
+        args: args ?? {},
+    };
+    let answers = { ...input.inputResponses };
+    if (input.requestState !== undefined) {
+        const prior = input.signer.verify(input.requestState, binding);
+        if (!prior)
+            throw invalidRequestState(tool, command);
+        answers = { ...answers, ...prior };
+    }
+    const session = createAskSession(answers);
+    const signal = options.signal ? AbortSignal.any([options.signal, session.signal]) : session.signal;
+    try {
+        const result = await invoke(registry, command, args, { ...rest, signal, ask: session.ask, readOnly: tool.readOnly });
+        return hasPending(session) ? inputRequiredResult(session, input.signer, binding) : result;
+    }
+    catch (error) {
+        if (hasPending(session))
+            return inputRequiredResult(session, input.signer, binding);
+        throw error;
+    }
+}
+/** 서명 · 만료 · 바인딩 검증 실패한 requestState. 처음부터 다시 호출하도록 안내 */
+function invalidRequestState(tool, command) {
+    return new MextError("INVALID_ARGUMENT", `Invalid arguments for ${command}: requestState is invalid or expired. Call ${tool.name} again without requestState and inputResponses.`, {
+        command,
+        missing_fields: [],
+        issues: [
+            {
+                path: "requestState",
+                code: "invalid_request_state",
+                message: "requestState failed verification (tampered, expired, or for a different call or server key)",
+            },
+        ],
+        expected_schema: tool.inputSchema,
+        examples: [],
+    });
+}
+/** 오류 → isError 결과. MextError = toJSON, 그 외 = EXECUTION_ERROR */
+export function errorResult(error) {
+    const body = isMextError(error)
+        ? error.toJSON()
+        : { code: EXECUTION_ERROR, message: error instanceof Error ? error.message : String(error) };
+    return {
+        content: [{ type: "text", text: `${body.code}: ${body.message}\n${stringify(body)}` }],
+        structuredContent: { error: body },
+        isError: true,
+    };
+}
+/** dispatcher 도구 inputSchema. command 를 Mcp-Param-Command 헤더로 복사 (SEP-2243) */
+export function dispatcherInputSchema() {
+    return {
+        type: "object",
+        properties: {
+            command: {
+                type: "string",
+                description: 'Command ID (e.g. "users.get"), or "help" to list namespaces and commands.',
+                "x-mcp-header": "Command",
+            },
+            args: {
+                type: "object",
+                description: 'Command input. For "help": { "target": "<namespace or command ID>" }.',
+                additionalProperties: true,
+            },
+        },
+        required: ["command"],
+        additionalProperties: false,
+    };
+}
+function parseDispatcherArguments(tool, raw) {
+    const input = raw === undefined ? {} : raw;
+    if (input === null || typeof input !== "object" || Array.isArray(input)) {
+        throw dispatcherArgumentError(tool, tool.name, "arguments must be an object", [], {
+            path: "",
+            code: "invalid_type",
+            message: "expected object",
+        });
+    }
+    const { command, args, ...rest } = input;
+    if (command === undefined) {
+        throw dispatcherArgumentError(tool, tool.name, "missing required: command", ["command"], {
+            path: "command",
+            code: "invalid_type",
+            message: "expected string, received undefined",
+        });
+    }
+    if (typeof command !== "string") {
+        throw dispatcherArgumentError(tool, tool.name, "command must be a string", [], {
+            path: "command",
+            code: "invalid_type",
+            message: "expected string",
+        });
+    }
+    const unknownKeys = Object.keys(rest);
+    if (unknownKeys.length > 0) {
+        throw dispatcherArgumentError(tool, tool.name, `unrecognized keys: ${unknownKeys.join(", ")}`, [], {
+            path: "",
+            code: "unrecognized_keys",
+            message: `Unrecognized keys: ${unknownKeys.join(", ")}. Put command input under "args".`,
+        });
+    }
+    if (args !== undefined && (args === null || typeof args !== "object" || Array.isArray(args))) {
+        throw dispatcherArgumentError(tool, command, "args must be an object", [], {
+            path: "args",
+            code: "invalid_type",
+            message: "expected object",
+        });
+    }
+    return { command, args };
+}
+function dispatcherArgumentError(tool, command, summary, missing, issue) {
+    return new MextError("INVALID_ARGUMENT", `Invalid arguments for ${command}: ${summary}`, {
+        command,
+        missing_fields: missing,
+        issues: [issue],
+        expected_schema: tool.inputSchema,
+        examples: [{ command: HELP_COMMAND }],
+    });
+}
+function splitToolFor(tools) {
+    if (!tools || tools.length < 2)
+        return undefined;
+    const query = tools.find((t) => t.readOnly)?.name;
+    const mutate = tools.find((t) => !t.readOnly)?.name;
+    if (query === undefined || mutate === undefined)
+        return undefined;
+    return (e) => (e.command.readOnly ? query : mutate);
+}
+function describeTool(name, lead, commands, note) {
+    const lines = [
+        lead,
+        `Arguments: { "command": "<command ID>", "args": { ...input } }. ` +
+            `Call ${name}({ "command": "help" }) to list namespaces and commands, ` +
+            `${name}({ "command": "help", "args": { "target": "<namespace or command ID>" } }) for input schemas and examples.`,
+    ];
+    if (note)
+        lines.push(note);
+    if (commands.length > 0 && commands.length <= DESCRIPTION_COMMAND_LIMIT) {
+        lines.push("", "Commands:");
+        for (const e of commands)
+            lines.push(`- ${e.id}: ${firstLine(e.command.description)}`);
+    }
+    return lines.join("\n");
+}
+function firstLine(text) {
+    return text.split("\n", 1)[0].trim();
+}
+function stringify(value) {
+    try {
+        return JSON.stringify(value, null, 2) ?? "null";
+    }
+    catch {
+        return String(value);
+    }
+}
+//# sourceMappingURL=dispatch.js.map