@obov/mext 0.0.0-stage → 0.1.0

package/dist/client/runner.js

@@ -0,0 +1,562 @@
+import { COMMAND } from "../command.js";
+import { MextError } from "../errors.js";
+import { isSegment } from "../ids.js";
+import { createRemoteClient, isRecord, RemoteInputRequiredError, RemoteRpcError, RemoteTransportError, RemoteUnauthorizedError, } from "../remote/client.js";
+import { credentialStore, envPrefix } from "../remote/credentials.js";
+import { isExpired, OAuthFlowError, refreshCredentials } from "../remote/oauth.js";
+import { cliSpecFromJsonSchema, coerceValue, defineCliSpec, parseArgs } from "../cli/args.js";
+import { cliPath, renderHelp } from "../cli/help.js";
+import { createLineReader, readAll } from "../cli/io.js";
+import { CliInterrupted, EXIT, errorJson, exitCodeOf, formatError, formatJson, formatProgress, formatResult, } from "../cli/output.js";
+import { MANIFEST_HASH_META_KEY } from "../mcp/constants.js";
+import { VERSION } from "../version.js";
+import { openSchema, schemaCacheDir, schemaCacheFile } from "./cache.js";
+import { manifestHelp } from "./manifest.js";
+export async function runRemote(options, argv, io) {
+    const { url, prog } = options;
+    const tokenEnv = `${envPrefix(options.bin)}_TOKEN`;
+    const ctx = { login: options.login, tokenEnv, auth: undefined, footer: options.rootHelpFooter };
+    const lead = { json: false, yes: false, help: false };
+    let i = 0;
+    for (; i < argv.length; i++) {
+        const tok = argv[i];
+        if (!tok.startsWith("-") || tok === "-")
+            break;
+        if (tok === "--json")
+            lead.json = true;
+        else if (tok === "--yes")
+            lead.yes = true;
+        else if (tok === "--help" || tok === "-h")
+            lead.help = true;
+        else
+            return report(usageError(`unknown flag ${tok} before the command`), io, prog, argv.includes("--json"), ctx);
+    }
+    const rest = argv.slice(i);
+    const beforeDashDash = rest.indexOf("--") < 0 ? rest : rest.slice(0, rest.indexOf("--"));
+    const json = lead.json || beforeDashDash.includes("--json");
+    const controller = new AbortController();
+    const onAbort = () => controller.abort(io.signal?.reason);
+    if (io.signal?.aborted)
+        onAbort();
+    io.signal?.addEventListener("abort", onAbort, { once: true });
+    const lines = createLineReader(io);
+    let session;
+    let schema;
+    try {
+        if (!/^https?:\/\//i.test(url))
+            throw usageError(`--url must be an http(s) URL (got "${url}")`);
+        session = openSession(options, tokenEnv, io, controller.signal);
+        const s = session;
+        schema = await openRunSchema(options, s, ctx, io);
+        const source = schema;
+        const wantsHelp = lead.help || beforeDashDash.includes("--help") || beforeDashDash.includes("-h");
+        let stdin;
+        const readStdin = () => (stdin ??= readAll(io.stdin));
+        // 경로 해석 · 플래그 파싱 (로컬). 실패하면 서버 help 로 1회 재시도
+        const plan = async () => {
+            // <prog> help [target...]
+            if (rest[0] === "help") {
+                const tokens = rest.slice(1).filter((t) => !t.startsWith("-"));
+                const resolved = await resolveRemotePath(source, tokens);
+                if (resolved.consumed < tokens.length)
+                    throw await unknownAt(source, resolved, tokens.slice(resolved.consumed));
+                return { kind: "help", help: resolved.help };
+            }
+            const resolved = await resolveRemotePath(source, rest);
+            const { help, consumed } = resolved;
+            const command = help.kind === "command" ? help : help.kind === "namespace" ? help.command : undefined;
+            const next = rest[consumed];
+            const acceptsPositional = command !== undefined && command.positional.length > 0;
+            if (help.kind !== "command" && next !== undefined && !next.startsWith("-") && !acceptsPositional) {
+                throw await unknownAt(source, resolved, rest.slice(consumed));
+            }
+            if (wantsHelp)
+                return { kind: "help", help };
+            if (!command)
+                return { kind: "namespace", help };
+            const entry = entryFromHelp(command);
+            const parsed = await parseArgs(entry, rest.slice(consumed), { readStdin });
+            return { kind: "run", command, entry, input: parsed.input, yes: parsed.yes };
+        };
+        let planned;
+        try {
+            planned = await plan();
+        }
+        catch (error) {
+            if (!isLocalParseFailure(error) || !schema.refetch())
+                throw error;
+            try {
+                planned = await plan();
+            }
+            catch (retryError) {
+                // 재조회 실패 (오프라인 등) = 원래 로컬 오류
+                if (retryError instanceof RemoteTransportError || retryError instanceof RemoteRpcError)
+                    throw error;
+                throw retryError;
+            }
+        }
+        if (planned.kind === "help")
+            return printHelp(planned.help, io, prog, json, ctx);
+        if (planned.kind === "namespace") {
+            const { help } = planned;
+            const id = help.kind === "namespace" ? help.id : "";
+            const error = new MextError("UNKNOWN_COMMAND", id === "" ? "No command given." : `"${cliPath(id)}" is a namespace. Specify a command.`, { command: id, suggested: [], usage: id === "" ? "help" : `help ${id}` });
+            if (json)
+                return report(error, io, prog, true, ctx);
+            io.stderr.write(formatError(error, prog));
+            io.stderr.write(`\n${helpText(help, prog, ctx)}`);
+            return EXIT.usage;
+        }
+        const { command, entry } = planned;
+        const yes = lead.yes || planned.yes;
+        const tool = commandTool(dispatcherOf(url, await schema.tools()), command);
+        const args = { command: entry.id, args: planned.input };
+        const result = await s.call((o) => s.client.callTool(tool, args, {
+            ...o,
+            progressToken: "mext-cli",
+            onNotification: (method, params) => {
+                if (method !== "notifications/progress" || typeof params.progress !== "number")
+                    return;
+                const update = { progress: params.progress };
+                if (typeof params.total === "number")
+                    update.total = params.total;
+                if (typeof params.message === "string")
+                    update.message = params.message;
+                io.stderr.write(formatProgress(update));
+            },
+            onInputRequired: inputHandler(io, lines, yes, entry.id, controller.signal),
+        }));
+        // drift: 이번 결과는 그대로, 다르면 캐시 stale (다음 실행에서 서버 help)
+        schema.observe(metaHash(result));
+        if (result.isError === true)
+            throw toolError(result, ctx);
+        const value = result.structuredContent === undefined ? textValue(result) : result.structuredContent;
+        io.stdout.write(json ? formatJson(value) : formatResult(value));
+        return EXIT.ok;
+    }
+    catch (error) {
+        if (session)
+            ctx.auth = session.auth;
+        if (controller.signal.aborted)
+            return report(new CliInterrupted(), io, prog, json, ctx);
+        return report(error, io, prog, json, ctx);
+    }
+    finally {
+        io.signal?.removeEventListener("abort", onAbort);
+        lines.close();
+        await schema?.save();
+    }
+}
+/** 서버 help 재조회 대상 로컬 오류 */
+function isLocalParseFailure(error) {
+    return error instanceof MextError && (error.code === "UNKNOWN_COMMAND" || error.code === "INVALID_ARGUMENT");
+}
+/** 결과 _meta["dev.mext/manifestHash"] */
+function metaHash(result) {
+    const meta = result._meta;
+    const value = isRecord(meta) ? meta[MANIFEST_HASH_META_KEY] : undefined;
+    return typeof value === "string" ? value : undefined;
+}
+/** 이번 실행의 스키마 상태: 캐시 파일 (<BIN>_CACHE_DIR · XDG · HOME) · 내장 manifest · 서버 help */
+function openRunSchema(options, s, ctx, io) {
+    const dir = schemaCacheDir(options.bin, io.env);
+    return openSchema({
+        file: dir === undefined ? undefined : schemaCacheFile(dir, options.url),
+        url: options.url,
+        client: { bin: options.bin, version: options.version, mext: VERSION },
+        ...(options.manifest && options.manifestHash !== undefined
+            ? { embedded: { manifest: options.manifest, hash: options.manifestHash } }
+            : {}),
+        fetchHelp: serverHelpFetcher(s, ctx),
+        fetchTools: async () => {
+            const r = await s.call((o) => s.client.listToolsResult(o));
+            dispatcherOf(s.url, r.tools);
+            return r.ttlMs === undefined ? { tools: r.tools } : { tools: r.tools, ttlMs: r.ttlMs };
+        },
+        warn: (message) => io.stderr.write(message),
+    });
+}
+/** 네트워크 · 키체인 접근은 첫 요청까지 미룬다 (번들 형태의 help 는 둘 다 없음) */
+function openSession(options, tokenEnv, io, signal) {
+    const { url } = options;
+    const envToken = io.env[tokenEnv] !== undefined && io.env[tokenEnv] !== "" ? io.env[tokenEnv] : undefined;
+    const store = envToken === undefined ? credentialStore({ env: io.env, bin: options.bin }) : undefined;
+    let stored;
+    let auth = envToken !== undefined ? "env" : undefined;
+    let refreshed = false;
+    const refresh = async () => {
+        if (!store || !stored?.refresh_token || refreshed)
+            return false;
+        refreshed = true;
+        try {
+            stored = await refreshCredentials(stored);
+            await store.set(url, stored).catch(() => { });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    let loading;
+    const load = () => (loading ??= (async () => {
+        if (!store)
+            return;
+        stored = await store.get(url).catch(() => undefined);
+        if (stored && isExpired(stored))
+            await refresh();
+        auth = stored ? "stored" : "none";
+    })());
+    const client = createRemoteClient({
+        url,
+        clientInfo: { name: options.bin, version: options.version },
+        token: async () => {
+            await load();
+            return envToken ?? stored?.access_token;
+        },
+    });
+    const call = async (fn) => {
+        try {
+            return await fn({ signal });
+        }
+        catch (error) {
+            if (error instanceof RemoteUnauthorizedError && (await refresh()))
+                return fn({ signal });
+            throw error;
+        }
+    };
+    return {
+        url,
+        client,
+        get auth() {
+            return auth;
+        },
+        call,
+    };
+}
+/** tools/list 결과 → dispatcher 도구 (execute 또는 query · mutate). 없으면 RemoteTransportError */
+function dispatcherOf(url, list) {
+    const execute = list.find((t) => t.name === "execute");
+    const query = list.find((t) => t.name === "query");
+    const helpTool = execute ?? query;
+    if (!helpTool || (!execute && !list.some((t) => t.name === "mutate"))) {
+        throw new RemoteTransportError(`${url} does not expose mext dispatcher tools (execute, or query and mutate).`);
+    }
+    return { list, helpTool };
+}
+/** 명령어를 호출할 도구: help 의 tool (split) → execute → readOnly 면 query, 아니면 mutate */
+function commandTool(tools, command) {
+    const byName = (name) => (name === undefined ? undefined : tools.list.find((t) => t.name === name));
+    return byName(command.tool) ?? byName("execute") ?? byName(command.readOnly ? "query" : "mutate") ?? tools.helpTool;
+}
+/** 서버의 dispatcher help (tools/call). UNKNOWN_COMMAND = 캐시할 결과, 그 외 오류 = throw */
+function serverHelpFetcher(s, ctx) {
+    return async (target, tools) => {
+        const { helpTool } = dispatcherOf(s.url, await tools());
+        const args = target === "" ? { command: "help" } : { command: "help", args: { target } };
+        const result = await s.call((o) => s.client.callTool(helpTool, args, o));
+        const hash = metaHash(result);
+        if (result.isError === true) {
+            const error = toolError(result, ctx);
+            if (error instanceof MextError && error.code === "UNKNOWN_COMMAND")
+                return { value: { error: error.toJSON() }, hash };
+            throw error;
+        }
+        const value = result.structuredContent;
+        if (!isRecord(value) || (value.kind !== "root" && value.kind !== "namespace" && value.kind !== "command")) {
+            throw new RemoteTransportError(`${s.url} returned an unexpected help result.`);
+        }
+        return { value: { help: value }, hash };
+    };
+}
+/** 번들 형태: 내장 manifest (네트워크 없음) */
+export function manifestHelpSource(manifest) {
+    return { help: async (target) => manifestHelp(manifest, target) };
+}
+async function resolveRemotePath(source, tokens) {
+    const segs = [];
+    for (const t of tokens) {
+        if (!isSegment(t))
+            break;
+        segs.push(t);
+    }
+    let unknown;
+    for (let k = segs.length; k >= 0; k--) {
+        try {
+            return { help: await source.help(segs.slice(0, k).join(".")), consumed: k, unknown };
+        }
+        catch (error) {
+            if (k > 0 && error instanceof MextError && error.code === "UNKNOWN_COMMAND") {
+                unknown ??= error;
+                continue;
+            }
+            throw error;
+        }
+    }
+    throw new Error("unreachable");
+}
+/** 해석되지 않은 경로 → UNKNOWN_COMMAND (suggested · usage) */
+async function unknownAt(source, resolved, tail) {
+    if (resolved.unknown)
+        return resolved.unknown;
+    const id = resolved.help.kind === "root" ? "" : resolved.help.id;
+    const first = tail.find((t) => !t.startsWith("-"));
+    const candidate = [id, first ?? ""].filter((x) => x !== "").join(".");
+    try {
+        await source.help(candidate);
+    }
+    catch (error) {
+        if (error instanceof MextError)
+            return error;
+        throw error;
+    }
+    return new MextError("UNKNOWN_COMMAND", `Unknown command "${candidate}".`, { command: candidate, suggested: [], usage: "help" });
+}
+/* help → 로컬 렌더러용 Registry (같은 help 텍스트) */
+/** 원격 명령어의 input 자리. CLI 필드는 defineCliSpec (JSON Schema 분석) 이 정하므로 Zod 스키마가 필요 없다 */
+const REMOTE_INPUT = { _zod: { def: { shape: {} } } };
+function commandOf(meta) {
+    return {
+        [COMMAND]: true,
+        description: meta.description,
+        input: REMOTE_INPUT,
+        output: undefined,
+        readOnly: meta.readOnly,
+        destructive: meta.destructive,
+        requiresConfirmation: meta.requiresConfirmation,
+        scopes: [...(meta.scopes ?? [])],
+        examples: [...(meta.examples ?? [])],
+        positional: [...(meta.positional ?? [])],
+        aliases: [],
+        execute() {
+            throw new Error("remote command");
+        },
+    };
+}
+/** 원격 명령어 help → RegisteredCommand (CLI 필드 = inputSchema 분석) */
+export function entryFromHelp(help) {
+    const entry = {
+        id: help.id,
+        command: commandOf(help),
+        aliases: [...help.aliases],
+        file: undefined,
+        inputSchema: help.inputSchema,
+        outputSchema: help.outputSchema,
+    };
+    defineCliSpec(entry, cliSpecFromJsonSchema(help.inputSchema, help.positional));
+    return entry;
+}
+function registryFromHelp(help) {
+    const commands = new Map();
+    const aliases = new Map();
+    const namespaces = new Map();
+    if (help.kind === "command") {
+        const entry = entryFromHelp(help);
+        commands.set(entry.id, entry);
+        for (const a of entry.aliases)
+            aliases.set(a, entry.id);
+        namespaces.set("", { id: "", description: undefined, commands: [], namespaces: [] });
+        return { commands, aliases, namespaces };
+    }
+    const id = help.kind === "root" ? "" : help.id;
+    namespaces.set(id, {
+        id,
+        description: help.description,
+        commands: help.commands.map((c) => c.id),
+        namespaces: help.namespaces.map((n) => n.id),
+    });
+    for (const n of help.namespaces)
+        namespaces.set(n.id, { id: n.id, description: n.description, commands: [], namespaces: [] });
+    for (const c of help.commands) {
+        commands.set(c.id, {
+            id: c.id,
+            command: commandOf(c),
+            aliases: [],
+            file: undefined,
+            inputSchema: {},
+            outputSchema: undefined,
+        });
+    }
+    if (help.kind === "namespace" && help.command)
+        commands.set(help.command.id, entryFromHelp(help.command));
+    return { commands, aliases, namespaces };
+}
+/** 사람용 help 텍스트. 루트면 footer (고객 CLI 내장 명령) 를 붙인다 */
+function helpText(help, prog, ctx) {
+    const target = help.kind === "root" ? "" : help.id;
+    const text = renderHelp(registryFromHelp(help), target, { prog });
+    return help.kind === "root" && ctx.footer ? `${text}\n${ctx.footer}` : text;
+}
+/** --help --json = help 결과 그대로 (서버 help 의 structuredContent · 내장 manifest help) */
+function printHelp(help, io, prog, json, ctx) {
+    io.stdout.write(json ? formatJson(help) : helpText(help, prog, ctx));
+    return EXIT.ok;
+}
+/* 결과 · 오류 */
+const MEXT_CODES = [
+    "UNKNOWN_COMMAND",
+    "INVALID_ARGUMENT",
+    "UNAUTHENTICATED",
+    "PERMISSION_DENIED",
+    "INPUT_UNAVAILABLE",
+];
+/** 서버 핸들러 예외 등 mext 구조화 오류 외의 도구 오류. --json = 서버 오류 본문 그대로, exit 1 */
+export class RemoteExecutionError extends Error {
+    body;
+    constructor(body) {
+        super(typeof body.message === "string" ? body.message : "Remote command failed.");
+        this.name = "RemoteExecutionError";
+        this.body = body;
+    }
+}
+/** isError 결과 → MextError (code 가 mext 구조화 오류면) 또는 RemoteExecutionError */
+function toolError(result, ctx) {
+    const sc = result.structuredContent;
+    const body = isRecord(sc) && isRecord(sc.error) ? sc.error : undefined;
+    if (!body)
+        return new RemoteExecutionError({ code: "EXECUTION_FAILED", message: textValue(result) ?? "Remote command failed." });
+    const { code, message, ...details } = body;
+    if (typeof code === "string" && MEXT_CODES.includes(code)) {
+        const text = typeof message === "string" ? message : code;
+        if (code === "UNAUTHENTICATED") {
+            return new MextError("UNAUTHENTICATED", text, { ...details, login: ctx.login });
+        }
+        return new MextError(code, text, details);
+    }
+    return new RemoteExecutionError(body);
+}
+function textValue(result) {
+    const texts = (result.content ?? []).flatMap((c) => isRecord(c) && c.type === "text" && typeof c.text === "string" ? [c.text] : []);
+    return texts.length > 0 ? texts.join("\n") : undefined;
+}
+/** 401 → UNAUTHENTICATED (login 안내 포함) */
+function unauthenticatedFrom(error, ctx) {
+    const data = isRecord(error.data) ? error.data : {};
+    const reason = data.reason === "invalid_token" || data.reason === "missing_token"
+        ? data.reason
+        : error.challenge.error === "invalid_token"
+            ? "invalid_token"
+            : "missing_token";
+    let message = typeof data.message === "string" ? data.message : error.message;
+    if (ctx.auth === "env")
+        message += ` ${ctx.tokenEnv} was rejected.`;
+    return new MextError("UNAUTHENTICATED", message, { reason, login: ctx.login });
+}
+function report(error, io, prog, json, ctx) {
+    let e = error;
+    if (e instanceof RemoteUnauthorizedError)
+        e = unauthenticatedFrom(e, ctx);
+    if (json) {
+        io.stderr.write(formatJson(errorBody(e)));
+        return exitCodeOf(e);
+    }
+    io.stderr.write(formatError(e, prog));
+    if (e instanceof MextError && e.code === "PERMISSION_DENIED" && ctx.auth === "none") {
+        const reason = e.details.reason;
+        if (reason === "anonymous")
+            io.stderr.write(`Run "${ctx.login}" to log in.\n`);
+    }
+    return exitCodeOf(e);
+}
+function errorBody(error) {
+    if (error instanceof RemoteExecutionError)
+        return error.body;
+    if (error instanceof RemoteTransportError ||
+        error instanceof RemoteRpcError ||
+        error instanceof RemoteInputRequiredError ||
+        error instanceof OAuthFlowError) {
+        const body = { code: "REMOTE_ERROR", message: error.message };
+        if (error instanceof RemoteRpcError)
+            body.rpc = { code: error.code, status: error.status, data: error.data };
+        return body;
+    }
+    return errorJson(error);
+}
+function usageError(message) {
+    return new MextError("INVALID_ARGUMENT", message, {
+        command: "",
+        missing_fields: [],
+        issues: [{ path: "", code: "unknown_flag", message }],
+        expected_schema: {},
+        examples: [],
+    });
+}
+/* MRTR: InputRequiredResult → 프롬프트 → inputResponses */
+/**
+ * elicitation/create (form) 만 처리 (clientCapabilities = elicitation.form).
+ * requestedSchema 가 boolean 속성 하나 = 확인: --yes → 승인, TTY → [y/N], 그 외 INPUT_UNAVAILABLE.
+ * 그 외 form = TTY 에서 필드별 입력 (스키마 모양으로 변환), TTY 없음 = INPUT_UNAVAILABLE.
+ * 응답 = { action: "accept", content }. 이번 라운드 요청에 대한 응답만 보낸다
+ */
+function inputHandler(io, lines, yes, command, signal) {
+    const unavailable = (message, hint) => new MextError("INPUT_UNAVAILABLE", `${command} asked "${message}", but stdin is not a terminal.${hint}`, { command });
+    const ask = async (prompt) => {
+        const answer = await lines.question(prompt, signal);
+        if (signal.aborted)
+            throw new CliInterrupted();
+        return answer ?? "";
+    };
+    return async (required) => {
+        const out = {};
+        for (const [key, request] of Object.entries(required.inputRequests ?? {})) {
+            const params = isRecord(request.params) ? request.params : {};
+            const message = typeof params.message === "string" ? params.message : "Input required";
+            if (request.method !== "elicitation/create") {
+                throw new RemoteTransportError(`${command}: unsupported input request ${request.method}.`);
+            }
+            if (params.mode === "url") {
+                if (!io.isTTY)
+                    throw unavailable(message, " Run it in an interactive terminal.");
+                await ask(`${message}\n  ${String(params.url)}\nPress Enter when done. `);
+                out[key] = { action: "accept" };
+                continue;
+            }
+            const schema = isRecord(params.requestedSchema) ? params.requestedSchema : { type: "object", properties: {} };
+            const confirmKey = confirmField(schema);
+            if (confirmKey !== undefined) {
+                if (yes) {
+                    out[key] = { action: "accept", content: { [confirmKey]: true } };
+                    continue;
+                }
+                if (!io.isTTY)
+                    throw unavailable(message, " Pass --yes to approve.");
+                const answer = await ask(`${message} [y/N] `);
+                out[key] = { action: "accept", content: { [confirmKey]: /^y(es)?$/i.test(answer.trim()) } };
+                continue;
+            }
+            if (!io.isTTY)
+                throw unavailable(message, " Run it in an interactive terminal.");
+            io.stderr.write(`${message}\n`);
+            const spec = cliSpecFromJsonSchema(schema);
+            const content = {};
+            for (const f of spec.fields) {
+                const answer = await ask(`  ${f.key}${f.required ? "" : " (optional)"}: `);
+                if (answer === "")
+                    continue;
+                if (f.kind.type === "array") {
+                    const kind = f.kind;
+                    content[f.key] = answer.split(",").map((s) => {
+                        const r = coerceValue(kind, s.trim());
+                        return r.ok ? r.value : s;
+                    });
+                    continue;
+                }
+                const r = coerceValue(f.kind, answer);
+                content[f.key] = r.ok ? r.value : answer;
+            }
+            out[key] = { action: "accept", content };
+        }
+        return out;
+    };
+}
+/** requestedSchema 의 속성이 boolean 하나면 그 키 (확인 요청) */
+function confirmField(schema) {
+    const props = schema.properties;
+    if (!isRecord(props))
+        return undefined;
+    const keys = Object.keys(props);
+    if (keys.length !== 1)
+        return undefined;
+    const p = props[keys[0]];
+    return isRecord(p) && p.type === "boolean" ? keys[0] : undefined;
+}
+//# sourceMappingURL=runner.js.map