@obov/mext 0.0.0-stage → 0.1.0

package/dist/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../src/ids.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,MAAM,CAAC,MAAM,eAAe,GAAG,iCAAiC,CAAA;AAEhE,gDAAgD;AAChD,MAAM,CAAC,MAAM,sBAAsB,GAAsB,CAAC,MAAM,CAAC,CAAA;AAEjE,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,OAAO,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;AACpC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,EAAU;IACxC,MAAM,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;IAC7B,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;AACvC,CAAC","sourcesContent":["/** 경로 세그먼트 · 별칭 규칙: kebab-case 만 */\nexport const SEGMENT_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/\n\n/** 루트에 둘 수 없는 세그먼트 (help 탐색 · CLI help 와 충돌) */\nexport const RESERVED_ROOT_SEGMENTS: readonly string[] = [\"help\"]\n\nexport function isSegment(value: string): boolean {\n  return SEGMENT_PATTERN.test(value)\n}\n\nexport function parentNamespace(id: string): string {\n  const i = id.lastIndexOf(\".\")\n  return i === -1 ? \"\" : id.slice(0, i)\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+export { VERSION } from "./version.ts";
+export { defineCommand, isCommand } from "./command.ts";
+export type { Ask, AskRequest, Command, CommandContext, CommandDefinition, ConfirmRequest, InputRequest, InputSchema, MextApp, ProgressUpdate, } from "./command.ts";
+export { ANONYMOUS, hasScope, localPrincipal } from "./principal.ts";
+export type { Principal } from "./principal.ts";
+export { inputDeclined, isMextError, MextBuildError, MextError, unauthenticated } from "./errors.ts";
+export type { ArgumentIssue, BuildIssue, BuildIssueCode, MextErrorCode, MextErrorDetails } from "./errors.ts";
+export { authorize, confirmationMessage, createContext, findCommand, invoke, parseInput } from "./invoke.ts";
+export type { AskHandler, AskHandlerRequest, InvokeOptions, InvokeResult } from "./invoke.ts";
+export { findInstrumentation, INSTRUMENTATION_FILE, loadInstrumentation, loadProjectInstrumentation, } from "./instrumentation.ts";
+export type { CommandErrorInfo, Instrumentation, InstrumentationModule, LoadInstrumentationOptions, OtelApi, Transport, } from "./instrumentation.ts";
+export { collectRegistry, createLazyRegistry, createRegistry, loadCommand, resolveCommand } from "./registry.ts";
+export type { JsonSchema, LazyCommandInput, NamespaceInfo, RegisteredCommand, Registry, RegistryCommandInput, RegistryInput, RegistryNamespaceInput, } from "./registry.ts";
+export { collectCommands, loadRegistry, scanCommands, walkCommands } from "./scan.ts";
+export type { ScannedFile, ScanResult } from "./scan.ts";
+export { buildManifest, describeCommand, generateManifest, MANIFEST_SCHEMA_VERSION, manifestHash } from "./manifest.ts";
+export type { BuildManifest, BuildManifestCommand, Manifest, ManifestCommand, ManifestNamespace } from "./manifest.ts";
+export { BUILD_DIR, BUILD_MANIFEST_FILE, buildProject, HANDLER_JS, RolldownUnavailableError, SERVER_JS, START_ENTRY } from "./build.ts";
+export type { BuildOptions, BuildResult, BuildWarning, RolldownModule, RolldownOutputItem } from "./build.ts";
+export { formatBuildSummary, runBuild } from "./cli/build.ts";
+export { mextVersion } from "./version.ts";
+export * from "./mcp/index.ts";
+export { CLI_BUILTIN_COMMANDS, CONFIG_FILE, createApp, defineConfig, loadConfig, resolveCommandsDir, resolveLocalPrincipal } from "./config.ts";
+export type { CliConfig, MextConfig } from "./config.ts";
+export { buildCustomerCli, CLI_BIN_FILE, CLI_DIR, customerCliIssues } from "./build-cli.ts";
+export type { BuildCustomerCliOptions, CustomerCliBuild } from "./build-cli.ts";
+export { runCustomerCli } from "./client/main.ts";
+export type { CustomerCliConfig } from "./client/main.ts";
+export { clientManifest, manifestHelp } from "./client/manifest.ts";
+export type { ClientManifest, ClientManifestCommand } from "./client/manifest.ts";
+export { runRemote } from "./client/runner.ts";
+export type { HelpSource, RemoteRunOptions } from "./client/runner.ts";
+export { runCli, SUBCOMMANDS } from "./cli/main.ts";
+export type { CliSubcommand } from "./cli/main.ts";
+export type { CliIo, CliWriter } from "./cli/io.ts";
+export { analyzeInput, assertCliConvertible, cliBuildIssues, cliSpec, parseArgs, RESERVED_FLAGS, toKebab } from "./cli/args.ts";
+export type { CliField, CliSpec, FieldKind, ParseArgsOptions, ParsedArgs, Primitive, ScalarKind } from "./cli/args.ts";
+export { cliPath, formatInvocation, renderCommandHelp, renderHelp, renderNamespaceHelp, resolveHelpTarget, } from "./cli/help.ts";
+export type { HelpOptions, HelpTarget } from "./cli/help.ts";
+export { errorJson, exitCodeOf, formatError, formatJson, formatResult } from "./cli/output.ts";
+export { loginCommand, resolveServerUrl } from "./cli/login.ts";
+export type { AuthCommandOptions } from "./cli/login.ts";
+export { logoutCommand } from "./cli/logout.ts";
+export * from "./remote/index.ts";
+export { cliSpecFromJsonSchema, defineCliSpec } from "./cli/args.ts";

package/dist/index.js

@@ -0,0 +1,27 @@
+export { VERSION } from "./version.js";
+export { defineCommand, isCommand } from "./command.js";
+export { ANONYMOUS, hasScope, localPrincipal } from "./principal.js";
+export { inputDeclined, isMextError, MextBuildError, MextError, unauthenticated } from "./errors.js";
+export { authorize, confirmationMessage, createContext, findCommand, invoke, parseInput } from "./invoke.js";
+export { findInstrumentation, INSTRUMENTATION_FILE, loadInstrumentation, loadProjectInstrumentation, } from "./instrumentation.js";
+export { collectRegistry, createLazyRegistry, createRegistry, loadCommand, resolveCommand } from "./registry.js";
+export { collectCommands, loadRegistry, scanCommands, walkCommands } from "./scan.js";
+export { buildManifest, describeCommand, generateManifest, MANIFEST_SCHEMA_VERSION, manifestHash } from "./manifest.js";
+export { BUILD_DIR, BUILD_MANIFEST_FILE, buildProject, HANDLER_JS, RolldownUnavailableError, SERVER_JS, START_ENTRY } from "./build.js";
+export { formatBuildSummary, runBuild } from "./cli/build.js";
+export { mextVersion } from "./version.js";
+export * from "./mcp/index.js";
+export { CLI_BUILTIN_COMMANDS, CONFIG_FILE, createApp, defineConfig, loadConfig, resolveCommandsDir, resolveLocalPrincipal } from "./config.js";
+export { buildCustomerCli, CLI_BIN_FILE, CLI_DIR, customerCliIssues } from "./build-cli.js";
+export { runCustomerCli } from "./client/main.js";
+export { clientManifest, manifestHelp } from "./client/manifest.js";
+export { runRemote } from "./client/runner.js";
+export { runCli, SUBCOMMANDS } from "./cli/main.js";
+export { analyzeInput, assertCliConvertible, cliBuildIssues, cliSpec, parseArgs, RESERVED_FLAGS, toKebab } from "./cli/args.js";
+export { cliPath, formatInvocation, renderCommandHelp, renderHelp, renderNamespaceHelp, resolveHelpTarget, } from "./cli/help.js";
+export { errorJson, exitCodeOf, formatError, formatJson, formatResult } from "./cli/output.js";
+export { loginCommand, resolveServerUrl } from "./cli/login.js";
+export { logoutCommand } from "./cli/logout.js";
+export * from "./remote/index.js";
+export { cliSpecFromJsonSchema, defineCliSpec } from "./cli/args.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAavD,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAEpE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,cAAc,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAEpG,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE5G,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,0BAA0B,GAC3B,MAAM,sBAAsB,CAAA;AAS7B,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAWhH,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAErF,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAEvH,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,YAAY,EAAE,UAAU,EAAE,wBAAwB,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAEvI,OAAO,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC1C,cAAc,gBAAgB,CAAA;AAC9B,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAE/I,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAE3F,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEjD,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAEnE,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAE9C,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAGnD,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,cAAc,EAAE,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAE/H,OAAO,EACL,OAAO,EACP,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,eAAe,CAAA;AAEtB,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC9F,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAE/D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,cAAc,mBAAmB,CAAA;AACjC,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA","sourcesContent":["export { VERSION } from \"./version.ts\"\n\nexport { defineCommand, isCommand } from \"./command.ts\"\nexport type {\n  Ask,\n  AskRequest,\n  Command,\n  CommandContext,\n  CommandDefinition,\n  ConfirmRequest,\n  InputRequest,\n  InputSchema,\n  MextApp,\n  ProgressUpdate,\n} from \"./command.ts\"\nexport { ANONYMOUS, hasScope, localPrincipal } from \"./principal.ts\"\nexport type { Principal } from \"./principal.ts\"\nexport { inputDeclined, isMextError, MextBuildError, MextError, unauthenticated } from \"./errors.ts\"\nexport type { ArgumentIssue, BuildIssue, BuildIssueCode, MextErrorCode, MextErrorDetails } from \"./errors.ts\"\nexport { authorize, confirmationMessage, createContext, findCommand, invoke, parseInput } from \"./invoke.ts\"\nexport type { AskHandler, AskHandlerRequest, InvokeOptions, InvokeResult } from \"./invoke.ts\"\nexport {\n  findInstrumentation,\n  INSTRUMENTATION_FILE,\n  loadInstrumentation,\n  loadProjectInstrumentation,\n} from \"./instrumentation.ts\"\nexport type {\n  CommandErrorInfo,\n  Instrumentation,\n  InstrumentationModule,\n  LoadInstrumentationOptions,\n  OtelApi,\n  Transport,\n} from \"./instrumentation.ts\"\nexport { collectRegistry, createLazyRegistry, createRegistry, loadCommand, resolveCommand } from \"./registry.ts\"\nexport type {\n  JsonSchema,\n  LazyCommandInput,\n  NamespaceInfo,\n  RegisteredCommand,\n  Registry,\n  RegistryCommandInput,\n  RegistryInput,\n  RegistryNamespaceInput,\n} from \"./registry.ts\"\nexport { collectCommands, loadRegistry, scanCommands, walkCommands } from \"./scan.ts\"\nexport type { ScannedFile, ScanResult } from \"./scan.ts\"\nexport { buildManifest, describeCommand, generateManifest, MANIFEST_SCHEMA_VERSION, manifestHash } from \"./manifest.ts\"\nexport type { BuildManifest, BuildManifestCommand, Manifest, ManifestCommand, ManifestNamespace } from \"./manifest.ts\"\nexport { BUILD_DIR, BUILD_MANIFEST_FILE, buildProject, HANDLER_JS, RolldownUnavailableError, SERVER_JS, START_ENTRY } from \"./build.ts\"\nexport type { BuildOptions, BuildResult, BuildWarning, RolldownModule, RolldownOutputItem } from \"./build.ts\"\nexport { formatBuildSummary, runBuild } from \"./cli/build.ts\"\nexport { mextVersion } from \"./version.ts\"\nexport * from \"./mcp/index.ts\"\nexport { CLI_BUILTIN_COMMANDS, CONFIG_FILE, createApp, defineConfig, loadConfig, resolveCommandsDir, resolveLocalPrincipal } from \"./config.ts\"\nexport type { CliConfig, MextConfig } from \"./config.ts\"\nexport { buildCustomerCli, CLI_BIN_FILE, CLI_DIR, customerCliIssues } from \"./build-cli.ts\"\nexport type { BuildCustomerCliOptions, CustomerCliBuild } from \"./build-cli.ts\"\nexport { runCustomerCli } from \"./client/main.ts\"\nexport type { CustomerCliConfig } from \"./client/main.ts\"\nexport { clientManifest, manifestHelp } from \"./client/manifest.ts\"\nexport type { ClientManifest, ClientManifestCommand } from \"./client/manifest.ts\"\nexport { runRemote } from \"./client/runner.ts\"\nexport type { HelpSource, RemoteRunOptions } from \"./client/runner.ts\"\nexport { runCli, SUBCOMMANDS } from \"./cli/main.ts\"\nexport type { CliSubcommand } from \"./cli/main.ts\"\nexport type { CliIo, CliWriter } from \"./cli/io.ts\"\nexport { analyzeInput, assertCliConvertible, cliBuildIssues, cliSpec, parseArgs, RESERVED_FLAGS, toKebab } from \"./cli/args.ts\"\nexport type { CliField, CliSpec, FieldKind, ParseArgsOptions, ParsedArgs, Primitive, ScalarKind } from \"./cli/args.ts\"\nexport {\n  cliPath,\n  formatInvocation,\n  renderCommandHelp,\n  renderHelp,\n  renderNamespaceHelp,\n  resolveHelpTarget,\n} from \"./cli/help.ts\"\nexport type { HelpOptions, HelpTarget } from \"./cli/help.ts\"\nexport { errorJson, exitCodeOf, formatError, formatJson, formatResult } from \"./cli/output.ts\"\nexport { loginCommand, resolveServerUrl } from \"./cli/login.ts\"\nexport type { AuthCommandOptions } from \"./cli/login.ts\"\nexport { logoutCommand } from \"./cli/logout.ts\"\nexport * from \"./remote/index.ts\"\nexport { cliSpecFromJsonSchema, defineCliSpec } from \"./cli/args.ts\"\n"]}

package/dist/instrumentation.d.ts

@@ -0,0 +1,97 @@
+import type { Principal } from "./principal.ts";
+/**
+ * instrumentation.ts (프로젝트 루트, 선택) · OpenTelemetry span (§11).
+ * register() = 프로세스당 1회, 첫 명령어 실행 전. onCommandError = 핸들러 예외 보고.
+ * span = @opentelemetry/api (선택 peer) 가 있을 때만. 없으면 no-op (실패한 import 1회 캐시).
+ */
+export declare const INSTRUMENTATION_FILE = "instrumentation.ts";
+/** 핸들러를 실행한 어댑터. 원격 CLI 는 핸들러를 실행하지 않으므로 없다 */
+export type Transport = "http" | "stdio" | "local";
+export interface CommandErrorInfo {
+    /** 정식 명령어 ID */
+    command: string;
+    transport: Transport;
+    /** scopes · claims 는 넘기지 않는다 */
+    principal: {
+        id: string;
+        kind: Principal["kind"];
+    };
+}
+/** instrumentation.ts 의 export */
+export interface InstrumentationModule {
+    register?: () => unknown;
+    onCommandError?: (error: unknown, info: CommandErrorInfo) => unknown;
+}
+/** 어댑터가 InvokeOptions.instrumentation 으로 넘기는 로드 결과 */
+export interface Instrumentation {
+    /** 핸들러 예외 (MextError 외, 취소 · MRTR 대기 제외). 자체 예외는 stderr 로 보고하고 응답은 바꾸지 않는다 */
+    onCommandError?: (error: unknown, info: CommandErrorInfo) => unknown;
+    /** @opentelemetry/api. undefined = span 없음 */
+    otel?: OtelApi;
+    /** onCommandError 의 예외 보고. 기본 stderr */
+    onerror?: (error: unknown) => void;
+}
+export interface LoadInstrumentationOptions {
+    /** @opentelemetry/api 로더 (테스트 주입). 기본 = 동적 import, 결과는 프로세스당 캐시 */
+    importOtel?: () => Promise<unknown>;
+    onerror?: (error: unknown) => void;
+}
+/** mext 가 쓰는 @opentelemetry/api 의 부분 (타입 의존 없이) */
+export interface OtelApi {
+    trace: {
+        getTracer(name: string, version?: string): OtelTracer;
+    };
+    context: {
+        active(): unknown;
+    };
+    propagation: {
+        extract(context: unknown, carrier: unknown): unknown;
+    };
+    SpanStatusCode: {
+        ERROR: number;
+    };
+}
+interface OtelTracer {
+    startActiveSpan<T>(name: string, options: {
+        attributes: Record<string, string>;
+    }, context: unknown, fn: (span: OtelSpan) => T): T;
+}
+interface OtelSpan {
+    setAttribute(key: string, value: string): unknown;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): unknown;
+    recordException(exception: unknown): unknown;
+    end(): void;
+}
+/** cwd 의 instrumentation.ts 절대 경로. 없으면 undefined */
+export declare function findInstrumentation(cwd?: string): string | undefined;
+/** findInstrumentation(cwd) → loadInstrumentation. mext dev · mext run (로컬) · stdio 용 */
+export declare function loadProjectInstrumentation(cwd?: string, options?: LoadInstrumentationOptions): Promise<Instrumentation>;
+/**
+ * instrumentation 모듈 (파일 경로 · URL · import 된 모듈) 을 프로세스당 1회 import 하고 register() 를 await.
+ * 같은 모듈의 두 번째 호출 = register 재호출 없이 같은 hooks. register 실패 = reject (다음 호출에서 재시도).
+ * source 없음 = hooks 없이 span 만. 빌드 산출물 (.mext/server/instrumentation.js) 도 같은 함수.
+ */
+export declare function loadInstrumentation(source?: string | URL | InstrumentationModule, options?: LoadInstrumentationOptions): Promise<Instrumentation>;
+export interface ObserveOptions {
+    instrumentation?: Instrumentation;
+    transport?: Transport;
+    principal: Principal;
+    /** W3C trace context carrier (MCP params._meta 의 traceparent · tracestate) */
+    traceContext?: Record<string, unknown>;
+}
+/**
+ * 명령어 실행 1회를 `mext.command <id>` span 으로 감싼다 (otel 있을 때만, 없으면 fn 그대로).
+ * 속성 = mext.command.id · mext.transport · mext.principal.kind. 인자 · 결과 · 토큰은 기록하지 않는다.
+ * 실패: status ERROR + mext.error.code. 핸들러 예외만 recordException (MextError 메시지는 입력 일부를 담을 수 있어 제외).
+ * 취소 (signal abort · MRTR 대기) = status 없음.
+ */
+export declare function observeCommand<T>(command: string, options: ObserveOptions, signal: () => AbortSignal | undefined, fn: () => Promise<T>): Promise<T>;
+/**
+ * 핸들러 예외 → onCommandError (await). MextError · 취소 · MRTR 대기는 보고하지 않는다.
+ * onCommandError 자체의 예외 = onerror (기본 stderr), 호출자에게 전파하지 않는다.
+ */
+export declare function reportCommandError(error: unknown, command: string, options: ObserveOptions, signal: AbortSignal | undefined): Promise<void>;
+export {};

package/dist/instrumentation.js

@@ -0,0 +1,165 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { isMextError } from "./errors.js";
+/**
+ * instrumentation.ts (프로젝트 루트, 선택) · OpenTelemetry span (§11).
+ * register() = 프로세스당 1회, 첫 명령어 실행 전. onCommandError = 핸들러 예외 보고.
+ * span = @opentelemetry/api (선택 peer) 가 있을 때만. 없으면 no-op (실패한 import 1회 캐시).
+ */
+export const INSTRUMENTATION_FILE = "instrumentation.ts";
+/** cwd 의 instrumentation.ts 절대 경로. 없으면 undefined */
+export function findInstrumentation(cwd = process.cwd()) {
+    const file = join(resolve(cwd), INSTRUMENTATION_FILE);
+    return existsSync(file) ? file : undefined;
+}
+/** findInstrumentation(cwd) → loadInstrumentation. mext dev · mext run (로컬) · stdio 용 */
+export function loadProjectInstrumentation(cwd = process.cwd(), options = {}) {
+    return loadInstrumentation(findInstrumentation(cwd), options);
+}
+const loaded = new Map();
+const loadedModules = new WeakMap();
+/**
+ * instrumentation 모듈 (파일 경로 · URL · import 된 모듈) 을 프로세스당 1회 import 하고 register() 를 await.
+ * 같은 모듈의 두 번째 호출 = register 재호출 없이 같은 hooks. register 실패 = reject (다음 호출에서 재시도).
+ * source 없음 = hooks 없이 span 만. 빌드 산출물 (.mext/server/instrumentation.js) 도 같은 함수.
+ */
+export async function loadInstrumentation(source, options = {}) {
+    const [mod, otel] = await Promise.all([
+        source === undefined ? Promise.resolve({}) : registerOnce(source),
+        options.importOtel ? resolveOtel(options.importOtel) : defaultOtel(),
+    ]);
+    return {
+        ...(mod.onCommandError ? { onCommandError: mod.onCommandError } : {}),
+        ...(otel ? { otel } : {}),
+        ...(options.onerror ? { onerror: options.onerror } : {}),
+    };
+}
+function registerOnce(source) {
+    if (typeof source === "string" || source instanceof URL) {
+        const isPath = typeof source === "string" && (isAbsolute(source) || !/^[a-z][a-z0-9+.-]+:/i.test(source));
+        const href = isPath ? pathToFileURL(resolve(source)).href : String(source);
+        return memo(loaded, href, () => import(__rewriteRelativeImportExtension(href)).then((m) => register(m, href)));
+    }
+    return memo(loadedModules, source, () => register(source, "instrumentation"));
+}
+function memo(cache, key, load) {
+    let pending = cache.get(key);
+    if (!pending) {
+        pending = load().catch((error) => {
+            cache.delete(key);
+            throw error;
+        });
+        cache.set(key, pending);
+    }
+    return pending;
+}
+async function register(value, label) {
+    const mod = (value ?? {});
+    for (const key of ["register", "onCommandError"]) {
+        if (mod[key] !== undefined && typeof mod[key] !== "function") {
+            throw new TypeError(`${label}: export ${key} must be a function`);
+        }
+    }
+    const hooks = mod;
+    await hooks.register?.();
+    return hooks;
+}
+/* @opentelemetry/api (선택 peer). 번들러가 해석 · 포함하지 않도록 specifier 는 변수 (R5) */
+const OTEL_API = "@opentelemetry/api";
+let otelDefault;
+function defaultOtel() {
+    otelDefault ??= resolveOtel(() => import(__rewriteRelativeImportExtension(OTEL_API)));
+    return otelDefault;
+}
+async function resolveOtel(importer) {
+    try {
+        const mod = (await importer());
+        const api = mod.trace ? mod : mod.default;
+        return api?.trace && api.context && api.propagation && api.SpanStatusCode ? api : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/* invoke 에서 사용 */
+const TRACER_NAME = "@obov/mext";
+/**
+ * 명령어 실행 1회를 `mext.command <id>` span 으로 감싼다 (otel 있을 때만, 없으면 fn 그대로).
+ * 속성 = mext.command.id · mext.transport · mext.principal.kind. 인자 · 결과 · 토큰은 기록하지 않는다.
+ * 실패: status ERROR + mext.error.code. 핸들러 예외만 recordException (MextError 메시지는 입력 일부를 담을 수 있어 제외).
+ * 취소 (signal abort · MRTR 대기) = status 없음.
+ */
+export function observeCommand(command, options, signal, fn) {
+    const otel = options.instrumentation?.otel;
+    if (!otel)
+        return fn();
+    const parent = options.traceContext ? otel.propagation.extract(otel.context.active(), options.traceContext) : otel.context.active();
+    const attributes = {
+        "mext.command.id": command,
+        "mext.transport": options.transport ?? "local",
+        "mext.principal.kind": options.principal.kind,
+    };
+    const tracer = otel.trace.getTracer(TRACER_NAME);
+    return tracer.startActiveSpan(`mext.command ${command}`, { attributes }, parent, async (span) => {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            if (!signal()?.aborted) {
+                if (isMextError(error)) {
+                    span.setAttribute("mext.error.code", error.code);
+                    span.setStatus({ code: otel.SpanStatusCode.ERROR, message: error.code });
+                }
+                else {
+                    span.setAttribute("mext.error.code", "EXECUTION_ERROR");
+                    span.recordException(error);
+                    span.setStatus({ code: otel.SpanStatusCode.ERROR, message: error instanceof Error ? error.message : String(error) });
+                }
+            }
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+/**
+ * 핸들러 예외 → onCommandError (await). MextError · 취소 · MRTR 대기는 보고하지 않는다.
+ * onCommandError 자체의 예외 = onerror (기본 stderr), 호출자에게 전파하지 않는다.
+ */
+export async function reportCommandError(error, command, options, signal) {
+    const hook = options.instrumentation?.onCommandError;
+    if (!hook || isMextError(error) || signal?.aborted)
+        return;
+    const info = {
+        command,
+        transport: options.transport ?? "local",
+        principal: { id: options.principal.id, kind: options.principal.kind },
+    };
+    try {
+        await hook(error, info);
+    }
+    catch (hookError) {
+        const onerror = options.instrumentation?.onerror ?? defaultOnError;
+        try {
+            onerror(hookError);
+        }
+        catch {
+            // 보고는 응답을 바꾸지 않는다
+        }
+    }
+}
+function defaultOnError(error) {
+    const message = error instanceof Error ? (error.stack ?? error.message) : String(error);
+    process.stderr.write(`mext: onCommandError threw: ${message}\n`);
+}
+//# sourceMappingURL=instrumentation.js.map

package/dist/instrumentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation.js","sourceRoot":"","sources":["../src/instrumentation.ts"],"names":[],"mappings":"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","sourcesContent":["import { existsSync } from \"node:fs\"\nimport { isAbsolute, join, resolve } from \"node:path\"\nimport { pathToFileURL } from \"node:url\"\nimport { isMextError } from \"./errors.ts\"\nimport type { Principal } from \"./principal.ts\"\n\n/**\n * instrumentation.ts (프로젝트 루트, 선택) · OpenTelemetry span (§11).\n * register() = 프로세스당 1회, 첫 명령어 실행 전. onCommandError = 핸들러 예외 보고.\n * span = @opentelemetry/api (선택 peer) 가 있을 때만. 없으면 no-op (실패한 import 1회 캐시).\n */\n\nexport const INSTRUMENTATION_FILE = \"instrumentation.ts\"\n\n/** 핸들러를 실행한 어댑터. 원격 CLI 는 핸들러를 실행하지 않으므로 없다 */\nexport type Transport = \"http\" | \"stdio\" | \"local\"\n\nexport interface CommandErrorInfo {\n  /** 정식 명령어 ID */\n  command: string\n  transport: Transport\n  /** scopes · claims 는 넘기지 않는다 */\n  principal: { id: string; kind: Principal[\"kind\"] }\n}\n\n/** instrumentation.ts 의 export */\nexport interface InstrumentationModule {\n  register?: () => unknown\n  onCommandError?: (error: unknown, info: CommandErrorInfo) => unknown\n}\n\n/** 어댑터가 InvokeOptions.instrumentation 으로 넘기는 로드 결과 */\nexport interface Instrumentation {\n  /** 핸들러 예외 (MextError 외, 취소 · MRTR 대기 제외). 자체 예외는 stderr 로 보고하고 응답은 바꾸지 않는다 */\n  onCommandError?: (error: unknown, info: CommandErrorInfo) => unknown\n  /** @opentelemetry/api. undefined = span 없음 */\n  otel?: OtelApi\n  /** onCommandError 의 예외 보고. 기본 stderr */\n  onerror?: (error: unknown) => void\n}\n\nexport interface LoadInstrumentationOptions {\n  /** @opentelemetry/api 로더 (테스트 주입). 기본 = 동적 import, 결과는 프로세스당 캐시 */\n  importOtel?: () => Promise<unknown>\n  onerror?: (error: unknown) => void\n}\n\n/** mext 가 쓰는 @opentelemetry/api 의 부분 (타입 의존 없이) */\nexport interface OtelApi {\n  trace: { getTracer(name: string, version?: string): OtelTracer }\n  context: { active(): unknown }\n  propagation: { extract(context: unknown, carrier: unknown): unknown }\n  SpanStatusCode: { ERROR: number }\n}\n\ninterface OtelTracer {\n  startActiveSpan<T>(name: string, options: { attributes: Record<string, string> }, context: unknown, fn: (span: OtelSpan) => T): T\n}\n\ninterface OtelSpan {\n  setAttribute(key: string, value: string): unknown\n  setStatus(status: { code: number; message?: string }): unknown\n  recordException(exception: unknown): unknown\n  end(): void\n}\n\n/** cwd 의 instrumentation.ts 절대 경로. 없으면 undefined */\nexport function findInstrumentation(cwd: string = process.cwd()): string | undefined {\n  const file = join(resolve(cwd), INSTRUMENTATION_FILE)\n  return existsSync(file) ? file : undefined\n}\n\n/** findInstrumentation(cwd) → loadInstrumentation. mext dev · mext run (로컬) · stdio 용 */\nexport function loadProjectInstrumentation(\n  cwd: string = process.cwd(),\n  options: LoadInstrumentationOptions = {},\n): Promise<Instrumentation> {\n  return loadInstrumentation(findInstrumentation(cwd), options)\n}\n\nconst loaded = new Map<string, Promise<InstrumentationModule>>()\nconst loadedModules = new WeakMap<object, Promise<InstrumentationModule>>()\n\n/**\n * instrumentation 모듈 (파일 경로 · URL · import 된 모듈) 을 프로세스당 1회 import 하고 register() 를 await.\n * 같은 모듈의 두 번째 호출 = register 재호출 없이 같은 hooks. register 실패 = reject (다음 호출에서 재시도).\n * source 없음 = hooks 없이 span 만. 빌드 산출물 (.mext/server/instrumentation.js) 도 같은 함수.\n */\nexport async function loadInstrumentation(\n  source?: string | URL | InstrumentationModule,\n  options: LoadInstrumentationOptions = {},\n): Promise<Instrumentation> {\n  const [mod, otel] = await Promise.all([\n    source === undefined ? Promise.resolve<InstrumentationModule>({}) : registerOnce(source),\n    options.importOtel ? resolveOtel(options.importOtel) : defaultOtel(),\n  ])\n  return {\n    ...(mod.onCommandError ? { onCommandError: mod.onCommandError } : {}),\n    ...(otel ? { otel } : {}),\n    ...(options.onerror ? { onerror: options.onerror } : {}),\n  }\n}\n\nfunction registerOnce(source: string | URL | InstrumentationModule): Promise<InstrumentationModule> {\n  if (typeof source === \"string\" || source instanceof URL) {\n    const isPath = typeof source === \"string\" && (isAbsolute(source) || !/^[a-z][a-z0-9+.-]+:/i.test(source))\n    const href = isPath ? pathToFileURL(resolve(source as string)).href : String(source)\n    return memo(loaded, href, () => import(href).then((m: unknown) => register(m, href)))\n  }\n  return memo(loadedModules, source, () => register(source, \"instrumentation\"))\n}\n\nfunction memo<K>(\n  cache: { get(k: K): Promise<InstrumentationModule> | undefined; set(k: K, v: Promise<InstrumentationModule>): unknown; delete(k: K): unknown },\n  key: K,\n  load: () => Promise<InstrumentationModule>,\n): Promise<InstrumentationModule> {\n  let pending = cache.get(key)\n  if (!pending) {\n    pending = load().catch((error: unknown) => {\n      cache.delete(key)\n      throw error\n    })\n    cache.set(key, pending)\n  }\n  return pending\n}\n\nasync function register(value: unknown, label: string): Promise<InstrumentationModule> {\n  const mod = (value ?? {}) as Record<string, unknown>\n  for (const key of [\"register\", \"onCommandError\"]) {\n    if (mod[key] !== undefined && typeof mod[key] !== \"function\") {\n      throw new TypeError(`${label}: export ${key} must be a function`)\n    }\n  }\n  const hooks = mod as InstrumentationModule\n  await hooks.register?.()\n  return hooks\n}\n\n/* @opentelemetry/api (선택 peer). 번들러가 해석 · 포함하지 않도록 specifier 는 변수 (R5) */\n\nconst OTEL_API = \"@opentelemetry/api\"\nlet otelDefault: Promise<OtelApi | undefined> | undefined\n\nfunction defaultOtel(): Promise<OtelApi | undefined> {\n  otelDefault ??= resolveOtel(() => import(OTEL_API))\n  return otelDefault\n}\n\nasync function resolveOtel(importer: () => Promise<unknown>): Promise<OtelApi | undefined> {\n  try {\n    const mod = (await importer()) as Partial<OtelApi> & { default?: Partial<OtelApi> }\n    const api = mod.trace ? mod : mod.default\n    return api?.trace && api.context && api.propagation && api.SpanStatusCode ? (api as OtelApi) : undefined\n  } catch {\n    return undefined\n  }\n}\n\n/* invoke 에서 사용 */\n\nconst TRACER_NAME = \"@obov/mext\"\n\nexport interface ObserveOptions {\n  instrumentation?: Instrumentation\n  transport?: Transport\n  principal: Principal\n  /** W3C trace context carrier (MCP params._meta 의 traceparent · tracestate) */\n  traceContext?: Record<string, unknown>\n}\n\n/**\n * 명령어 실행 1회를 `mext.command <id>` span 으로 감싼다 (otel 있을 때만, 없으면 fn 그대로).\n * 속성 = mext.command.id · mext.transport · mext.principal.kind. 인자 · 결과 · 토큰은 기록하지 않는다.\n * 실패: status ERROR + mext.error.code. 핸들러 예외만 recordException (MextError 메시지는 입력 일부를 담을 수 있어 제외).\n * 취소 (signal abort · MRTR 대기) = status 없음.\n */\nexport function observeCommand<T>(\n  command: string,\n  options: ObserveOptions,\n  signal: () => AbortSignal | undefined,\n  fn: () => Promise<T>,\n): Promise<T> {\n  const otel = options.instrumentation?.otel\n  if (!otel) return fn()\n  const parent = options.traceContext ? otel.propagation.extract(otel.context.active(), options.traceContext) : otel.context.active()\n  const attributes = {\n    \"mext.command.id\": command,\n    \"mext.transport\": options.transport ?? \"local\",\n    \"mext.principal.kind\": options.principal.kind,\n  }\n  const tracer = otel.trace.getTracer(TRACER_NAME)\n  return tracer.startActiveSpan(`mext.command ${command}`, { attributes }, parent, async (span) => {\n    try {\n      return await fn()\n    } catch (error) {\n      if (!signal()?.aborted) {\n        if (isMextError(error)) {\n          span.setAttribute(\"mext.error.code\", error.code)\n          span.setStatus({ code: otel.SpanStatusCode.ERROR, message: error.code })\n        } else {\n          span.setAttribute(\"mext.error.code\", \"EXECUTION_ERROR\")\n          span.recordException(error)\n          span.setStatus({ code: otel.SpanStatusCode.ERROR, message: error instanceof Error ? error.message : String(error) })\n        }\n      }\n      throw error\n    } finally {\n      span.end()\n    }\n  })\n}\n\n/**\n * 핸들러 예외 → onCommandError (await). MextError · 취소 · MRTR 대기는 보고하지 않는다.\n * onCommandError 자체의 예외 = onerror (기본 stderr), 호출자에게 전파하지 않는다.\n */\nexport async function reportCommandError(\n  error: unknown,\n  command: string,\n  options: ObserveOptions,\n  signal: AbortSignal | undefined,\n): Promise<void> {\n  const hook = options.instrumentation?.onCommandError\n  if (!hook || isMextError(error) || signal?.aborted) return\n  const info: CommandErrorInfo = {\n    command,\n    transport: options.transport ?? \"local\",\n    principal: { id: options.principal.id, kind: options.principal.kind },\n  }\n  try {\n    await hook(error, info)\n  } catch (hookError) {\n    const onerror = options.instrumentation?.onerror ?? defaultOnError\n    try {\n      onerror(hookError)\n    } catch {\n      // 보고는 응답을 바꾸지 않는다\n    }\n  }\n}\n\nfunction defaultOnError(error: unknown): void {\n  const message = error instanceof Error ? (error.stack ?? error.message) : String(error)\n  process.stderr.write(`mext: onCommandError threw: ${message}\\n`)\n}\n"]}

package/dist/invoke.d.ts

@@ -0,0 +1,64 @@
+import * as z from "zod";
+import type { CommandContext, InputSchema, MextApp, ProgressUpdate } from "./command.ts";
+import { type Instrumentation, type Transport } from "./instrumentation.ts";
+import { findCommand } from "./lookup.ts";
+import { type Principal } from "./principal.ts";
+import { type JsonSchema, type RegisteredCommand, type Registry } from "./registry.ts";
+/** 어댑터가 주입하는 ctx.ask 구현. command = 정식 ID */
+export type AskHandler = (request: AskHandlerRequest) => Promise<unknown>;
+export type AskHandlerRequest = {
+    command: string;
+    kind: "confirm";
+    message: string;
+} | {
+    command: string;
+    kind: "input";
+    message: string;
+    schema: InputSchema;
+    requestedSchema: JsonSchema;
+};
+export interface InvokeOptions {
+    principal: Principal;
+    /** 기본 = abort 되지 않는 signal */
+    signal?: AbortSignal;
+    /** 기본 = 무시 */
+    progress?: (update: ProgressUpdate) => void;
+    /** 기본 = ctx.ask 호출 시 INPUT_UNAVAILABLE */
+    ask?: AskHandler;
+    app?: MextApp;
+    /** readOnly 명령어만 허용 (split 의 query 도구). 그 외 = PERMISSION_DENIED */
+    readOnly?: boolean;
+    /** loadInstrumentation 결과. onCommandError · mext.command span. 기본 = 없음 */
+    instrumentation?: Instrumentation;
+    /** 실행 어댑터 (onCommandError · span 속성). 기본 "local" */
+    transport?: Transport;
+    /** W3C trace context carrier (MCP params._meta 의 traceparent · tracestate). span 의 부모 */
+    traceContext?: Record<string, unknown>;
+}
+export interface InvokeResult {
+    /** 정식 ID (별칭으로 호출해도) */
+    command: string;
+    value: unknown;
+}
+/**
+ * 어댑터 공통 실행기: ID 해석 (별칭 포함) → 권한 → (lazy 면 모듈 import) → Zod safeParse 1회 → 확인 (requiresConfirmation) → execute.
+ * 실패는 MextError (UNKNOWN_COMMAND · PERMISSION_DENIED · INVALID_ARGUMENT · INPUT_UNAVAILABLE · INPUT_DECLINED).
+ * 핸들러 예외는 그대로 전파 (instrumentation 있으면 onCommandError 보고 후).
+ * instrumentation.otel 있으면 findCommand 뒤 전체를 `mext.command <id>` span 으로 감싼다.
+ */
+export declare function invoke(registry: Registry, id: string, rawInput: unknown, options: InvokeOptions): Promise<InvokeResult>;
+/** ID · 별칭 → 명령어. 없으면 UNKNOWN_COMMAND (suggested · usage). 구현 = lookup.ts (help · 고객 CLI 공용) */
+export { findCommand };
+/**
+ * 안전성 메타데이터를 주체에 대해 강제.
+ * readOnly 전용 호출 = readOnly 명령어만 · anonymous = readOnly 명령어만 · command.scopes 전부 보유 ("*" = 전체).
+ */
+export declare function authorize(entry: RegisteredCommand, principal: Principal, options?: {
+    readOnly?: boolean;
+}): void;
+/** Zod safeParse 1회. 실패 = INVALID_ARGUMENT (missing_fields · issues · expected_schema · examples) */
+export declare function parseInput(entry: RegisteredCommand, rawInput: unknown): Promise<z.output<InputSchema>>;
+/** ctx 생성. ask · progress · signal 은 어댑터 주입 */
+export declare function createContext(entry: RegisteredCommand, options: InvokeOptions): CommandContext;
+/** requiresConfirmation 확인 문구. 검증된 입력을 포함 (무엇을 승인하는지) */
+export declare function confirmationMessage(entry: RegisteredCommand, input: unknown): string;

package/dist/invoke.js

@@ -0,0 +1,152 @@
+import * as z from "zod";
+import { inputDeclined, MextError } from "./errors.js";
+import { observeCommand, reportCommandError } from "./instrumentation.js";
+import { findCommand } from "./lookup.js";
+import { hasScope } from "./principal.js";
+import { loadCommand } from "./registry.js";
+/**
+ * 어댑터 공통 실행기: ID 해석 (별칭 포함) → 권한 → (lazy 면 모듈 import) → Zod safeParse 1회 → 확인 (requiresConfirmation) → execute.
+ * 실패는 MextError (UNKNOWN_COMMAND · PERMISSION_DENIED · INVALID_ARGUMENT · INPUT_UNAVAILABLE · INPUT_DECLINED).
+ * 핸들러 예외는 그대로 전파 (instrumentation 있으면 onCommandError 보고 후).
+ * instrumentation.otel 있으면 findCommand 뒤 전체를 `mext.command <id>` span 으로 감싼다.
+ */
+export async function invoke(registry, id, rawInput, options) {
+    const entry = findCommand(registry, id);
+    return observeCommand(entry.id, options, () => options.signal, async () => {
+        authorize(entry, options.principal, { readOnly: options.readOnly });
+        // lazy Registry (mext start) = 여기서 명령어 모듈 import. 권한 · ID 오류는 import 없이
+        const command = await loadCommand(entry);
+        const input = await parseInput(entry, rawInput);
+        const ctx = createContext(entry, options);
+        ctx.signal.throwIfAborted();
+        if (entry.command.requiresConfirmation) {
+            // 확인은 ctx.ask 경유 (CLI = 프롬프트 · --yes, MCP = MRTR). ask 미주입 = INPUT_UNAVAILABLE
+            const confirmed = await ctx.ask({ kind: "confirm", message: confirmationMessage(entry, input) });
+            if (!confirmed)
+                throw inputDeclined(entry.id, "confirm");
+            ctx.signal.throwIfAborted();
+        }
+        try {
+            const value = await command.execute(input, ctx);
+            return { command: entry.id, value };
+        }
+        catch (error) {
+            await reportCommandError(error, entry.id, options, ctx.signal);
+            throw error;
+        }
+    });
+}
+/** ID · 별칭 → 명령어. 없으면 UNKNOWN_COMMAND (suggested · usage). 구현 = lookup.ts (help · 고객 CLI 공용) */
+export { findCommand };
+/**
+ * 안전성 메타데이터를 주체에 대해 강제.
+ * readOnly 전용 호출 = readOnly 명령어만 · anonymous = readOnly 명령어만 · command.scopes 전부 보유 ("*" = 전체).
+ */
+export function authorize(entry, principal, options = {}) {
+    const c = entry.command;
+    const deny = (reason, message) => throwError(new MextError("PERMISSION_DENIED", message, {
+        command: entry.id,
+        reason,
+        required_scopes: [...c.scopes],
+        held_scopes: [...principal.scopes],
+    }));
+    if (options.readOnly && !c.readOnly)
+        deny("read_only", `${entry.id} is not read-only and cannot run here.`);
+    if (principal.kind === "anonymous" && !c.readOnly) {
+        deny("anonymous", `${entry.id} is not read-only and requires an authenticated principal.`);
+    }
+    const missing = c.scopes.filter((s) => !hasScope(principal, s));
+    if (missing.length > 0)
+        deny("scope", `${entry.id} requires scopes: ${missing.join(", ")}.`);
+}
+/** Zod safeParse 1회. 실패 = INVALID_ARGUMENT (missing_fields · issues · expected_schema · examples) */
+export async function parseInput(entry, rawInput) {
+    const raw = rawInput === undefined ? {} : rawInput;
+    const result = await (await loadCommand(entry)).input.safeParseAsync(raw);
+    if (result.success)
+        return result.data;
+    throw invalidArgument(entry.id, raw, result.error.issues, entry.inputSchema, [...entry.command.examples]);
+}
+/** ctx 생성. ask · progress · signal 은 어댑터 주입 */
+export function createContext(entry, options) {
+    const handler = options.ask;
+    const ask = async (request) => {
+        if (!handler) {
+            throw new MextError("INPUT_UNAVAILABLE", `${entry.id} requested input, but this environment cannot ask.`, {
+                command: entry.id,
+            });
+        }
+        if (request.kind === "confirm") {
+            return (await handler({ command: entry.id, kind: "confirm", message: request.message })) === true;
+        }
+        const requestedSchema = z.toJSONSchema(request.schema, { target: "draft-2020-12", io: "input" });
+        const response = await handler({
+            command: entry.id,
+            kind: "input",
+            message: request.message,
+            schema: request.schema,
+            requestedSchema,
+        });
+        const parsed = await request.schema.safeParseAsync(response);
+        if (parsed.success)
+            return parsed.data;
+        throw invalidArgument(entry.id, response, parsed.error.issues, requestedSchema, []);
+    };
+    return {
+        principal: options.principal,
+        signal: options.signal ?? new AbortController().signal,
+        progress: options.progress ?? (() => { }),
+        ask: ask,
+        app: options.app ?? {},
+    };
+}
+/** requiresConfirmation 확인 문구. 검증된 입력을 포함 (무엇을 승인하는지) */
+export function confirmationMessage(entry, input) {
+    let args;
+    try {
+        args = JSON.stringify(input) ?? "{}";
+    }
+    catch {
+        args = "{}";
+    }
+    return `Run ${entry.id} with ${args}?${entry.command.destructive ? " This command is destructive." : ""}`;
+}
+function invalidArgument(command, raw, zodIssues, expectedSchema, examples) {
+    const issues = zodIssues.map((i) => ({
+        path: i.path.map(String).join("."),
+        code: i.code,
+        message: i.message,
+    }));
+    const missing = new Set();
+    for (const i of zodIssues) {
+        if (i.code === "invalid_type" && i.path.length > 0 && isAbsent(raw, i.path))
+            missing.add(i.path.map(String).join("."));
+    }
+    const missing_fields = [...missing];
+    const summary = missing_fields.length > 0
+        ? `missing required: ${missing_fields.join(", ")}`
+        : issues.map((i) => (i.path ? `${i.path}: ${i.message}` : i.message)).join("; ");
+    return new MextError("INVALID_ARGUMENT", `Invalid arguments for ${command}: ${summary}`, {
+        command,
+        missing_fields,
+        issues,
+        expected_schema: expectedSchema,
+        examples,
+    });
+}
+/** 원본 입력에 경로가 없는지 (값 undefined 포함) */
+function isAbsent(raw, path) {
+    let cur = raw;
+    for (const key of path) {
+        if (cur === null || typeof cur !== "object")
+            return true;
+        cur = cur[key];
+        if (cur === undefined)
+            return true;
+    }
+    return false;
+}
+function throwError(error) {
+    throw error;
+}
+//# sourceMappingURL=invoke.js.map