@obov/mext 0.0.0-stage → 0.2.0

package/dist/errors.d.ts

@@ -0,0 +1,74 @@
+export type BuildIssueCode = "COMMANDS_DIR_MISSING" | "PATH_COLLISION" | "DUPLICATE_ID" | "INVALID_SEGMENT" | "INVALID_ALIAS" | "RESERVED_ID" | "ROOT_INDEX" | "INVALID_COMMAND" | "LOAD_FAILED" | "SCHEMA_UNREPRESENTABLE" | "CLI_UNCONVERTIBLE" | "BUNDLE_FAILED" | "INVALID_CONFIG";
+export interface BuildIssue {
+    code: BuildIssueCode;
+    message: string;
+    /** commands/ 기준 상대 경로 (posix) */
+    file?: string;
+    id?: string;
+}
+/** 스캔 · Registry 생성의 빌드 오류. 발견한 문제를 모두 모아 한 번에 던진다 */
+export declare class MextBuildError extends Error {
+    readonly issues: readonly BuildIssue[];
+    constructor(issues: readonly BuildIssue[]);
+}
+export type MextErrorCode = "UNKNOWN_COMMAND" | "INVALID_ARGUMENT" | "UNAUTHENTICATED" | "PERMISSION_DENIED" | "INPUT_UNAVAILABLE" | "INPUT_DECLINED";
+export interface ArgumentIssue {
+    /** 점 구분 경로. "" = 입력 전체 */
+    path: string;
+    code: string;
+    message: string;
+}
+export interface MextErrorDetails {
+    UNKNOWN_COMMAND: {
+        command: string;
+        /** 유사 정식 ID (가까운 순) */
+        suggested: string[];
+        /** 다음에 볼 help 대상. "help" (루트) · "help users" (네임스페이스) */
+        usage: string;
+    };
+    INVALID_ARGUMENT: {
+        command: string;
+        /** 원본 입력에 없는 필수 필드 경로 */
+        missing_fields: string[];
+        issues: ArgumentIssue[];
+        /** input JSON Schema 2020-12 */
+        expected_schema: Record<string, unknown>;
+        examples: unknown[];
+    };
+    UNAUTHENTICATED: {
+        reason: "missing_token" | "invalid_token";
+        /** CLI 원격 실행: 토큰 발급 명령 (mext login --url <url>) */
+        login?: string;
+    };
+    PERMISSION_DENIED: {
+        command: string;
+        /** anonymous = 인증 없는 주체의 readOnly 외 명령어 · read_only = readOnly 전용 호출 (split query) · scope = scopes 부족 */
+        reason: "anonymous" | "read_only" | "scope";
+        required_scopes: string[];
+        held_scopes: string[];
+    };
+    /** ctx.ask 를 처리할 수 없는 실행 환경 (TTY 없는 CLI 등) */
+    INPUT_UNAVAILABLE: {
+        command: string;
+    };
+    /** ctx.ask 거절 · 취소. confirm = requiresConfirmation 확인 거절 (실행 안 함), input = 입력 요청 거절 */
+    INPUT_DECLINED: {
+        command: string;
+        kind: "confirm" | "input";
+    };
+}
+/** 구조화 오류. 어댑터는 code 로 분기하고 toJSON() 을 응답 본문으로 쓴다 */
+export declare class MextError<C extends MextErrorCode = MextErrorCode> extends Error {
+    readonly code: C;
+    readonly details: MextErrorDetails[C];
+    constructor(code: C, message: string, details: MextErrorDetails[C]);
+    toJSON(): {
+        code: C;
+        message: string;
+    } & MextErrorDetails[C];
+}
+export declare function isMextError<C extends MextErrorCode>(error: unknown, code?: C): error is MextError<C>;
+/** auth 단계에서 어댑터가 던지는 오류. anonymous 로 낮추지 않는다 */
+export declare function unauthenticated(reason: MextErrorDetails["UNAUTHENTICATED"]["reason"]): MextError<"UNAUTHENTICATED">;
+/** ctx.ask 거절. AskHandler 가 input 요청 거절 · 취소에 던진다. invoke 는 requiresConfirmation 확인 거절에 던진다 */
+export declare function inputDeclined(command: string, kind: "confirm" | "input"): MextError<"INPUT_DECLINED">;

package/dist/errors.js

@@ -0,0 +1,38 @@
+/** 스캔 · Registry 생성의 빌드 오류. 발견한 문제를 모두 모아 한 번에 던진다 */
+export class MextBuildError extends Error {
+    issues;
+    constructor(issues) {
+        super(`mext build failed (${issues.length} issue${issues.length === 1 ? "" : "s"})\n` +
+            issues.map((i) => `  ${i.code}${i.file ? ` ${i.file}` : ""}: ${i.message}`).join("\n"));
+        this.name = "MextBuildError";
+        this.issues = issues;
+    }
+}
+/** 구조화 오류. 어댑터는 code 로 분기하고 toJSON() 을 응답 본문으로 쓴다 */
+export class MextError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "MextError";
+        this.code = code;
+        this.details = details;
+    }
+    toJSON() {
+        return { code: this.code, message: this.message, ...this.details };
+    }
+}
+export function isMextError(error, code) {
+    return error instanceof MextError && (code === undefined || error.code === code);
+}
+/** auth 단계에서 어댑터가 던지는 오류. anonymous 로 낮추지 않는다 */
+export function unauthenticated(reason) {
+    const message = reason === "missing_token" ? "Authentication required." : "Invalid authentication token.";
+    return new MextError("UNAUTHENTICATED", message, { reason });
+}
+/** ctx.ask 거절. AskHandler 가 input 요청 거절 · 취소에 던진다. invoke 는 requiresConfirmation 확인 거절에 던진다 */
+export function inputDeclined(command, kind) {
+    const message = kind === "confirm" ? `${command} was not confirmed and did not run.` : `${command} requested input, but it was declined.`;
+    return new MextError("INPUT_DECLINED", message, { command, kind });
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAuBA,sDAAsD;AACtD,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,MAAM,CAAuB;IAEtC,YAAY,MAA6B;QACvC,KAAK,CACH,sBAAsB,MAAM,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK;YAC7E,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CACzF,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;QAC5B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;CACF;AAyDD,qDAAqD;AACrD,MAAM,OAAO,SAAmD,SAAQ,KAAK;IAClE,IAAI,CAAG;IACP,OAAO,CAAqB;IAErC,YAAY,IAAO,EAAE,OAAe,EAAE,OAA4B;QAChE,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,WAAW,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;IACxB,CAAC;IAED,MAAM;QACJ,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,CAAA;IACpE,CAAC;CACF;AAED,MAAM,UAAU,WAAW,CAA0B,KAAc,EAAE,IAAQ;IAC3E,OAAO,KAAK,YAAY,SAAS,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;AAClF,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,eAAe,CAAC,MAAqD;IACnF,MAAM,OAAO,GAAG,MAAM,KAAK,eAAe,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,CAAC,+BAA+B,CAAA;IACzG,OAAO,IAAI,SAAS,CAAC,iBAAiB,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,CAAC,CAAA;AAC9D,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,IAAyB;IACtE,MAAM,OAAO,GACX,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,qCAAqC,CAAC,CAAC,CAAC,GAAG,OAAO,wCAAwC,CAAA;IAC3H,OAAO,IAAI,SAAS,CAAC,gBAAgB,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAA;AACpE,CAAC","sourcesContent":["export type BuildIssueCode =\n  | \"COMMANDS_DIR_MISSING\"\n  | \"PATH_COLLISION\"\n  | \"DUPLICATE_ID\"\n  | \"INVALID_SEGMENT\"\n  | \"INVALID_ALIAS\"\n  | \"RESERVED_ID\"\n  | \"ROOT_INDEX\"\n  | \"INVALID_COMMAND\"\n  | \"LOAD_FAILED\"\n  | \"SCHEMA_UNREPRESENTABLE\"\n  | \"CLI_UNCONVERTIBLE\"\n  | \"BUNDLE_FAILED\"\n  | \"INVALID_CONFIG\"\n\nexport interface BuildIssue {\n  code: BuildIssueCode\n  message: string\n  /** commands/ 기준 상대 경로 (posix) */\n  file?: string\n  id?: string\n}\n\n/** 스캔 · Registry 생성의 빌드 오류. 발견한 문제를 모두 모아 한 번에 던진다 */\nexport class MextBuildError extends Error {\n  readonly issues: readonly BuildIssue[]\n\n  constructor(issues: readonly BuildIssue[]) {\n    super(\n      `mext build failed (${issues.length} issue${issues.length === 1 ? \"\" : \"s\"})\\n` +\n        issues.map((i) => `  ${i.code}${i.file ? ` ${i.file}` : \"\"}: ${i.message}`).join(\"\\n\"),\n    )\n    this.name = \"MextBuildError\"\n    this.issues = issues\n  }\n}\n\nexport type MextErrorCode =\n  | \"UNKNOWN_COMMAND\"\n  | \"INVALID_ARGUMENT\"\n  | \"UNAUTHENTICATED\"\n  | \"PERMISSION_DENIED\"\n  | \"INPUT_UNAVAILABLE\"\n  | \"INPUT_DECLINED\"\n\nexport interface ArgumentIssue {\n  /** 점 구분 경로. \"\" = 입력 전체 */\n  path: string\n  code: string\n  message: string\n}\n\nexport interface MextErrorDetails {\n  UNKNOWN_COMMAND: {\n    command: string\n    /** 유사 정식 ID (가까운 순) */\n    suggested: string[]\n    /** 다음에 볼 help 대상. \"help\" (루트) · \"help users\" (네임스페이스) */\n    usage: string\n  }\n  INVALID_ARGUMENT: {\n    command: string\n    /** 원본 입력에 없는 필수 필드 경로 */\n    missing_fields: string[]\n    issues: ArgumentIssue[]\n    /** input JSON Schema 2020-12 */\n    expected_schema: Record<string, unknown>\n    examples: unknown[]\n  }\n  UNAUTHENTICATED: {\n    reason: \"missing_token\" | \"invalid_token\"\n    /** CLI 원격 실행: 토큰 발급 명령 (mext login --url <url>) */\n    login?: string\n  }\n  PERMISSION_DENIED: {\n    command: string\n    /** anonymous = 인증 없는 주체의 readOnly 외 명령어 · read_only = readOnly 전용 호출 (split query) · scope = scopes 부족 */\n    reason: \"anonymous\" | \"read_only\" | \"scope\"\n    required_scopes: string[]\n    held_scopes: string[]\n  }\n  /** ctx.ask 를 처리할 수 없는 실행 환경 (TTY 없는 CLI 등) */\n  INPUT_UNAVAILABLE: {\n    command: string\n  }\n  /** ctx.ask 거절 · 취소. confirm = requiresConfirmation 확인 거절 (실행 안 함), input = 입력 요청 거절 */\n  INPUT_DECLINED: {\n    command: string\n    kind: \"confirm\" | \"input\"\n  }\n}\n\n/** 구조화 오류. 어댑터는 code 로 분기하고 toJSON() 을 응답 본문으로 쓴다 */\nexport class MextError<C extends MextErrorCode = MextErrorCode> extends Error {\n  readonly code: C\n  readonly details: MextErrorDetails[C]\n\n  constructor(code: C, message: string, details: MextErrorDetails[C]) {\n    super(message)\n    this.name = \"MextError\"\n    this.code = code\n    this.details = details\n  }\n\n  toJSON(): { code: C; message: string } & MextErrorDetails[C] {\n    return { code: this.code, message: this.message, ...this.details }\n  }\n}\n\nexport function isMextError<C extends MextErrorCode>(error: unknown, code?: C): error is MextError<C> {\n  return error instanceof MextError && (code === undefined || error.code === code)\n}\n\n/** auth 단계에서 어댑터가 던지는 오류. anonymous 로 낮추지 않는다 */\nexport function unauthenticated(reason: MextErrorDetails[\"UNAUTHENTICATED\"][\"reason\"]): MextError<\"UNAUTHENTICATED\"> {\n  const message = reason === \"missing_token\" ? \"Authentication required.\" : \"Invalid authentication token.\"\n  return new MextError(\"UNAUTHENTICATED\", message, { reason })\n}\n\n/** ctx.ask 거절. AskHandler 가 input 요청 거절 · 취소에 던진다. invoke 는 requiresConfirmation 확인 거절에 던진다 */\nexport function inputDeclined(command: string, kind: \"confirm\" | \"input\"): MextError<\"INPUT_DECLINED\"> {\n  const message =\n    kind === \"confirm\" ? `${command} was not confirmed and did not run.` : `${command} requested input, but it was declined.`\n  return new MextError(\"INPUT_DECLINED\", message, { command, kind })\n}\n"]}

package/dist/ids.d.ts

@@ -0,0 +1,6 @@
+/** 경로 세그먼트 · 별칭 규칙: kebab-case 만 */
+export declare const SEGMENT_PATTERN: RegExp;
+/** 루트에 둘 수 없는 세그먼트 (help 탐색 · CLI help 와 충돌) */
+export declare const RESERVED_ROOT_SEGMENTS: readonly string[];
+export declare function isSegment(value: string): boolean;
+export declare function parentNamespace(id: string): string;

package/dist/ids.js

@@ -0,0 +1,12 @@
+/** 경로 세그먼트 · 별칭 규칙: kebab-case 만 */
+export const SEGMENT_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+/** 루트에 둘 수 없는 세그먼트 (help 탐색 · CLI help 와 충돌) */
+export const RESERVED_ROOT_SEGMENTS = ["help"];
+export function isSegment(value) {
+    return SEGMENT_PATTERN.test(value);
+}
+export function parentNamespace(id) {
+    const i = id.lastIndexOf(".");
+    return i === -1 ? "" : id.slice(0, i);
+}
+//# sourceMappingURL=ids.js.map

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,46 @@
+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, McpCapabilities, McpConfig, McpConnectHandler, McpConnection, 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 type { CliErrorFormatter, CliErrorInfo, CliErrorOutput } 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;AAE9F,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, McpCapabilities, McpConfig, McpConnectHandler, McpConnection, 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 type { CliErrorFormatter, CliErrorInfo, CliErrorOutput } 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;