@obov/mext 0.5.0 → 0.7.1

package/dist/cli/inspect.js

@@ -0,0 +1,699 @@
+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 { basename, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { entryFromHelp } from "../client/runner.js";
+import { CallError } from "../client/typed.js";
+import { isMextError } from "../errors.js";
+import { parentNamespace } from "../ids.js";
+import { createInspector, InspectUsageError, outcomeOf, resolveTarget, } from "../inspect/inspector.js";
+import { isAgentClient } from "../inspect/agent.js";
+import { resolveAudit } from "../inspect/audit.js";
+import { startUiServer, UI_DEFAULT_PORT } from "../inspect/ui-server.js";
+import { findProfile, INSPECT_DIR, loadProfiles, PROFILES_FILE, ProfileFileError } from "../inspect/profiles.js";
+import { appendStep, listErrorBody, loadScenario, runScenario, ScenarioFileError, scenarioFiles, stepFromRecord, } from "../inspect/scenario.js";
+import { parseArgs } from "./args.js";
+import { table } from "./help.js";
+import { readAll } from "./io.js";
+import { EXIT, formatError, formatJson, formatProgress, formatResult } from "./output.js";
+export const INSPECT_PROG = "mext inspect";
+const VALUE_FLAGS = ["url", "profiles", "as", "answers", "save", "port", "agent", "name"];
+const BOOLEAN_FLAGS = ["json", "confirmed", "decline", "raw", "bail"];
+/** 하위 명령별로 받는 플래그 (공통 제외) */
+const SUBCOMMAND_FLAGS = {
+    commands: [],
+    show: [],
+    call: ["confirmed", "decline", "raw", "answers", "save"],
+    run: ["bail", "agent"],
+    profiles: [],
+    ui: ["port", "agent"],
+    "mcp-config": ["name"],
+};
+const COMMON_FLAGS = ["url", "profiles", "as", "json"];
+class UsageError extends Error {
+}
+export async function inspectCommand(argv, io) {
+    const json = argv.includes("--json");
+    try {
+        return await run(argv, io);
+    }
+    catch (error) {
+        if (error instanceof UsageError) {
+            io.stderr.write(`error: ${error.message}\nRun "${INSPECT_PROG} --help" for usage.\n`);
+            return EXIT.usage;
+        }
+        if (error instanceof InspectUsageError || error instanceof ProfileFileError || error instanceof ScenarioFileError) {
+            io.stderr.write(`error: ${error.message}\n`);
+            return EXIT.usage;
+        }
+        if (isMextError(error, "INVALID_ARGUMENT")) {
+            const lines = formatError(error, INSPECT_PROG).trimEnd().split("\n");
+            if (lines.at(-1)?.startsWith("Run "))
+                lines[lines.length - 1] = `Run "${INSPECT_PROG} show ${error.details.command}" for the input schema.`;
+            io.stderr.write(`${lines.join("\n")}\n`);
+            return EXIT.usage;
+        }
+        const body = listErrorBody(error);
+        io.stderr.write(json ? formatJson(body) : `error: ${body.code}: ${body.message}\n`);
+        return EXIT.error;
+    }
+}
+async function run(argv, io) {
+    const flags = { json: false, help: false, confirmed: false, decline: false, raw: false, bail: false };
+    const given = new Set();
+    const positionals = [];
+    /** call 의 <id> 뒤 = 명령어 입력 (mext run 과 같은 플래그). inspect 플래그는 <id> 앞에 둔다 */
+    let inputArgv = [];
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        if (tok === "--help" || tok === "-h") {
+            flags.help = true;
+            continue;
+        }
+        if (!tok.startsWith("--")) {
+            positionals.push(tok);
+            if (positionals[0] === "call" && positionals.length === 2) {
+                inputArgv = argv.slice(i + 1);
+                break;
+            }
+            continue;
+        }
+        const eq = tok.indexOf("=");
+        const name = tok.slice(2, eq < 0 ? undefined : eq);
+        given.add(name);
+        if (BOOLEAN_FLAGS.includes(name) && eq < 0) {
+            flags[name] = true;
+            continue;
+        }
+        if (!VALUE_FLAGS.includes(name))
+            throw new UsageError(`unknown flag --${name}`);
+        const value = eq < 0 ? argv[++i] : tok.slice(eq + 1);
+        if (value === undefined || value === "")
+            throw new UsageError(`--${name} requires a value`);
+        if (name === "as") {
+            flags.as = value
+                .split(",")
+                .map((s) => s.trim())
+                .filter((s) => s !== "");
+        }
+        else if (name === "answers")
+            flags.answers = parseAnswers(value);
+        else
+            flags[name] = value;
+    }
+    const [sub, ...args] = positionals;
+    if (sub === undefined || sub === "help") {
+        (flags.help || sub === "help" ? io.stdout : io.stderr).write(inspectHelp());
+        return flags.help || sub === "help" ? EXIT.ok : EXIT.usage;
+    }
+    if (flags.help) {
+        io.stdout.write(inspectHelp());
+        return EXIT.ok;
+    }
+    const allowed = SUBCOMMAND_FLAGS[sub];
+    if (!allowed)
+        throw new UsageError(`unknown subcommand "${sub}" (commands · show · call · run · profiles · ui · mcp-config)`);
+    for (const name of given) {
+        if (!COMMON_FLAGS.includes(name) && !allowed.includes(name))
+            throw new UsageError(`--${name} is not a flag of "${INSPECT_PROG} ${sub}"`);
+    }
+    const profiles = loadProfiles(io.cwd, { ...(flags.profiles !== undefined ? { file: flags.profiles } : {}), env: io.env });
+    if (sub === "profiles") {
+        if (args.length > 0)
+            throw new UsageError(`unexpected argument "${args[0]}"`);
+        return printProfiles(profiles, io, flags.json);
+    }
+    const target = resolveTarget({ ...(flags.url !== undefined ? { url: flags.url } : {}), env: io.env, cwd: io.cwd });
+    if (sub === "ui") {
+        if (args.length > 0)
+            throw new UsageError(`unexpected argument "${args[0]}"`);
+        if (flags.as || flags.json)
+            throw new UsageError(`--${flags.as ? "as" : "json"} is not a flag of "${INSPECT_PROG} ui" (pick profiles in the page)`);
+        return ui(target, profiles, flags, io);
+    }
+    // run = 감사 이벤트를 비교한다 (expect.audit · agent 단계): 대상이 이 프로젝트의 mext dev 면 감사 출처를 잇는다
+    if (sub === "mcp-config") {
+        if (args.length > 0)
+            throw new UsageError(`unexpected argument "${args[0]}"`);
+        return mcpConfig(target, profiles, flags, io);
+    }
+    const audit = sub === "run" ? resolveAudit(target, io.cwd) : undefined;
+    const inspector = createInspector({ url: target.url, profiles, env: io.env, ...(audit?.available ? { audit: audit.source } : {}) });
+    // 이름 확인 (없는 프로필 = 사용법 오류)
+    const names = (flags.as ?? [profiles.default]).map((name) => inspector.profile(name).name);
+    if (names.length === 0)
+        throw new UsageError("--as requires at least one profile name");
+    switch (sub) {
+        case "commands": {
+            if (args.length > 1)
+                throw new UsageError(`unexpected argument "${args[1]}"`);
+            return commands(inspector, target, names, args[0], io, flags.json);
+        }
+        case "show": {
+            if (args.length !== 1)
+                throw new UsageError(`usage: ${INSPECT_PROG} show <id>`);
+            return show(inspector, names, args[0], io, flags.json);
+        }
+        case "call": {
+            if (args.length !== 1)
+                throw new UsageError(`usage: ${INSPECT_PROG} call [flags] <id> [input flags]`);
+            return call(inspector, names, args[0], inputArgv, flags, io);
+        }
+        default: {
+            if (flags.as && flags.as.length > 1)
+                throw new UsageError("--as takes one profile for run (steps name their own profile with \"as\")");
+            try {
+                return await runScenarios(inspector, profiles, args, flags, io);
+            }
+            finally {
+                inspector.close();
+            }
+        }
+    }
+}
+function parseAnswers(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new UsageError('--answers must be JSON, e.g. \'{"confirm": true, "form": {"reason": "ok"}}\'');
+    }
+    if (!isRecord(value))
+        throw new UsageError("--answers must be a JSON object");
+    const out = {};
+    for (const [key, v] of Object.entries(value)) {
+        if (key === "confirm" || key === "url") {
+            if (typeof v !== "boolean")
+                throw new UsageError(`--answers ${key} must be true or false`);
+            out[key] = v;
+        }
+        else if (key === "form") {
+            if (v !== false && !isRecord(v))
+                throw new UsageError("--answers form must be an object or false");
+            out.form = v;
+        }
+        else
+            throw new UsageError(`--answers: unknown key "${key}" (confirm · form · url)`);
+    }
+    return out;
+}
+/* profiles */
+function printProfiles(profiles, io, json) {
+    const inspector = createInspector({ url: "http://unused.invalid/mcp", profiles, env: io.env });
+    const views = inspector.profiles();
+    if (json) {
+        io.stdout.write(formatJson({ file: profiles.file ?? null, default: profiles.default, profiles: views }));
+        return EXIT.ok;
+    }
+    const source = profiles.file ? shown(io.cwd, profiles.file) : `built-in (no ${INSPECT_DIR}/${PROFILES_FILE})`;
+    const rows = views.map((p) => [
+        `${p.default ? "*" : " "} ${p.name}`,
+        p.token ? `${p.token.env} (${p.token.set ? "set" : "not set"})` : "-",
+        p.headers.map((h) => (h.env ? `${h.name}=$${h.env}${h.set ? "" : " (not set)"}` : `${h.name}=${h.value}`)).join(", ") || "-",
+        p.description ?? "",
+    ]);
+    io.stdout.write(`Profiles: ${source}\n${table([["  NAME", "TOKEN", "HEADERS", "DESCRIPTION"], ...rows]).join("\n")}\n`);
+    return EXIT.ok;
+}
+/* mcp-config */
+/**
+ * 에이전트 (Happy 봇) 가 이 서버를 MCP 서버로 쓰게 하는 설정 스니펫 (mcp.toml 형식, §3). 출력만 한다 (파일을 쓰지 않는다).
+ * 토큰 = 환경변수 이름 (bearer_token_env_var). 값은 읽지도 출력하지도 않는다
+ */
+function mcpConfig(target, profiles, flags, io) {
+    if (!flags.as || flags.as.length !== 1) {
+        throw new UsageError(`"${INSPECT_PROG} mcp-config" needs --as <profile>: the profile whose token the agent will use (profiles: ${profiles.profiles.map((p) => p.name).join(", ")})`);
+    }
+    const profile = findProfile(profiles, flags.as[0]);
+    if (!profile)
+        throw new UsageError(`Unknown profile "${flags.as[0]}". Profiles: ${profiles.profiles.map((p) => p.name).join(", ")}`);
+    const name = flags.name ?? (basename(resolve(io.cwd)).replace(/[^A-Za-z0-9_-]+/g, "_") || "mext");
+    const fixed = Object.entries(profile.headers).filter((entry) => typeof entry[1] === "string");
+    const fromEnv = Object.entries(profile.headers).flatMap(([header, value]) => (typeof value === "string" ? [] : [{ name: header, env: value.env }]));
+    const key = /^[A-Za-z0-9_-]+$/.test(name) ? name : JSON.stringify(name);
+    const entry = [
+        `[mcp_servers.${key}]`,
+        `url = ${JSON.stringify(target.url)}`,
+        ...(profile.token ? [`bearer_token_env_var = ${JSON.stringify(profile.token.env)}`] : []),
+        ...(fixed.length > 0 ? [`http_headers = { ${fixed.map(([header, value]) => `${JSON.stringify(header)} = ${JSON.stringify(value)}`).join(", ")} }`] : []),
+    ];
+    if (flags.json) {
+        io.stdout.write(formatJson({
+            name,
+            profile: profile.name,
+            url: target.url,
+            bearerTokenEnvVar: profile.token?.env ?? null,
+            httpHeaders: Object.fromEntries(fixed),
+            skippedHeaders: fromEnv,
+            toml: `${entry.join("\n")}\n`,
+        }));
+        return EXIT.ok;
+    }
+    const lines = [
+        `# MCP server entry for a Happy Agent bot, calling as profile "${profile.name}" (${INSPECT_PROG} mcp-config).`,
+        "# 1. Add it to the mcp.toml in the bot's folder (for example ~/Happy/Bots/<bot>/mcp.toml). This command does not write that file.",
+        profile.token
+            ? `# 2. The Happy daemon reads the token from its own environment: ${profile.token.env} must be set where the daemon runs (not only in this shell).`
+            : "# 2. This profile has no token: the bot calls the server anonymously.",
+        "# 3. Ask the bot to reload its MCP servers.",
+        ...entry,
+        ...fromEnv.map((h) => `# Not included: header ${h.name} comes from $${h.env} in this profile, and mcp.toml headers are fixed values only.`),
+        ...(target.source === "dev" ? [`# This URL is this project's mext dev server. Keep the port fixed (mext dev --port ${new URL(target.url).port}) so the entry stays valid.`] : []),
+    ];
+    io.stdout.write(`${lines.join("\n")}\n`);
+    return EXIT.ok;
+}
+async function listFor(inspector, names, namespace) {
+    const out = [];
+    for (const profile of names) {
+        try {
+            const list = await inspector.commands(profile);
+            out.push({ profile, ok: true, list: namespace === undefined ? list : within(list, namespace) });
+        }
+        catch (error) {
+            out.push({ profile, ok: false, error: listErrorBody(error) });
+        }
+    }
+    return out;
+}
+function within(list, namespace) {
+    const inside = (id) => id === namespace || id.startsWith(`${namespace}.`);
+    return { ...list, namespaces: list.namespaces.filter((n) => inside(n.id)), commands: list.commands.filter((c) => inside(c.id)) };
+}
+async function commands(inspector, target, names, namespace, io, json) {
+    const listings = await listFor(inspector, names, namespace);
+    const failed = listings.some((l) => !l.ok);
+    if (names.length === 1) {
+        const only = listings[0];
+        if (!only.ok) {
+            io.stderr.write(json ? formatJson(only.error) : `error: ${only.error.code}: ${only.error.message}\n`);
+            return EXIT.error;
+        }
+        if (json) {
+            io.stdout.write(formatJson(only.list));
+            return EXIT.ok;
+        }
+        io.stdout.write(`${targetLine(target)} · as ${only.profile}\n\n${commandLines(only.list)}`);
+        return EXIT.ok;
+    }
+    if (json) {
+        io.stdout.write(formatJson(listings));
+        return failed ? EXIT.error : EXIT.ok;
+    }
+    const ids = [...new Set(listings.flatMap((l) => (l.ok ? l.list.commands.map((c) => c.id) : [])))].sort();
+    const rows = ids.map((id) => [id, ...listings.map((l) => (l.ok ? (l.list.commands.some((c) => c.id === id) ? "visible" : "hidden") : l.error.code))]);
+    io.stdout.write(`${targetLine(target)}\n\n${table([["", ...names], ...rows]).join("\n")}\n`);
+    for (const l of listings)
+        if (!l.ok)
+            io.stderr.write(`${l.profile}: ${l.error.code}: ${l.error.message}\n`);
+    return failed ? EXIT.error : EXIT.ok;
+}
+function targetLine(target) {
+    return `${target.url}${target.source === "dev" ? " (mext dev)" : ""}`;
+}
+/** 네임스페이스별 명령어 + 안전성 */
+function commandLines(list) {
+    if (list.commands.length === 0)
+        return "(no commands visible to this profile)\n";
+    const groups = new Map();
+    for (const c of list.commands) {
+        const ns = parentNamespace(c.id);
+        groups.set(ns, [...(groups.get(ns) ?? []), c]);
+    }
+    const rows = [];
+    const heads = new Set();
+    for (const [ns, items] of [...groups].sort(([a], [b]) => a.localeCompare(b))) {
+        heads.add(rows.length);
+        rows.push([ns === "" ? "(root)" : ns, "", list.namespaces.find((n) => n.id === ns)?.description ?? ""]);
+        for (const c of items)
+            rows.push([`  ${c.id}`, safetyOf(c).join(", "), c.description]);
+    }
+    const lines = table(rows);
+    return `${lines.map((l, i) => (heads.has(i) && i > 0 ? `\n${l}` : l)).join("\n")}\n`;
+}
+/** 안전성 표시 (mext run --help 의 Safety 줄과 같은 말) */
+export function safetyOf(c) {
+    const out = [c.readOnly ? "read-only" : "writes"];
+    if (c.destructive)
+        out.push("destructive");
+    if (c.requiresConfirmation)
+        out.push("requires confirmation");
+    else if (c.needsApproval === "conditional")
+        out.push("may require confirmation");
+    return out;
+}
+/* show */
+async function show(inspector, names, id, io, json) {
+    let info;
+    const visibleTo = {};
+    let firstError;
+    for (const profile of names) {
+        try {
+            const found = await inspector.describe(id, profile);
+            info ??= found;
+            visibleTo[profile] = true;
+        }
+        catch (error) {
+            if (!(error instanceof CallError && error.code === "UNKNOWN_COMMAND") && names.length === 1)
+                throw error;
+            firstError ??= error;
+            visibleTo[profile] = false;
+        }
+    }
+    if (!info)
+        throw firstError;
+    if (json) {
+        io.stdout.write(formatJson(names.length === 1 ? info : { ...info, visibleTo }));
+        return EXIT.ok;
+    }
+    const safety = safetyOf(info);
+    const rows = [
+        ["Safety", safety.join(", ")],
+        ["Approval", info.requiresConfirmation ? "required" : info.needsApproval === "conditional" ? "conditional" : "none"],
+        ["Scopes", info.scopes.join(", ") || "(none)"],
+    ];
+    if (info.aliases.length > 0)
+        rows.push(["Aliases", info.aliases.join(", ")]);
+    if (info.tool !== undefined)
+        rows.push(["Tool", info.tool]);
+    if (info.task)
+        rows.push(["Task", `ttl ${info.task.ttlMs}ms`]);
+    if (info.errors.length > 0)
+        rows.push(["Errors", info.errors.join(", ")]);
+    if (names.length > 1)
+        rows.push(["Visible to", names.map((n) => `${n} ${visibleTo[n] ? "yes" : "no"}`).join(" · ")]);
+    const out = [`${info.id} — ${info.description}`, "", ...table(rows), "", "Input schema:", indent(JSON.stringify(info.inputSchema, null, 2))];
+    if (info.outputSchema)
+        out.push("", "Output schema:", indent(JSON.stringify(info.outputSchema, null, 2)));
+    if (info.examples.length > 0)
+        out.push("", "Examples:", ...info.examples.map((e) => `  ${JSON.stringify(e)}`));
+    io.stdout.write(`${out.join("\n")}\n`);
+    return EXIT.ok;
+}
+/* call */
+async function call(inspector, names, id, inputArgv, flags, io) {
+    const parsed = await parseInput(inspector, names, id, inputArgv, io);
+    if (parsed.help)
+        return show(inspector, names, id, io, flags.json || parsed.json);
+    const json = flags.json || parsed.json;
+    const confirmed = flags.confirmed || parsed.yes;
+    const records = [];
+    for (const profile of names) {
+        records.push(await inspector.call(id, parsed.input, {
+            profile,
+            ...(confirmed ? { confirmed: true } : {}),
+            ...(flags.answers ? { answers: flags.answers } : {}),
+            ...(flags.decline ? { decline: true } : {}),
+            ...(io.signal ? { signal: io.signal } : {}),
+            onProgress: (update) => {
+                const line = formatProgress({ ...update, progress: update.progress ?? 0 });
+                io.stderr.write(names.length > 1 ? `${profile}: ${line}` : line);
+            },
+        }));
+    }
+    if (flags.save !== undefined) {
+        const file = resolve(io.cwd, flags.save);
+        let count = 0;
+        for (const record of records) {
+            count = appendStep(file, stepFromRecord(record, { ...(flags.answers ? { answers: flags.answers } : {}), ...(flags.decline ? { decline: true } : {}) }));
+        }
+        io.stderr.write(`Saved ${records.length === 1 ? "step" : `${records.length} steps`} to ${shown(io.cwd, file)} (${count} step${count === 1 ? "" : "s"})\n`);
+    }
+    const failed = records.some((r) => !r.ok);
+    if (json) {
+        io.stdout.write(formatJson(records.map((r) => ({
+            profile: r.profile,
+            ...outcomeOf(r),
+            durationMs: r.durationMs,
+            ...(r.task ? { task: r.task } : {}),
+            ...(flags.raw ? { exchanges: r.exchanges } : {}),
+        }))));
+        return failed ? EXIT.error : EXIT.ok;
+    }
+    const blocks = records.map((r) => {
+        const lines = [recordLine(r)];
+        const body = r.ok ? formatResult(r.value).trimEnd() : JSON.stringify(r.error, null, 2);
+        if (body !== "")
+            lines.push(indent(body));
+        if (flags.raw) {
+            lines.push("  Requests:");
+            for (const x of r.exchanges) {
+                lines.push(`  → ${x.request.method} ${x.request.url}${x.rpc ? ` ${x.rpc}` : ""} (${x.response ? x.response.status : (x.error ?? "no response")}, ${x.durationMs}ms)`);
+                lines.push(indent(JSON.stringify({ request: x.request, response: x.response }, null, 2), 4));
+            }
+        }
+        return lines.join("\n");
+    });
+    io.stdout.write(`${blocks.join("\n\n")}\n`);
+    return failed ? EXIT.error : EXIT.ok;
+}
+/** 한 줄 요약: ✓ posts.get as editor (12ms) · ✗ posts.publish as agent (8ms) APPROVAL_REQUIRED (human_required) */
+function recordLine(r) {
+    const head = `${r.ok ? "✓" : "✗"} ${r.command} as ${r.profile} (${r.durationMs}ms)`;
+    if (r.ok || !r.error)
+        return head;
+    return `${head} ${r.error.code}${typeof r.error.reason === "string" ? ` (${r.error.reason})` : ""}`;
+}
+/**
+ * <id> 뒤 argv → 입력. 스키마 = 이 명령어가 보이는 첫 프로필의 것 (mext run 과 같은 플래그 해석).
+ * 어느 프로필에도 보이지 않으면 (숨긴 명령어를 호출해 보는 경우) --input-json 만 받는다
+ */
+async function parseInput(inspector, names, id, argv, io) {
+    let info;
+    for (const profile of names) {
+        try {
+            info = await inspector.describe(id, profile);
+            break;
+        }
+        catch {
+            // 다음 프로필
+        }
+    }
+    if (info) {
+        const entry = entryFromHelp({ ...info, kind: "command" });
+        const parsed = await parseArgs(entry, argv, { readStdin: () => readAll(io.stdin) });
+        return { input: isRecord(parsed.input) ? parsed.input : {}, json: parsed.json, yes: parsed.yes, help: parsed.help };
+    }
+    const out = { input: {}, json: false, yes: false, help: false };
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        if (tok === "--json")
+            out.json = true;
+        else if (tok === "--yes")
+            out.yes = true;
+        else if (tok === "--help" || tok === "-h")
+            out.help = true;
+        else if (tok === "--input-json" || tok.startsWith("--input-json=")) {
+            const text = tok === "--input-json" ? argv[++i] : tok.slice("--input-json=".length);
+            let value;
+            try {
+                value = JSON.parse(text === "-" ? await readAll(io.stdin) : (text ?? ""));
+            }
+            catch {
+                throw new UsageError("--input-json must be a JSON object");
+            }
+            if (!isRecord(value))
+                throw new UsageError("--input-json must be a JSON object");
+            out.input = value;
+        }
+        else {
+            throw new UsageError(`"${id}" is not visible to ${names.join(", ")}, so its flags are unknown. Pass the input with --input-json '<json>'`);
+        }
+    }
+    return out;
+}
+/* run */
+async function runScenarios(inspector, profiles, paths, flags, io) {
+    const scenarios = scenarioFiles(io.cwd, paths).map((file) => loadScenario(file, profiles));
+    const needsAgent = scenarios.some((scenario) => scenario.steps.some((step) => "agent" in step));
+    if (needsAgent && flags.agent === undefined) {
+        throw new UsageError('these scenarios have "agent" steps: pass --agent <module> (a module whose default export is an AgentClient, or a function that makes one)');
+    }
+    const agent = flags.agent !== undefined ? await loadAgent(flags.agent, io) : undefined;
+    try {
+        return await runLoaded(inspector, scenarios, agent, flags, io);
+    }
+    finally {
+        await agent?.close?.().catch(() => { });
+    }
+}
+/** --agent <모듈>: default export = AgentClient, 또는 그것을 만드는 함수 ({ cwd, env }) */
+async function loadAgent(path, io) {
+    const file = resolve(io.cwd, path);
+    if (!existsSync(file))
+        throw new UsageError(`--agent: ${shown(io.cwd, file)} not found`);
+    const module = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href)));
+    const plugin = module.default;
+    let client = plugin;
+    if (typeof plugin === "function") {
+        try {
+            client = await plugin({ cwd: io.cwd, env: io.env });
+        }
+        catch (error) {
+            // 설정이 빠진 plugin (환경변수 등) = 사용법 오류
+            throw new UsageError(`--agent: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (!isAgentClient(client)) {
+        throw new UsageError(`--agent: the default export of ${shown(io.cwd, file)} must be an AgentClient ({ connect, send, onEvent }) or a function that returns one`);
+    }
+    return client;
+}
+async function runLoaded(inspector, scenarios, agent, flags, io) {
+    const results = [];
+    for (const scenario of scenarios) {
+        // --as = 시나리오 · 단계가 프로필을 적지 않았을 때의 기본값
+        const effective = scenario.as === undefined && flags.as ? { ...scenario, as: flags.as[0] } : scenario;
+        if (!flags.json)
+            io.stdout.write(`${scenario.name}${scenario.file ? ` (${shown(io.cwd, scenario.file)})` : ""}\n`);
+        const result = await runScenario(inspector, effective, {
+            bail: flags.bail,
+            ...(agent ? { agent } : {}),
+            ...(io.signal ? { signal: io.signal } : {}),
+            onStep: (step) => {
+                if (!flags.json)
+                    io.stdout.write(stepLines(step));
+            },
+        });
+        results.push(result);
+        if (!flags.json && result.steps.length < scenario.steps.length) {
+            io.stdout.write(`  (stopped: ${scenario.steps.length - result.steps.length} step(s) not run)\n`);
+        }
+    }
+    const pass = results.every((r) => r.pass);
+    if (flags.json) {
+        io.stdout.write(formatJson({ pass, scenarios: results }));
+        return pass ? EXIT.ok : EXIT.error;
+    }
+    const steps = results.flatMap((r) => r.steps);
+    const passed = results.filter((r) => r.pass).length;
+    io.stdout.write(`\n${passed}/${results.length} scenario${results.length === 1 ? "" : "s"} passed, ${steps.filter((s) => s.pass).length}/${steps.length} steps passed\n`);
+    return pass ? EXIT.ok : EXIT.error;
+}
+function stepLines(step) {
+    const lines = [`  ${step.pass ? "✓" : "✗"} ${step.step}. ${step.name} (as ${step.as}, ${step.durationMs}ms)`];
+    for (const f of step.failures)
+        lines.push(`      ${f.path}: expected ${JSON.stringify(f.expected)}, got ${JSON.stringify(f.actual)}`);
+    const outcome = step.outcome;
+    if (outcome && "events" in outcome) {
+        // agent 단계: 실패하면 서버가 본 것 (감사 이벤트) 과 에이전트가 한 말을 같이 보여 준다
+        if (!step.pass) {
+            lines.push(`      server saw ${outcome.events.length} call${outcome.events.length === 1 ? "" : "s"} from the agent${outcome.events.length > 0 ? ":" : ""}`);
+            for (const event of outcome.events)
+                lines.push(`        ${event.outcome} ${event.command}${event.error ? ` (${event.error.code})` : ""}`);
+            const said = outcome.messages.at(-1);
+            if (said !== undefined)
+                lines.push(`      agent said: ${said.length > 200 ? `${said.slice(0, 197)}…` : said}`);
+        }
+    }
+    else if (!step.pass && outcome && !outcome.ok)
+        lines.push(`      result: ${outcome.error.code}: ${outcome.error.message}`);
+    return `${lines.join("\n")}\n`;
+}
+/* ui */
+/** 웹 UI (§5): 127.0.0.1 에 페이지 · 중계 API 를 열고 SIGINT 까지 실행 */
+async function ui(target, profiles, flags, io) {
+    const port = flags.port === undefined ? UI_DEFAULT_PORT : Number(flags.port);
+    if (!Number.isInteger(port) || port < 0 || port > 65_535)
+        throw new UsageError("--port must be a port number (0 = any free port)");
+    const audit = resolveAudit(target, io.cwd);
+    const agent = flags.agent !== undefined ? await loadAgent(flags.agent, io) : undefined;
+    const inspector = createInspector({ url: target.url, profiles, env: io.env, ...(audit.available ? { audit: audit.source } : {}) });
+    let server;
+    try {
+        server = await startUiServer({ inspector, target, cwd: io.cwd, port, ...(audit.available ? {} : { auditReason: audit.reason }), ...(agent ? { agent } : {}) });
+    }
+    catch (error) {
+        inspector.close();
+        if (error.code === "EADDRINUSE") {
+            io.stderr.write(`error: port ${port} is in use. Pass --port <n> (0 = any free port).\n`);
+            return EXIT.error;
+        }
+        throw error;
+    }
+    io.stderr.write(`${INSPECT_PROG}: ${server.url}\n` +
+        `  target  ${targetLine(target)}\n` +
+        `  audit   ${audit.available ? "streaming from mext dev" : "not available for this target"}\n` +
+        (agent ? `  agent   ${agent.name ?? "connected on the first agent step"}\n` : "") +
+        "Press Ctrl-C to stop.\n");
+    await new Promise((done) => {
+        if (io.signal?.aborted)
+            return done();
+        io.signal?.addEventListener("abort", () => done(), { once: true });
+    });
+    await server.close();
+    inspector.close();
+    await agent?.close?.().catch(() => { });
+    return EXIT.ok;
+}
+/* help */
+export function inspectHelp() {
+    const lines = [
+        "Inspect a mext server command by command: who (a caller profile) calls what, and what comes back.",
+        "",
+        "Usage:",
+        `  ${INSPECT_PROG} commands [<namespace>]         List commands with safety metadata`,
+        `  ${INSPECT_PROG} show <id>                      One command: safety, approval, scopes, input schema, examples, errors`,
+        `  ${INSPECT_PROG} call [flags] <id> [input]      Call a command (input: --flag value, or --input-json '<json>')`,
+        `  ${INSPECT_PROG} run [<scenario|folder>...]     Run scenario files (default: ${INSPECT_DIR}/scenarios)`,
+        `  ${INSPECT_PROG} profiles                       List caller profiles (values are never printed)`,
+        `  ${INSPECT_PROG} ui [--port <n>] [--agent <m>]  Web UI on http://127.0.0.1:${UI_DEFAULT_PORT} (calls go through this process)`,
+        `  ${INSPECT_PROG} mcp-config --as <profile>      Print the mcp.toml entry that lets an agent (a Happy bot) use this server`,
+        "",
+        "Server: --url <url>, or MEXT_URL, or the mext dev server running in this project.",
+        `Profiles: ${INSPECT_DIR}/${PROFILES_FILE} names tokens and headers by environment variable, e.g.`,
+        '  { "profiles": { "editor": { "token": { "env": "EDITOR_TOKEN" } }, "anonymous": {} } }',
+        "Without the file there is one profile, default (token from MEXT_TOKEN if set).",
+        "",
+        "Flags:",
+        ...table([
+            ["--url <url>", "MCP endpoint of the server to inspect"],
+            ["--profiles <path>", `Profiles file (default: ${INSPECT_DIR}/${PROFILES_FILE})`],
+            ["--as <a>[,<b>...]", "Caller profile. Several = run the same request as each and compare"],
+            ["--json", "Print JSON"],
+            ["-h, --help", "Show help"],
+        ]).map((l) => `  ${l}`),
+        "",
+        `Flags of call (before <id>; everything after <id> is the command's input):`,
+        ...table([
+            ["--confirmed", "Declare that a human confirmed this call (same as --yes after <id>)"],
+            ["--answers <json>", 'Answers for input requests: {"confirm": true, "form": {…}, "url": true}'],
+            ["--decline", "Decline input and confirmation requests"],
+            ["--save <file>", "Append this call and its observed result to a scenario file"],
+            ["--raw", "Also print the raw requests and responses (secrets redacted)"],
+        ]).map((l) => `  ${l}`),
+        "",
+        "Flags of run (--agent also works for ui):",
+        ...table([
+            ["--bail", "Stop a scenario at its first failing step"],
+            ["--agent <module>", 'Agent client for "agent" steps (default export: { connect, send, onEvent })'],
+        ]).map((l) => `  ${l}`),
+        "",
+        "Exit code: 0 = every call succeeded / every scenario passed, 1 = an error result or a failed scenario, 2 = usage or file format error.",
+    ];
+    return `${lines.join("\n")}\n`;
+}
+/** cwd 안 = 상대 경로 · 밖 = 절대 경로 */
+function shown(cwd, file) {
+    const rel = relative(cwd, file);
+    return rel === "" || rel.startsWith("..") ? file : rel;
+}
+function indent(text, by = 2) {
+    const pad = " ".repeat(by);
+    return text
+        .split("\n")
+        .map((l) => (l === "" ? l : `${pad}${l}`))
+        .join("\n");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=inspect.js.map