@obov/mext 0.0.0-stage → 0.2.0

package/dist/mcp/stdio.js

@@ -0,0 +1,222 @@
+import { Writable } from "node:stream";
+import { serveStdio, StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { localPrincipal } from "../principal.js";
+import { createMcpServerFactory } from "./server.js";
+/**
+ * MCP stdio (2026-07-28 · 2025 레거시 모두 SDK serveStdio). 줄 단위 JSON-RPC, 연결 하나 = McpServer 하나.
+ * notifications/cancelled → ctx.signal abort (SDK). stdin EOF = 연결 종료, 진행 중 요청은 abort 되고 응답하지 않는다.
+ * 헤더 검증 · Origin · 바인딩 · Authorization 은 해당 없음. 주체 = 로컬 (kind local).
+ */
+export function serveMcpStdio(options) {
+    const core = createMcpServerFactory({
+        registry: options.registry,
+        principal: options.principal ?? localPrincipal(),
+        ...(options.app ? { app: options.app } : {}),
+        ...(options.tools ? { tools: options.tools } : {}),
+        ...(options.name ? { name: options.name } : {}),
+        ...(options.instructions !== undefined ? { instructions: options.instructions } : {}),
+        ...(options.capabilities ? { capabilities: options.capabilities } : {}),
+        ...(options.requestStateKey !== undefined ? { requestStateKey: options.requestStateKey } : {}),
+        ...(options.progressInterval !== undefined ? { progressInterval: options.progressInterval } : {}),
+        ...(options.instrumentation ? { instrumentation: options.instrumentation } : {}),
+        ...(options.manifestHash !== undefined ? { manifestHash: options.manifestHash } : {}),
+        transport: "stdio",
+    });
+    const onConnect = options.onConnect;
+    const report = (error) => options.onerror?.(error instanceof Error ? error : new Error(String(error)));
+    /** 인스턴스별 정리 완료 (onConnect settle + cleanup). closed 는 이것들을 기다린다 */
+    const settled = new Set();
+    const factory = onConnect
+        ? async (ctx) => {
+            const server = (await core(ctx));
+            settled.add(attachConnection(server, ctx.era, onConnect, report));
+            return server;
+        }
+        : core;
+    const transport = new StdioServerTransport(options.stdin, options.stdout);
+    let resolveClosed;
+    const closed = new Promise((resolve) => {
+        resolveClosed = resolve;
+    });
+    let finishing = false;
+    const finish = () => {
+        if (finishing)
+            return;
+        finishing = true;
+        void waitCleanups(settled, report).then(resolveClosed);
+    };
+    const wrapClose = () => {
+        const sdkOnClose = transport.onclose;
+        transport.onclose = () => {
+            try {
+                sdkOnClose?.();
+            }
+            finally {
+                finish();
+            }
+        };
+    };
+    let handle;
+    const era = options.era ?? (options.capabilities?.experimental?.[CLAUDE_CHANNEL] !== undefined ? "legacy" : "auto");
+    if (era === "legacy") {
+        // serveStdio 는 server/discover 를 받으면 2026-07-28 로 고정한다 → 우회.
+        // SDK 기본 supportedProtocolVersions = 2025 버전만 → McpServer 생성자가 server/discover 를 등록하지 않는다
+        const ready = Promise.resolve(factory({ era: "legacy" })).then(async (product) => {
+            const server = product;
+            server.server.onerror = report;
+            await server.connect(transport);
+            wrapClose();
+            return server;
+        });
+        ready.catch((error) => {
+            report(error);
+            finish();
+        });
+        handle = {
+            async close() {
+                const server = await ready.catch(() => undefined);
+                await server?.close();
+            },
+        };
+    }
+    else {
+        handle = serveStdio(factory, options.onerror ? { transport, onerror: options.onerror } : { transport });
+        // serveStdio 가 onclose 를 동기적으로 설정한 뒤 감싼다 (stdin 이벤트는 비동기)
+        wrapClose();
+    }
+    return {
+        closed,
+        async close() {
+            await handle.close();
+            finish();
+            await closed;
+        },
+    };
+}
+/** Claude Code channel capability. 선언하면 stdio 기본 era = legacy */
+const CLAUDE_CHANNEL = "claude/channel";
+/** 연결 종료 후 onConnect cleanup 대기 상한 (ms). 넘으면 오류 보고 후 종료 진행 */
+export const CLEANUP_TIMEOUT_MS = 5_000;
+async function waitCleanups(settled, report) {
+    if (settled.size === 0)
+        return;
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve("timeout"), CLEANUP_TIMEOUT_MS);
+        timer.unref?.();
+    });
+    const result = await Promise.race([Promise.all(settled), timeout]);
+    clearTimeout(timer);
+    if (result === "timeout")
+        report(new Error(`mcp.onConnect cleanup did not finish within ${CLEANUP_TIMEOUT_MS}ms`));
+}
+/**
+ * McpServer 인스턴스 하나 = stdio 연결 하나. onConnect 시점: 2025 = notifications/initialized
+ * (initialize 응답 전 알림은 클라이언트가 버릴 수 있음), 2026-07-28 = connect 직후 (handshake 없음).
+ * SDK 가 era 판별용 probe 인스턴스를 버리면 그 인스턴스의 onclose 로 cleanup 된다.
+ * 반환 = 인스턴스 종료 후 (onConnect settle · cleanup 완료) resolve. 시작 전 종료 = 바로 resolve
+ */
+function attachConnection(server, era, onConnect, report) {
+    const inner = server.server;
+    let connected;
+    let resolveDone;
+    const done = new Promise((resolve) => {
+        resolveDone = resolve;
+    });
+    let closed = false;
+    const handlers = new Map();
+    // SDK 가 등록하지 않은 method 만 fallback 으로 온다 (사양 알림은 SDK handler · era 필터가 먼저)
+    inner.fallbackNotificationHandler = async (notification) => {
+        const handler = handlers.get(notification.method);
+        if (!handler)
+            return;
+        const params = (notification.params ?? {});
+        try {
+            await handler(params);
+        }
+        catch (error) {
+            report(error);
+        }
+    };
+    const conn = {
+        era,
+        notify: (method, params) => inner.notification({ method, ...(params !== undefined ? { params } : {}) }),
+        onNotification(method, handler) {
+            handlers.set(method, handler);
+            return () => {
+                if (handlers.get(method) === handler)
+                    handlers.delete(method);
+            };
+        },
+    };
+    const start = () => {
+        if (connected || closed)
+            return;
+        connected = Promise.resolve().then(() => onConnect(conn));
+        connected.catch(report);
+    };
+    const previousClose = inner.onclose;
+    inner.onclose = () => {
+        previousClose?.();
+        if (closed)
+            return;
+        closed = true;
+        if (!connected)
+            return resolveDone();
+        connected
+            .then(async (cleanup) => {
+            if (typeof cleanup === "function")
+                await cleanup();
+        }, () => { })
+            .catch(report)
+            .finally(resolveDone);
+    };
+    if (era === "legacy") {
+        const previousInit = inner.oninitialized;
+        inner.oninitialized = () => {
+            previousInit?.();
+            start();
+        };
+    }
+    else {
+        const connect = server.connect.bind(server);
+        server.connect = async (transport) => {
+            await connect(transport);
+            start();
+        };
+    }
+    return done;
+}
+/**
+ * D4: stdio 모드에서 transport 외의 stdout 쓰기 (console.log · process.stdout.write) 를 stderr 로 돌린다.
+ * 반환된 wire 만 실제 stdout 에 쓴다. 명령어 모듈 import 전에 호출해야 top-level 출력도 막는다.
+ * 자식 프로세스 · fd 1 직접 쓰기 (fs.writeSync(1)) 는 막지 못한다.
+ */
+export function redirectStdout() {
+    const stdout = process.stdout;
+    const original = stdout.write;
+    const toStderr = (...args) => process.stderr.write.apply(process.stderr, args);
+    stdout.write = toStderr;
+    // EPIPE 등은 wire 의 write 콜백으로 transport 에 전달된다. process.stdout 의 미처리 error 로 죽지 않게
+    const ignore = () => { };
+    stdout.on("error", ignore);
+    const wire = new Writable({
+        write(chunk, _encoding, callback) {
+            const write = original;
+            write.call(stdout, chunk, (error) => callback(error ?? null));
+        },
+    });
+    let restored = false;
+    return {
+        wire,
+        restore() {
+            if (restored)
+                return;
+            restored = true;
+            if (stdout.write === toStderr)
+                stdout.write = original;
+            stdout.off("error", ignore);
+        },
+    };
+}
+//# sourceMappingURL=stdio.js.map

package/dist/mcp/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../../src/mcp/stdio.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Readable } from \"node:stream\"\nimport { Writable } from \"node:stream\"\nimport type { McpServer, McpServerFactory } from \"@modelcontextprotocol/server\"\nimport { serveStdio, StdioServerTransport } from \"@modelcontextprotocol/server/stdio\"\nimport type { MextApp } from \"../command.ts\"\nimport type { McpCapabilities, McpConnectHandler, McpConnection } from \"../config.ts\"\nimport { localPrincipal, type Principal } from \"../principal.ts\"\nimport type { Registry } from \"../registry.ts\"\nimport type { Instrumentation } from \"../instrumentation.ts\"\nimport type { ToolExposure } from \"./dispatch.ts\"\nimport { createMcpServerFactory, type McpCoreOptions } from \"./server.ts\"\n\nexport interface McpStdioOptions {\n  registry: Registry\n  app?: () => MextApp | Promise<MextApp>\n  tools?: ToolExposure\n  /** serverInfo.name. 기본 \"mext\" */\n  name?: string\n  /** initialize · server/discover 결과 instructions */\n  instructions?: string\n  /** 서버 capabilities 에 병합 (experimental) */\n  capabilities?: McpCapabilities\n  /**\n   * 연결 하나에 1회 (2025 = notifications/initialized 후, 2026-07-28 = 연결 직후).\n   * conn.notify = 요청과 무관한 서버 발신 알림. 반환 함수 = 연결 종료 시 cleanup. 예외 = onerror\n   */\n  onConnect?: McpConnectHandler\n  /**\n   * auto = 2026-07-28 · 2025 모두 (SDK serveStdio 가 판별). legacy = 2025 만:\n   * server/discover = -32601 → 클라이언트가 initialize 로 재시도 (Claude Code channel 은 2025 연결에서만 전달).\n   * 기본 = capabilities.experimental[\"claude/channel\"] 선언 시 legacy, 그 외 auto\n   */\n  era?: \"auto\" | \"legacy\"\n  /** 연결 주체 (로컬 모드). 기본 localPrincipal() */\n  principal?: Principal\n  /** 기본 process.stdin */\n  stdin?: Readable\n  /**\n   * MCP 메시지 출력. 기본 process.stdout.\n   * D4: process.stdout 을 쓰는 경우 redirectStdout() 의 wire 를 넘겨 핸들러 출력이 메시지와 섞이지 않게 한다\n   */\n  stdout?: Writable\n  /** 응답에 영향 없는 오류 보고 (SDK 내부 오류 · 깨진 메시지) */\n  onerror?: (error: Error) => void\n  /** MRTR requestState 서명 키 (createMcpServerFactory 와 같음) */\n  requestStateKey?: McpCoreOptions[\"requestStateKey\"]\n  /** 주기 progress 간격 (ms). 0 = 끔 */\n  progressInterval?: number\n  /** loadInstrumentation 결과 (onCommandError · span, transport = \"stdio\") */\n  instrumentation?: Instrumentation\n  /** _meta[\"dev.mext/manifestHash\"]. McpCoreOptions.manifestHash (기본 = registry 로 계산) */\n  manifestHash?: string\n}\n\nexport interface McpStdioServer {\n  /** stdin EOF · stdout 오류 · close() 로 연결이 끝나면 resolve */\n  closed: Promise<void>\n  close(): Promise<void>\n}\n\n/**\n * MCP stdio (2026-07-28 · 2025 레거시 모두 SDK serveStdio). 줄 단위 JSON-RPC, 연결 하나 = McpServer 하나.\n * notifications/cancelled → ctx.signal abort (SDK). stdin EOF = 연결 종료, 진행 중 요청은 abort 되고 응답하지 않는다.\n * 헤더 검증 · Origin · 바인딩 · Authorization 은 해당 없음. 주체 = 로컬 (kind local).\n */\nexport function serveMcpStdio(options: McpStdioOptions): McpStdioServer {\n  const core = createMcpServerFactory({\n    registry: options.registry,\n    principal: options.principal ?? localPrincipal(),\n    ...(options.app ? { app: options.app } : {}),\n    ...(options.tools ? { tools: options.tools } : {}),\n    ...(options.name ? { name: options.name } : {}),\n    ...(options.instructions !== undefined ? { instructions: options.instructions } : {}),\n    ...(options.capabilities ? { capabilities: options.capabilities } : {}),\n    ...(options.requestStateKey !== undefined ? { requestStateKey: options.requestStateKey } : {}),\n    ...(options.progressInterval !== undefined ? { progressInterval: options.progressInterval } : {}),\n    ...(options.instrumentation ? { instrumentation: options.instrumentation } : {}),\n    ...(options.manifestHash !== undefined ? { manifestHash: options.manifestHash } : {}),\n    transport: \"stdio\",\n  })\n  const onConnect = options.onConnect\n  const report = (error: unknown): void => options.onerror?.(error instanceof Error ? error : new Error(String(error)))\n  /** 인스턴스별 정리 완료 (onConnect settle + cleanup). closed 는 이것들을 기다린다 */\n  const settled = new Set<Promise<void>>()\n  const factory: McpServerFactory = onConnect\n    ? async (ctx) => {\n        const server = (await core(ctx)) as McpServer\n        settled.add(attachConnection(server, ctx.era, onConnect, report))\n        return server\n      }\n    : core\n  const transport = new StdioServerTransport(options.stdin, options.stdout)\n  let resolveClosed!: () => void\n  const closed = new Promise<void>((resolve) => {\n    resolveClosed = resolve\n  })\n  let finishing = false\n  const finish = (): void => {\n    if (finishing) return\n    finishing = true\n    void waitCleanups(settled, report).then(resolveClosed)\n  }\n  const wrapClose = (): void => {\n    const sdkOnClose = transport.onclose\n    transport.onclose = () => {\n      try {\n        sdkOnClose?.()\n      } finally {\n        finish()\n      }\n    }\n  }\n  let handle: { close(): Promise<void> }\n  const era = options.era ?? (options.capabilities?.experimental?.[CLAUDE_CHANNEL] !== undefined ? \"legacy\" : \"auto\")\n  if (era === \"legacy\") {\n    // serveStdio 는 server/discover 를 받으면 2026-07-28 로 고정한다 → 우회.\n    // SDK 기본 supportedProtocolVersions = 2025 버전만 → McpServer 생성자가 server/discover 를 등록하지 않는다\n    const ready = Promise.resolve(factory({ era: \"legacy\" } as Parameters<McpServerFactory>[0])).then(async (product) => {\n      const server = product as McpServer\n      server.server.onerror = report\n      await server.connect(transport)\n      wrapClose()\n      return server\n    })\n    ready.catch((error: unknown) => {\n      report(error)\n      finish()\n    })\n    handle = {\n      async close() {\n        const server = await ready.catch(() => undefined)\n        await server?.close()\n      },\n    }\n  } else {\n    handle = serveStdio(factory, options.onerror ? { transport, onerror: options.onerror } : { transport })\n    // serveStdio 가 onclose 를 동기적으로 설정한 뒤 감싼다 (stdin 이벤트는 비동기)\n    wrapClose()\n  }\n  return {\n    closed,\n    async close() {\n      await handle.close()\n      finish()\n      await closed\n    },\n  }\n}\n\n/** Claude Code channel capability. 선언하면 stdio 기본 era = legacy */\nconst CLAUDE_CHANNEL = \"claude/channel\"\n\n/** 연결 종료 후 onConnect cleanup 대기 상한 (ms). 넘으면 오류 보고 후 종료 진행 */\nexport const CLEANUP_TIMEOUT_MS = 5_000\n\nasync function waitCleanups(settled: ReadonlySet<Promise<void>>, report: (error: unknown) => void): Promise<void> {\n  if (settled.size === 0) return\n  let timer: ReturnType<typeof setTimeout> | undefined\n  const timeout = new Promise<\"timeout\">((resolve) => {\n    timer = setTimeout(() => resolve(\"timeout\"), CLEANUP_TIMEOUT_MS)\n    timer.unref?.()\n  })\n  const result = await Promise.race([Promise.all(settled), timeout])\n  clearTimeout(timer)\n  if (result === \"timeout\") report(new Error(`mcp.onConnect cleanup did not finish within ${CLEANUP_TIMEOUT_MS}ms`))\n}\n\n/**\n * McpServer 인스턴스 하나 = stdio 연결 하나. onConnect 시점: 2025 = notifications/initialized\n * (initialize 응답 전 알림은 클라이언트가 버릴 수 있음), 2026-07-28 = connect 직후 (handshake 없음).\n * SDK 가 era 판별용 probe 인스턴스를 버리면 그 인스턴스의 onclose 로 cleanup 된다.\n * 반환 = 인스턴스 종료 후 (onConnect settle · cleanup 완료) resolve. 시작 전 종료 = 바로 resolve\n */\nfunction attachConnection(\n  server: McpServer,\n  era: McpConnection[\"era\"],\n  onConnect: McpConnectHandler,\n  report: (error: unknown) => void,\n): Promise<void> {\n  const inner = server.server\n  let connected: Promise<unknown> | undefined\n  let resolveDone!: () => void\n  const done = new Promise<void>((resolve) => {\n    resolveDone = resolve\n  })\n  let closed = false\n  const handlers = new Map<string, (params: Record<string, unknown>) => void | Promise<void>>()\n  // SDK 가 등록하지 않은 method 만 fallback 으로 온다 (사양 알림은 SDK handler · era 필터가 먼저)\n  inner.fallbackNotificationHandler = async (notification) => {\n    const handler = handlers.get(notification.method)\n    if (!handler) return\n    const params = (notification.params ?? {}) as Record<string, unknown>\n    try {\n      await handler(params)\n    } catch (error) {\n      report(error)\n    }\n  }\n  const conn: McpConnection = {\n    era,\n    notify: (method, params) => inner.notification({ method, ...(params !== undefined ? { params } : {}) } as never),\n    onNotification(method, handler) {\n      handlers.set(method, handler)\n      return () => {\n        if (handlers.get(method) === handler) handlers.delete(method)\n      }\n    },\n  }\n  const start = (): void => {\n    if (connected || closed) return\n    connected = Promise.resolve().then(() => onConnect(conn))\n    connected.catch(report)\n  }\n  const previousClose = inner.onclose\n  inner.onclose = () => {\n    previousClose?.()\n    if (closed) return\n    closed = true\n    if (!connected) return resolveDone()\n    connected\n      .then(async (cleanup) => {\n        if (typeof cleanup === \"function\") await cleanup()\n      }, () => {})\n      .catch(report)\n      .finally(resolveDone)\n  }\n  if (era === \"legacy\") {\n    const previousInit = inner.oninitialized\n    inner.oninitialized = () => {\n      previousInit?.()\n      start()\n    }\n  } else {\n    const connect = server.connect.bind(server)\n    server.connect = async (transport) => {\n      await connect(transport)\n      start()\n    }\n  }\n  return done\n}\n\nexport interface StdoutRedirect {\n  /** 원래 process.stdout 으로 쓰는 스트림. MCP transport 전용 */\n  wire: Writable\n  /** process.stdout.write 원복 */\n  restore(): void\n}\n\n/**\n * D4: stdio 모드에서 transport 외의 stdout 쓰기 (console.log · process.stdout.write) 를 stderr 로 돌린다.\n * 반환된 wire 만 실제 stdout 에 쓴다. 명령어 모듈 import 전에 호출해야 top-level 출력도 막는다.\n * 자식 프로세스 · fd 1 직접 쓰기 (fs.writeSync(1)) 는 막지 못한다.\n */\nexport function redirectStdout(): StdoutRedirect {\n  const stdout = process.stdout\n  const original = stdout.write\n  const toStderr = (...args: unknown[]): boolean =>\n    (process.stderr.write as (...a: unknown[]) => boolean).apply(process.stderr, args)\n  stdout.write = toStderr as typeof stdout.write\n  // EPIPE 등은 wire 의 write 콜백으로 transport 에 전달된다. process.stdout 의 미처리 error 로 죽지 않게\n  const ignore = (): void => {}\n  stdout.on(\"error\", ignore)\n  const wire = new Writable({\n    write(chunk: Buffer | string, _encoding, callback) {\n      const write = original as (chunk: Buffer | string, done: (error?: Error | null) => void) => boolean\n      write.call(stdout, chunk, (error) => callback(error ?? null))\n    },\n  })\n  let restored = false\n  return {\n    wire,\n    restore() {\n      if (restored) return\n      restored = true\n      if (stdout.write === (toStderr as typeof stdout.write)) stdout.write = original\n      stdout.off(\"error\", ignore)\n    },\n  }\n}\n"]}

package/dist/principal.d.ts

@@ -0,0 +1,16 @@
+/** 요청 주체. 서버가 요청마다 생성 (HTTP · CLI 원격), 로컬 · stdio = kind local */
+export interface Principal {
+    /** "local:obov" | "user_123" | "anonymous" */
+    id: string;
+    kind: "local" | "token" | "anonymous";
+    /** "*" = 전체 */
+    scopes: string[];
+    /** 검증된 토큰 내용. 토큰 원문은 포함하지 않는다 */
+    claims?: Record<string, unknown>;
+}
+/** 인증 없는 주체. scopes 없음 → readOnly 명령어만 */
+export declare const ANONYMOUS: Principal;
+/** 로컬 · stdio 실행의 기본 주체: { id: "local:<OS 사용자>", kind: "local", scopes: ["*"] } */
+export declare function localPrincipal(user?: string): Principal;
+/** "*" = 전체 */
+export declare function hasScope(principal: Principal, scope: string): boolean;

package/dist/principal.js

@@ -0,0 +1,24 @@
+import { userInfo } from "node:os";
+/** 인증 없는 주체. scopes 없음 → readOnly 명령어만 */
+export const ANONYMOUS = Object.freeze({
+    id: "anonymous",
+    kind: "anonymous",
+    scopes: Object.freeze([]),
+});
+/** 로컬 · stdio 실행의 기본 주체: { id: "local:<OS 사용자>", kind: "local", scopes: ["*"] } */
+export function localPrincipal(user = osUser()) {
+    return { id: `local:${user}`, kind: "local", scopes: ["*"] };
+}
+/** "*" = 전체 */
+export function hasScope(principal, scope) {
+    return principal.scopes.includes("*") || principal.scopes.includes(scope);
+}
+function osUser() {
+    try {
+        return userInfo().username;
+    }
+    catch {
+        return process.env.USER ?? process.env.USERNAME ?? "unknown";
+    }
+}
+//# sourceMappingURL=principal.js.map

package/dist/principal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal.js","sourceRoot":"","sources":["../src/principal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAalC,0CAA0C;AAC1C,MAAM,CAAC,MAAM,SAAS,GAAc,MAAM,CAAC,MAAM,CAAC;IAChD,EAAE,EAAE,WAAW;IACf,IAAI,EAAE,WAAW;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAwB;CACjD,CAAc,CAAA;AAEf,mFAAmF;AACnF,MAAM,UAAU,cAAc,CAAC,IAAI,GAAW,MAAM,EAAE;IACpD,OAAO,EAAE,EAAE,EAAE,SAAS,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAA;AAC9D,CAAC;AAED,eAAe;AACf,MAAM,UAAU,QAAQ,CAAC,SAAoB,EAAE,KAAa;IAC1D,OAAO,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;AAC3E,CAAC;AAED,SAAS,MAAM;IACb,IAAI,CAAC;QACH,OAAO,QAAQ,EAAE,CAAC,QAAQ,CAAA;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,SAAS,CAAA;IAC9D,CAAC;AACH,CAAC","sourcesContent":["import { userInfo } from \"node:os\"\n\n/** 요청 주체. 서버가 요청마다 생성 (HTTP · CLI 원격), 로컬 · stdio = kind local */\nexport interface Principal {\n  /** \"local:obov\" | \"user_123\" | \"anonymous\" */\n  id: string\n  kind: \"local\" | \"token\" | \"anonymous\"\n  /** \"*\" = 전체 */\n  scopes: string[]\n  /** 검증된 토큰 내용. 토큰 원문은 포함하지 않는다 */\n  claims?: Record<string, unknown>\n}\n\n/** 인증 없는 주체. scopes 없음 → readOnly 명령어만 */\nexport const ANONYMOUS: Principal = Object.freeze({\n  id: \"anonymous\",\n  kind: \"anonymous\",\n  scopes: Object.freeze([]) as unknown as string[],\n}) as Principal\n\n/** 로컬 · stdio 실행의 기본 주체: { id: \"local:<OS 사용자>\", kind: \"local\", scopes: [\"*\"] } */\nexport function localPrincipal(user: string = osUser()): Principal {\n  return { id: `local:${user}`, kind: \"local\", scopes: [\"*\"] }\n}\n\n/** \"*\" = 전체 */\nexport function hasScope(principal: Principal, scope: string): boolean {\n  return principal.scopes.includes(\"*\") || principal.scopes.includes(scope)\n}\n\nfunction osUser(): string {\n  try {\n    return userInfo().username\n  } catch {\n    return process.env.USER ?? process.env.USERNAME ?? \"unknown\"\n  }\n}\n"]}

package/dist/registry.d.ts

@@ -0,0 +1,90 @@
+import { type Command } from "./command.ts";
+import { type BuildIssue } from "./errors.ts";
+export type JsonSchema = Record<string, unknown>;
+export interface RegistryCommandInput {
+    /** 정식 ID. 점 구분 kebab-case 세그먼트 */
+    id: string;
+    command: Command;
+    /** commands/ 기준 상대 경로 (posix). 스캔 결과에만 있음 */
+    file?: string;
+}
+export interface RegistryNamespaceInput {
+    /** "" = 루트 */
+    id: string;
+    description?: string;
+}
+export interface RegistryInput {
+    commands: readonly RegistryCommandInput[];
+    namespaces?: readonly RegistryNamespaceInput[];
+}
+export interface RegisteredCommand {
+    id: string;
+    /**
+     * 메타데이터 (description · 안전성 · scopes · examples · positional · aliases) 의 원본.
+     * eager (createRegistry) = 실행 가능한 명령어 그대로. lazy (createLazyRegistry) = manifest 로 만든 메타데이터만
+     * (input · execute 는 load() 결과에서)
+     */
+    command: Command;
+    /** lazy Registry: 명령어 모듈 import (1회 캐시) → 실행 가능한 명령어. 없음 = command 가 실행 가능. loadCommand 로 호출 */
+    load?: () => Promise<Command>;
+    /** 별칭의 전체 ID (정렬) */
+    aliases: readonly string[];
+    file: string | undefined;
+    /** input 의 JSON Schema 2020-12 (io: input) */
+    inputSchema: JsonSchema;
+    /** output 의 JSON Schema 2020-12 (io: output) */
+    outputSchema: JsonSchema | undefined;
+}
+export interface NamespaceInfo {
+    /** "" = 루트 */
+    id: string;
+    /** _index.md 내용 */
+    description: string | undefined;
+    /** 직속 명령어 정식 ID (정렬). index.ts 명령어 (네임스페이스와 같은 ID) 는 상위 네임스페이스에 속한다 */
+    commands: readonly string[];
+    /** 직속 하위 네임스페이스 ID (정렬) */
+    namespaces: readonly string[];
+}
+export interface Registry {
+    /** 정식 ID → 명령어. ID 순 */
+    readonly commands: ReadonlyMap<string, RegisteredCommand>;
+    /** 별칭 전체 ID → 정식 ID */
+    readonly aliases: ReadonlyMap<string, string>;
+    /** 네임스페이스 ID → 정보. 루트 ("") 포함, ID 순 */
+    readonly namespaces: ReadonlyMap<string, NamespaceInfo>;
+}
+/** 명령어 목록에서 Registry 생성. ID · 별칭 · 스키마 규칙 위반은 MextBuildError */
+export declare function createRegistry(input: RegistryInput): Registry;
+/**
+ * createRegistry 의 수집형 (mext build 의 일괄 검증용). 던지지 않는다.
+ * registry = 규칙을 통과한 명령어만, issues = 위반 전부
+ */
+export declare function collectRegistry(input: RegistryInput): {
+    registry: Registry;
+    issues: BuildIssue[];
+};
+/** lazy Registry 의 명령어: manifest 메타데이터 + 모듈 로더 (규칙 검증은 mext build 가 이미 함) */
+export interface LazyCommandInput {
+    id: string;
+    /** 메타데이터만 있는 명령어 (input · execute 는 load 결과). RegisteredCommand.command */
+    command: Command;
+    /** 별칭의 전체 ID */
+    aliases: readonly string[];
+    file?: string;
+    inputSchema: JsonSchema;
+    outputSchema?: JsonSchema;
+    /** 실행 시 1회 호출 (결과 캐시, 실패는 다음 호출에서 재시도) */
+    load: () => Promise<Command>;
+}
+/**
+ * manifest (mext build 산출) 로 Registry 생성. 명령어 모듈을 import 하지 않는다 (mext start · handler.js).
+ * help · tools/list · UNKNOWN_COMMAND · 권한 검사 = 메타데이터만, 입력 검증 · execute = loadCommand 후
+ */
+export declare function createLazyRegistry(input: {
+    commands: readonly LazyCommandInput[];
+    namespaces?: readonly RegistryNamespaceInput[];
+}): Registry;
+/** 실행 가능한 명령어. eager = entry.command, lazy = entry.load() (모듈 import) */
+export declare function loadCommand(entry: RegisteredCommand): Promise<Command>;
+/** 정식 ID 또는 별칭으로 명령어 찾기 */
+export declare function resolveCommand(registry: Registry, id: string): RegisteredCommand | undefined;

package/dist/registry.js

@@ -0,0 +1,169 @@
+import * as z from "zod";
+import { isCommand } from "./command.js";
+import { MextBuildError } from "./errors.js";
+import { isSegment, parentNamespace, RESERVED_ROOT_SEGMENTS } from "./ids.js";
+/** 명령어 목록에서 Registry 생성. ID · 별칭 · 스키마 규칙 위반은 MextBuildError */
+export function createRegistry(input) {
+    const { registry, issues } = collectRegistry(input);
+    if (issues.length > 0)
+        throw new MextBuildError(issues);
+    return registry;
+}
+/**
+ * createRegistry 의 수집형 (mext build 의 일괄 검증용). 던지지 않는다.
+ * registry = 규칙을 통과한 명령어만, issues = 위반 전부
+ */
+export function collectRegistry(input) {
+    const issues = [];
+    const accepted = [];
+    const seen = new Map();
+    for (const entry of input.commands) {
+        const where = { id: entry.id, file: entry.file };
+        if (!isCommand(entry.command)) {
+            issues.push({ code: "INVALID_COMMAND", message: "not a defineCommand result", ...where });
+            continue;
+        }
+        const segments = entry.id.split(".");
+        const bad = segments.find((s) => !isSegment(s));
+        if (bad !== undefined) {
+            issues.push({ code: "INVALID_SEGMENT", message: `segment "${bad}" is not kebab-case`, ...where });
+            continue;
+        }
+        if (RESERVED_ROOT_SEGMENTS.includes(segments[0])) {
+            issues.push({ code: "RESERVED_ID", message: `root segment "${segments[0]}" is reserved`, ...where });
+            continue;
+        }
+        const prev = seen.get(entry.id);
+        if (prev) {
+            issues.push({ code: "DUPLICATE_ID", message: `duplicate ID (also ${prev.file ?? prev.id})`, ...where });
+            continue;
+        }
+        seen.set(entry.id, entry);
+        accepted.push(entry);
+    }
+    // 네임스페이스 = 명령어 ID 의 모든 상위 경로
+    const namespaceIds = new Set([""]);
+    for (const { id } of accepted) {
+        for (let ns = parentNamespace(id); ns !== ""; ns = parentNamespace(ns))
+            namespaceIds.add(ns);
+    }
+    const aliases = new Map();
+    const aliasesOf = new Map();
+    for (const entry of accepted) {
+        const where = { id: entry.id, file: entry.file };
+        const parent = parentNamespace(entry.id);
+        const own = [];
+        for (const alias of entry.command.aliases) {
+            if (!isSegment(alias)) {
+                issues.push({ code: "INVALID_ALIAS", message: `alias "${alias}" is not a kebab-case segment`, ...where });
+                continue;
+            }
+            if (parent === "") {
+                issues.push({ code: "INVALID_ALIAS", message: `alias "${alias}": aliases are not allowed at the root`, ...where });
+                continue;
+            }
+            const full = `${parent}.${alias}`;
+            const owner = seen.has(full) ? full : aliases.get(full);
+            if (owner !== undefined || namespaceIds.has(full)) {
+                issues.push({
+                    code: "DUPLICATE_ID",
+                    message: `alias ${full} duplicates ${owner !== undefined ? owner : "a namespace"}`,
+                    ...where,
+                });
+                continue;
+            }
+            aliases.set(full, entry.id);
+            own.push(full);
+        }
+        aliasesOf.set(entry.id, own.sort());
+    }
+    const commands = new Map();
+    for (const entry of [...accepted].sort((a, b) => compareIds(a.id, b.id))) {
+        const where = { id: entry.id, file: entry.file };
+        let inputSchema;
+        let outputSchema;
+        try {
+            inputSchema = toJsonSchema(entry.command.input, "input");
+            outputSchema = entry.command.output ? toJsonSchema(entry.command.output, "output") : undefined;
+        }
+        catch (error) {
+            issues.push({ code: "SCHEMA_UNREPRESENTABLE", message: errorMessage(error), ...where });
+            continue;
+        }
+        commands.set(entry.id, {
+            id: entry.id,
+            command: entry.command,
+            aliases: aliasesOf.get(entry.id) ?? [],
+            file: entry.file,
+            inputSchema,
+            outputSchema,
+        });
+    }
+    const namespaces = namespaceTable(namespaceIds, [...commands.keys()], input.namespaces);
+    return { registry: { commands, aliases, namespaces }, issues };
+}
+/**
+ * manifest (mext build 산출) 로 Registry 생성. 명령어 모듈을 import 하지 않는다 (mext start · handler.js).
+ * help · tools/list · UNKNOWN_COMMAND · 권한 검사 = 메타데이터만, 입력 검증 · execute = loadCommand 후
+ */
+export function createLazyRegistry(input) {
+    const commands = new Map();
+    const aliases = new Map();
+    for (const entry of [...input.commands].sort((a, b) => compareIds(a.id, b.id))) {
+        const load = entry.load;
+        let pending;
+        commands.set(entry.id, {
+            id: entry.id,
+            command: entry.command,
+            aliases: [...entry.aliases].sort(),
+            file: entry.file,
+            inputSchema: entry.inputSchema,
+            outputSchema: entry.outputSchema,
+            load: () => (pending ??= load().catch((error) => {
+                pending = undefined;
+                throw error;
+            })),
+        });
+        for (const alias of entry.aliases)
+            aliases.set(alias, entry.id);
+    }
+    const namespaceIds = new Set([""]);
+    for (const id of commands.keys()) {
+        for (let ns = parentNamespace(id); ns !== ""; ns = parentNamespace(ns))
+            namespaceIds.add(ns);
+    }
+    return { commands, aliases, namespaces: namespaceTable(namespaceIds, [...commands.keys()], input.namespaces) };
+}
+/** 실행 가능한 명령어. eager = entry.command, lazy = entry.load() (모듈 import) */
+export function loadCommand(entry) {
+    return entry.load ? entry.load() : Promise.resolve(entry.command);
+}
+function namespaceTable(namespaceIds, commandIds, inputs) {
+    const descriptions = new Map();
+    for (const ns of inputs ?? [])
+        descriptions.set(ns.id, ns.description);
+    const namespaces = new Map();
+    for (const id of [...namespaceIds].sort(compareIds)) {
+        namespaces.set(id, {
+            id,
+            description: descriptions.get(id),
+            commands: commandIds.filter((c) => parentNamespace(c) === id),
+            namespaces: [...namespaceIds].filter((n) => n !== "" && parentNamespace(n) === id).sort(compareIds),
+        });
+    }
+    return namespaces;
+}
+/** 정식 ID 또는 별칭으로 명령어 찾기 */
+export function resolveCommand(registry, id) {
+    return registry.commands.get(id) ?? registry.commands.get(registry.aliases.get(id) ?? "");
+}
+function toJsonSchema(schema, io) {
+    return z.toJSONSchema(schema, { target: "draft-2020-12", io, unrepresentable: "throw" });
+}
+function compareIds(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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","sourcesContent":["import * as z from \"zod\"\nimport { isCommand, type Command } from \"./command.ts\"\nimport { MextBuildError, type BuildIssue } from \"./errors.ts\"\nimport { isSegment, parentNamespace, RESERVED_ROOT_SEGMENTS } from \"./ids.ts\"\n\nexport type JsonSchema = Record<string, unknown>\n\nexport interface RegistryCommandInput {\n  /** 정식 ID. 점 구분 kebab-case 세그먼트 */\n  id: string\n  command: Command\n  /** commands/ 기준 상대 경로 (posix). 스캔 결과에만 있음 */\n  file?: string\n}\n\nexport interface RegistryNamespaceInput {\n  /** \"\" = 루트 */\n  id: string\n  description?: string\n}\n\nexport interface RegistryInput {\n  commands: readonly RegistryCommandInput[]\n  namespaces?: readonly RegistryNamespaceInput[]\n}\n\nexport interface RegisteredCommand {\n  id: string\n  /**\n   * 메타데이터 (description · 안전성 · scopes · examples · positional · aliases) 의 원본.\n   * eager (createRegistry) = 실행 가능한 명령어 그대로. lazy (createLazyRegistry) = manifest 로 만든 메타데이터만\n   * (input · execute 는 load() 결과에서)\n   */\n  command: Command\n  /** lazy Registry: 명령어 모듈 import (1회 캐시) → 실행 가능한 명령어. 없음 = command 가 실행 가능. loadCommand 로 호출 */\n  load?: () => Promise<Command>\n  /** 별칭의 전체 ID (정렬) */\n  aliases: readonly string[]\n  file: string | undefined\n  /** input 의 JSON Schema 2020-12 (io: input) */\n  inputSchema: JsonSchema\n  /** output 의 JSON Schema 2020-12 (io: output) */\n  outputSchema: JsonSchema | undefined\n}\n\nexport interface NamespaceInfo {\n  /** \"\" = 루트 */\n  id: string\n  /** _index.md 내용 */\n  description: string | undefined\n  /** 직속 명령어 정식 ID (정렬). index.ts 명령어 (네임스페이스와 같은 ID) 는 상위 네임스페이스에 속한다 */\n  commands: readonly string[]\n  /** 직속 하위 네임스페이스 ID (정렬) */\n  namespaces: readonly string[]\n}\n\nexport interface Registry {\n  /** 정식 ID → 명령어. ID 순 */\n  readonly commands: ReadonlyMap<string, RegisteredCommand>\n  /** 별칭 전체 ID → 정식 ID */\n  readonly aliases: ReadonlyMap<string, string>\n  /** 네임스페이스 ID → 정보. 루트 (\"\") 포함, ID 순 */\n  readonly namespaces: ReadonlyMap<string, NamespaceInfo>\n}\n\n/** 명령어 목록에서 Registry 생성. ID · 별칭 · 스키마 규칙 위반은 MextBuildError */\nexport function createRegistry(input: RegistryInput): Registry {\n  const { registry, issues } = collectRegistry(input)\n  if (issues.length > 0) throw new MextBuildError(issues)\n  return registry\n}\n\n/**\n * createRegistry 의 수집형 (mext build 의 일괄 검증용). 던지지 않는다.\n * registry = 규칙을 통과한 명령어만, issues = 위반 전부\n */\nexport function collectRegistry(input: RegistryInput): { registry: Registry; issues: BuildIssue[] } {\n  const issues: BuildIssue[] = []\n  const accepted: RegistryCommandInput[] = []\n  const seen = new Map<string, RegistryCommandInput>()\n\n  for (const entry of input.commands) {\n    const where = { id: entry.id, file: entry.file }\n    if (!isCommand(entry.command)) {\n      issues.push({ code: \"INVALID_COMMAND\", message: \"not a defineCommand result\", ...where })\n      continue\n    }\n    const segments = entry.id.split(\".\")\n    const bad = segments.find((s) => !isSegment(s))\n    if (bad !== undefined) {\n      issues.push({ code: \"INVALID_SEGMENT\", message: `segment \"${bad}\" is not kebab-case`, ...where })\n      continue\n    }\n    if (RESERVED_ROOT_SEGMENTS.includes(segments[0]!)) {\n      issues.push({ code: \"RESERVED_ID\", message: `root segment \"${segments[0]}\" is reserved`, ...where })\n      continue\n    }\n    const prev = seen.get(entry.id)\n    if (prev) {\n      issues.push({ code: \"DUPLICATE_ID\", message: `duplicate ID (also ${prev.file ?? prev.id})`, ...where })\n      continue\n    }\n    seen.set(entry.id, entry)\n    accepted.push(entry)\n  }\n\n  // 네임스페이스 = 명령어 ID 의 모든 상위 경로\n  const namespaceIds = new Set<string>([\"\"])\n  for (const { id } of accepted) {\n    for (let ns = parentNamespace(id); ns !== \"\"; ns = parentNamespace(ns)) namespaceIds.add(ns)\n  }\n\n  const aliases = new Map<string, string>()\n  const aliasesOf = new Map<string, string[]>()\n  for (const entry of accepted) {\n    const where = { id: entry.id, file: entry.file }\n    const parent = parentNamespace(entry.id)\n    const own: string[] = []\n    for (const alias of entry.command.aliases) {\n      if (!isSegment(alias)) {\n        issues.push({ code: \"INVALID_ALIAS\", message: `alias \"${alias}\" is not a kebab-case segment`, ...where })\n        continue\n      }\n      if (parent === \"\") {\n        issues.push({ code: \"INVALID_ALIAS\", message: `alias \"${alias}\": aliases are not allowed at the root`, ...where })\n        continue\n      }\n      const full = `${parent}.${alias}`\n      const owner = seen.has(full) ? full : aliases.get(full)\n      if (owner !== undefined || namespaceIds.has(full)) {\n        issues.push({\n          code: \"DUPLICATE_ID\",\n          message: `alias ${full} duplicates ${owner !== undefined ? owner : \"a namespace\"}`,\n          ...where,\n        })\n        continue\n      }\n      aliases.set(full, entry.id)\n      own.push(full)\n    }\n    aliasesOf.set(entry.id, own.sort())\n  }\n\n  const commands = new Map<string, RegisteredCommand>()\n  for (const entry of [...accepted].sort((a, b) => compareIds(a.id, b.id))) {\n    const where = { id: entry.id, file: entry.file }\n    let inputSchema: JsonSchema\n    let outputSchema: JsonSchema | undefined\n    try {\n      inputSchema = toJsonSchema(entry.command.input, \"input\")\n      outputSchema = entry.command.output ? toJsonSchema(entry.command.output, \"output\") : undefined\n    } catch (error) {\n      issues.push({ code: \"SCHEMA_UNREPRESENTABLE\", message: errorMessage(error), ...where })\n      continue\n    }\n    commands.set(entry.id, {\n      id: entry.id,\n      command: entry.command,\n      aliases: aliasesOf.get(entry.id) ?? [],\n      file: entry.file,\n      inputSchema,\n      outputSchema,\n    })\n  }\n\n  const namespaces = namespaceTable(namespaceIds, [...commands.keys()], input.namespaces)\n  return { registry: { commands, aliases, namespaces }, issues }\n}\n\n/** lazy Registry 의 명령어: manifest 메타데이터 + 모듈 로더 (규칙 검증은 mext build 가 이미 함) */\nexport interface LazyCommandInput {\n  id: string\n  /** 메타데이터만 있는 명령어 (input · execute 는 load 결과). RegisteredCommand.command */\n  command: Command\n  /** 별칭의 전체 ID */\n  aliases: readonly string[]\n  file?: string\n  inputSchema: JsonSchema\n  outputSchema?: JsonSchema\n  /** 실행 시 1회 호출 (결과 캐시, 실패는 다음 호출에서 재시도) */\n  load: () => Promise<Command>\n}\n\n/**\n * manifest (mext build 산출) 로 Registry 생성. 명령어 모듈을 import 하지 않는다 (mext start · handler.js).\n * help · tools/list · UNKNOWN_COMMAND · 권한 검사 = 메타데이터만, 입력 검증 · execute = loadCommand 후\n */\nexport function createLazyRegistry(input: {\n  commands: readonly LazyCommandInput[]\n  namespaces?: readonly RegistryNamespaceInput[]\n}): Registry {\n  const commands = new Map<string, RegisteredCommand>()\n  const aliases = new Map<string, string>()\n  for (const entry of [...input.commands].sort((a, b) => compareIds(a.id, b.id))) {\n    const load = entry.load\n    let pending: Promise<Command> | undefined\n    commands.set(entry.id, {\n      id: entry.id,\n      command: entry.command,\n      aliases: [...entry.aliases].sort(),\n      file: entry.file,\n      inputSchema: entry.inputSchema,\n      outputSchema: entry.outputSchema,\n      load: () =>\n        (pending ??= load().catch((error: unknown) => {\n          pending = undefined\n          throw error\n        })),\n    })\n    for (const alias of entry.aliases) aliases.set(alias, entry.id)\n  }\n  const namespaceIds = new Set<string>([\"\"])\n  for (const id of commands.keys()) {\n    for (let ns = parentNamespace(id); ns !== \"\"; ns = parentNamespace(ns)) namespaceIds.add(ns)\n  }\n  return { commands, aliases, namespaces: namespaceTable(namespaceIds, [...commands.keys()], input.namespaces) }\n}\n\n/** 실행 가능한 명령어. eager = entry.command, lazy = entry.load() (모듈 import) */\nexport function loadCommand(entry: RegisteredCommand): Promise<Command> {\n  return entry.load ? entry.load() : Promise.resolve(entry.command)\n}\n\nfunction namespaceTable(\n  namespaceIds: ReadonlySet<string>,\n  commandIds: readonly string[],\n  inputs: readonly RegistryNamespaceInput[] | undefined,\n): Map<string, NamespaceInfo> {\n  const descriptions = new Map<string, string | undefined>()\n  for (const ns of inputs ?? []) descriptions.set(ns.id, ns.description)\n  const namespaces = new Map<string, NamespaceInfo>()\n  for (const id of [...namespaceIds].sort(compareIds)) {\n    namespaces.set(id, {\n      id,\n      description: descriptions.get(id),\n      commands: commandIds.filter((c) => parentNamespace(c) === id),\n      namespaces: [...namespaceIds].filter((n) => n !== \"\" && parentNamespace(n) === id).sort(compareIds),\n    })\n  }\n  return namespaces\n}\n\n/** 정식 ID 또는 별칭으로 명령어 찾기 */\nexport function resolveCommand(registry: Registry, id: string): RegisteredCommand | undefined {\n  return registry.commands.get(id) ?? registry.commands.get(registry.aliases.get(id) ?? \"\")\n}\n\nfunction toJsonSchema(schema: z.ZodType, io: \"input\" | \"output\"): JsonSchema {\n  return z.toJSONSchema(schema, { target: \"draft-2020-12\", io, unrepresentable: \"throw\" }) as JsonSchema\n}\n\nfunction compareIds(a: string, b: string): number {\n  return a < b ? -1 : a > b ? 1 : 0\n}\n\nfunction errorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error)\n}\n"]}

package/dist/remote/browser.d.ts

@@ -0,0 +1,15 @@
+/**
+ * login 의 브라우저 판정 · 열기 (spec §5 login 브라우저 판정 · headless).
+ * 열지 않음 = SSH 세션 (SSH_CONNECTION · SSH_CLIENT · SSH_TTY) · Linux 에서 DISPLAY · WAYLAND_DISPLAY 없음.
+ * 여는 명령 = BROWSER (있으면) → open (macOS) · start (Windows) · xdg-open.
+ */
+export interface BrowserDecision {
+    open: boolean;
+    /** 열지 않는 이유 (안내 출력용) */
+    reason?: "ssh" | "no-display";
+}
+/** URL 을 브라우저로 연다. 실패는 무시 (URL 은 항상 stderr 에 출력) */
+export type BrowserOpener = (url: string) => void;
+export declare function browserDecision(env: Record<string, string | undefined>, platform?: NodeJS.Platform): BrowserDecision;
+/** 기본 opener. BROWSER = 명령 (공백 구분 인자, %s 가 있으면 URL 로 치환 · 없으면 끝에 URL) */
+export declare function systemBrowserOpener(env: Record<string, string | undefined>, platform?: NodeJS.Platform): BrowserOpener;