@obov/mext 0.0.0-stage → 0.2.0

package/dist/cli/run.js

@@ -0,0 +1,218 @@
+import { createApp, loadCliErrorFormatter, loadConfig, resolveCommandsDir, resolveLocalPrincipal } from "../config.js";
+import { MextError } from "../errors.js";
+import { isSegment } from "../ids.js";
+import { loadProjectInstrumentation } from "../instrumentation.js";
+import { authorize, findCommand, invoke } from "../invoke.js";
+import { help } from "../mcp/help.js";
+import { resolveCommand } from "../registry.js";
+import { loadRegistry } from "../scan.js";
+import { analyzeInput, assertCliConvertible, coerceValue, parseArgs } from "./args.js";
+import { cliPath, renderHelp } from "./help.js";
+import { createLineReader, readAll } from "./io.js";
+import { CliInterrupted, emitError, EXIT, errorJson, exitCodeOf, formatError, formatJson, formatProgress, formatResult, } from "./output.js";
+import { remoteTarget, runRemoteCommand } from "./remote.js";
+export const RUN_PROG = "mext run";
+/**
+ * mext run <ns> <cmd> [flags] — 로컬 실행 (ctx.principal.kind = local, mext.config.ts 의 localPrincipal 로 변경 가능).
+ * mext run help [target] · mext run [<ns> [<cmd>]] --help · --json · --yes.
+ * --url <url> (또는 MEXT_URL) = 원격 실행 (cli/remote.ts)
+ */
+export async function runCommand(argv, io) {
+    const remote = remoteTarget(argv, io.env);
+    if (remote)
+        return runRemoteCommand(remote, io);
+    const prog = RUN_PROG;
+    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"));
+        }
+    }
+    const rest = argv.slice(i);
+    const beforeDashDash = rest.indexOf("--") < 0 ? rest : rest.slice(0, rest.indexOf("--"));
+    const json = lead.json || beforeDashDash.includes("--json");
+    const lines = createLineReader(io);
+    let formatter;
+    try {
+        // instrumentation.ts register() = 설정 · 명령어 모듈 import 전 (프로세스당 1회)
+        const instrumentation = await loadProjectInstrumentation(io.cwd);
+        const config = await loadConfig(io.cwd);
+        formatter = await loadCliErrorFormatter(io.cwd, config);
+        const registry = await loadRegistry(resolveCommandsDir(io.cwd, config));
+        assertCliConvertible(registry);
+        // mext run help [target...]
+        if (rest[0] === "help") {
+            const targetTokens = rest.slice(1).filter((t) => !t.startsWith("-"));
+            const { id, consumed } = resolvePath(registry, targetTokens);
+            if (consumed < targetTokens.length)
+                throw unknownAt(registry, id, targetTokens.slice(consumed));
+            return printHelp(registry, id, io, prog, json, config.tools);
+        }
+        const { id, consumed } = resolvePath(registry, rest);
+        const entry = id === "" ? undefined : resolveCommand(registry, id);
+        const next = rest[consumed];
+        const acceptsPositional = entry !== undefined && entry.command.positional.length > 0;
+        if (registry.namespaces.has(id) && next !== undefined && !next.startsWith("-") && !acceptsPositional) {
+            throw unknownAt(registry, id, rest.slice(consumed));
+        }
+        if (entry === undefined && next !== undefined && !next.startsWith("-")) {
+            throw unknownAt(registry, id, rest.slice(consumed));
+        }
+        const help = lead.help || beforeDashDash.includes("--help") || beforeDashDash.includes("-h");
+        if (help)
+            return printHelp(registry, id, io, prog, json, config.tools);
+        if (!entry) {
+            // 네임스페이스 (루트 포함) 만 지정 = 명령어 없음
+            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, formatter);
+            const text = `${formatError(error, prog)}\n${renderHelp(registry, id, { prog })}`;
+            return emitError(io, { body: errorJson(error), text, exitCode: EXIT.usage, json: false }, formatter);
+        }
+        const principal = await resolveLocalPrincipal(config);
+        authorize(entry, principal); // 권한 → 입력 검증 순서 (invoke 와 같음)
+        const parsed = await parseArgs(entry, rest.slice(consumed), { readStdin: () => readAll(io.stdin) });
+        const yes = lead.yes || parsed.yes;
+        const app = await createApp(config);
+        const controller = new AbortController();
+        const onAbort = () => controller.abort(io.signal?.reason);
+        if (io.signal?.aborted)
+            onAbort();
+        io.signal?.addEventListener("abort", onAbort, { once: true });
+        try {
+            const result = await invoke(registry, entry.id, parsed.input, {
+                principal,
+                signal: controller.signal,
+                progress: (update) => io.stderr.write(formatProgress(update)),
+                ask: askHandler(io, lines, yes, controller.signal),
+                app,
+                instrumentation,
+                transport: "local",
+            });
+            if (controller.signal.aborted)
+                throw new CliInterrupted();
+            io.stdout.write(json ? formatJson(result.value) : formatResult(result.value));
+            return EXIT.ok;
+        }
+        catch (error) {
+            if (controller.signal.aborted)
+                throw new CliInterrupted();
+            throw error;
+        }
+        finally {
+            io.signal?.removeEventListener("abort", onAbort);
+        }
+    }
+    catch (error) {
+        return report(error, io, prog, json, formatter);
+    }
+    finally {
+        lines.close();
+    }
+}
+/** 앞쪽 경로 토큰 → 가장 긴 네임스페이스 · 명령어 (별칭 포함) ID */
+export function resolvePath(registry, tokens) {
+    let id = "";
+    let consumed = 0;
+    for (const tok of tokens) {
+        if (!isSegment(tok))
+            break;
+        const candidate = id === "" ? tok : `${id}.${tok}`;
+        if (!registry.namespaces.has(candidate) && !resolveCommand(registry, candidate))
+            break;
+        id = candidate;
+        consumed++;
+    }
+    return { id, consumed };
+}
+/** 해석되지 않은 경로 토큰 → UNKNOWN_COMMAND (suggested · usage) */
+function unknownAt(registry, id, tail) {
+    const segs = [];
+    for (const t of tail) {
+        if (t.startsWith("-") || (segs.length > 0 && !isSegment(t)))
+            break;
+        segs.push(t);
+        if (!isSegment(t))
+            break;
+    }
+    const unknown = [id, ...segs].filter((s) => s !== "").join(".");
+    try {
+        findCommand(registry, unknown);
+    }
+    catch (error) {
+        if (error instanceof MextError)
+            return error;
+        throw error;
+    }
+    return new MextError("UNKNOWN_COMMAND", `Unknown command "${unknown}".`, { command: unknown, suggested: [], usage: "help" });
+}
+/** --help --json = MCP help 의 structuredContent 와 같은 데이터 (mext mcp 의 tools 노출 기준) */
+function printHelp(registry, id, io, prog, json, tools) {
+    const toolFor = tools === "split" ? (e) => (e.command.readOnly ? "query" : "mutate") : undefined;
+    io.stdout.write(json ? formatJson(help(registry, id, toolFor ? { toolFor } : {})) : renderHelp(registry, id, { prog }));
+    return EXIT.ok;
+}
+function report(error, io, prog, json, formatter) {
+    return emitError(io, { body: errorJson(error), text: formatError(error, prog), exitCode: exitCodeOf(error), json }, formatter);
+}
+function usageError(message) {
+    return new MextError("INVALID_ARGUMENT", message, {
+        command: "",
+        missing_fields: [],
+        issues: [{ path: "", code: "unknown_flag", message }],
+        expected_schema: {},
+        examples: [],
+    });
+}
+/**
+ * ctx.ask. --yes = confirm 승인. TTY 없음 = 즉시 INPUT_UNAVAILABLE.
+ * TTY = stderr 프롬프트 + stdin 한 줄 (confirm = y/yes, input = 필드별 입력을 스키마 모양으로 변환)
+ */
+function askHandler(io, lines, yes, signal) {
+    return async (request) => {
+        if (request.kind === "confirm" && yes)
+            return true;
+        if (!io.isTTY) {
+            const hint = request.kind === "confirm" ? " Pass --yes to approve." : " Run it in an interactive terminal.";
+            throw new MextError("INPUT_UNAVAILABLE", `${request.command} asked "${request.message}", but stdin is not a terminal.${hint}`, { command: request.command });
+        }
+        if (request.kind === "confirm") {
+            const answer = await lines.question(`${request.message} [y/N] `, signal);
+            if (signal.aborted)
+                throw new CliInterrupted();
+            return /^y(es)?$/i.test((answer ?? "").trim());
+        }
+        io.stderr.write(`${request.message}\n`);
+        const { spec } = analyzeInput(request.schema, request.requestedSchema);
+        const out = {};
+        for (const f of spec.fields) {
+            const answer = await lines.question(`  ${f.key}${f.required ? "" : " (optional)"}: `, signal);
+            if (signal.aborted)
+                throw new CliInterrupted();
+            if (answer === undefined || answer === "")
+                continue;
+            if (f.kind.type === "array") {
+                const kind = f.kind;
+                out[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);
+            out[f.key] = r.ok ? r.value : answer;
+        }
+        return out;
+    };
+}
+//# sourceMappingURL=run.js.map

package/dist/cli/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"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","sourcesContent":["import { createApp, loadCliErrorFormatter, loadConfig, resolveCommandsDir, resolveLocalPrincipal } from \"../config.ts\"\nimport { MextError } from \"../errors.ts\"\nimport { isSegment } from \"../ids.ts\"\nimport { loadProjectInstrumentation } from \"../instrumentation.ts\"\nimport { authorize, findCommand, invoke, type AskHandler } from \"../invoke.ts\"\nimport type { ToolExposure } from \"../mcp/dispatch.ts\"\nimport { help } from \"../mcp/help.ts\"\nimport { resolveCommand, type RegisteredCommand, type Registry } from \"../registry.ts\"\nimport { loadRegistry } from \"../scan.ts\"\nimport { analyzeInput, assertCliConvertible, coerceValue, parseArgs } from \"./args.ts\"\nimport { cliPath, renderHelp } from \"./help.ts\"\nimport { createLineReader, readAll, type CliIo, type LineReader } from \"./io.ts\"\nimport {\n  CliInterrupted,\n  emitError,\n  EXIT,\n  errorJson,\n  exitCodeOf,\n  formatError,\n  formatJson,\n  formatProgress,\n  formatResult,\n  type CliErrorFormatter,\n} from \"./output.ts\"\nimport { remoteTarget, runRemoteCommand } from \"./remote.ts\"\n\nexport const RUN_PROG = \"mext run\"\n\n/**\n * mext run <ns> <cmd> [flags] — 로컬 실행 (ctx.principal.kind = local, mext.config.ts 의 localPrincipal 로 변경 가능).\n * mext run help [target] · mext run [<ns> [<cmd>]] --help · --json · --yes.\n * --url <url> (또는 MEXT_URL) = 원격 실행 (cli/remote.ts)\n */\nexport async function runCommand(argv: readonly string[], io: CliIo): Promise<number> {\n  const remote = remoteTarget(argv, io.env)\n  if (remote) return runRemoteCommand(remote, io)\n  const prog = RUN_PROG\n  const lead = { json: false, yes: false, help: false }\n  let i = 0\n  for (; i < argv.length; i++) {\n    const tok = argv[i]!\n    if (!tok.startsWith(\"-\") || tok === \"-\") break\n    if (tok === \"--json\") lead.json = true\n    else if (tok === \"--yes\") lead.yes = true\n    else if (tok === \"--help\" || tok === \"-h\") lead.help = true\n    else {\n      return report(usageError(`unknown flag ${tok} before the command`), io, prog, argv.includes(\"--json\"))\n    }\n  }\n  const rest = argv.slice(i)\n  const beforeDashDash = rest.indexOf(\"--\") < 0 ? rest : rest.slice(0, rest.indexOf(\"--\"))\n  const json = lead.json || beforeDashDash.includes(\"--json\")\n\n  const lines = createLineReader(io)\n  let formatter: CliErrorFormatter | undefined\n  try {\n    // instrumentation.ts register() = 설정 · 명령어 모듈 import 전 (프로세스당 1회)\n    const instrumentation = await loadProjectInstrumentation(io.cwd)\n    const config = await loadConfig(io.cwd)\n    formatter = await loadCliErrorFormatter(io.cwd, config)\n    const registry = await loadRegistry(resolveCommandsDir(io.cwd, config))\n    assertCliConvertible(registry)\n\n    // mext run help [target...]\n    if (rest[0] === \"help\") {\n      const targetTokens = rest.slice(1).filter((t) => !t.startsWith(\"-\"))\n      const { id, consumed } = resolvePath(registry, targetTokens)\n      if (consumed < targetTokens.length) throw unknownAt(registry, id, targetTokens.slice(consumed))\n      return printHelp(registry, id, io, prog, json, config.tools)\n    }\n\n    const { id, consumed } = resolvePath(registry, rest)\n    const entry = id === \"\" ? undefined : resolveCommand(registry, id)\n    const next = rest[consumed]\n    const acceptsPositional = entry !== undefined && entry.command.positional.length > 0\n    if (registry.namespaces.has(id) && next !== undefined && !next.startsWith(\"-\") && !acceptsPositional) {\n      throw unknownAt(registry, id, rest.slice(consumed))\n    }\n    if (entry === undefined && next !== undefined && !next.startsWith(\"-\")) {\n      throw unknownAt(registry, id, rest.slice(consumed))\n    }\n\n    const help = lead.help || beforeDashDash.includes(\"--help\") || beforeDashDash.includes(\"-h\")\n    if (help) return printHelp(registry, id, io, prog, json, config.tools)\n\n    if (!entry) {\n      // 네임스페이스 (루트 포함) 만 지정 = 명령어 없음\n      const error = new MextError(\n        \"UNKNOWN_COMMAND\",\n        id === \"\" ? \"No command given.\" : `\"${cliPath(id)}\" is a namespace. Specify a command.`,\n        { command: id, suggested: [], usage: id === \"\" ? \"help\" : `help ${id}` },\n      )\n      if (json) return report(error, io, prog, true, formatter)\n      const text = `${formatError(error, prog)}\\n${renderHelp(registry, id, { prog })}`\n      return emitError(io, { body: errorJson(error), text, exitCode: EXIT.usage, json: false }, formatter)\n    }\n\n    const principal = await resolveLocalPrincipal(config)\n    authorize(entry, principal) // 권한 → 입력 검증 순서 (invoke 와 같음)\n    const parsed = await parseArgs(entry, rest.slice(consumed), { readStdin: () => readAll(io.stdin) })\n    const yes = lead.yes || parsed.yes\n    const app = await createApp(config)\n\n    const controller = new AbortController()\n    const onAbort = (): void => controller.abort(io.signal?.reason)\n    if (io.signal?.aborted) onAbort()\n    io.signal?.addEventListener(\"abort\", onAbort, { once: true })\n    try {\n      const result = await invoke(registry, entry.id, parsed.input, {\n        principal,\n        signal: controller.signal,\n        progress: (update) => io.stderr.write(formatProgress(update)),\n        ask: askHandler(io, lines, yes, controller.signal),\n        app,\n        instrumentation,\n        transport: \"local\",\n      })\n      if (controller.signal.aborted) throw new CliInterrupted()\n      io.stdout.write(json ? formatJson(result.value) : formatResult(result.value))\n      return EXIT.ok\n    } catch (error) {\n      if (controller.signal.aborted) throw new CliInterrupted()\n      throw error\n    } finally {\n      io.signal?.removeEventListener(\"abort\", onAbort)\n    }\n  } catch (error) {\n    return report(error, io, prog, json, formatter)\n  } finally {\n    lines.close()\n  }\n}\n\n/** 앞쪽 경로 토큰 → 가장 긴 네임스페이스 · 명령어 (별칭 포함) ID */\nexport function resolvePath(registry: Registry, tokens: readonly string[]): { id: string; consumed: number } {\n  let id = \"\"\n  let consumed = 0\n  for (const tok of tokens) {\n    if (!isSegment(tok)) break\n    const candidate = id === \"\" ? tok : `${id}.${tok}`\n    if (!registry.namespaces.has(candidate) && !resolveCommand(registry, candidate)) break\n    id = candidate\n    consumed++\n  }\n  return { id, consumed }\n}\n\n/** 해석되지 않은 경로 토큰 → UNKNOWN_COMMAND (suggested · usage) */\nfunction unknownAt(registry: Registry, id: string, tail: readonly string[]): MextError {\n  const segs: string[] = []\n  for (const t of tail) {\n    if (t.startsWith(\"-\") || (segs.length > 0 && !isSegment(t))) break\n    segs.push(t)\n    if (!isSegment(t)) break\n  }\n  const unknown = [id, ...segs].filter((s) => s !== \"\").join(\".\")\n  try {\n    findCommand(registry, unknown)\n  } catch (error) {\n    if (error instanceof MextError) return error\n    throw error\n  }\n  return new MextError(\"UNKNOWN_COMMAND\", `Unknown command \"${unknown}\".`, { command: unknown, suggested: [], usage: \"help\" })\n}\n\n/** --help --json = MCP help 의 structuredContent 와 같은 데이터 (mext mcp 의 tools 노출 기준) */\nfunction printHelp(registry: Registry, id: string, io: CliIo, prog: string, json: boolean, tools: ToolExposure | undefined): number {\n  const toolFor = tools === \"split\" ? (e: RegisteredCommand) => (e.command.readOnly ? \"query\" : \"mutate\") : undefined\n  io.stdout.write(json ? formatJson(help(registry, id, toolFor ? { toolFor } : {})) : renderHelp(registry, id, { prog }))\n  return EXIT.ok\n}\n\nfunction report(error: unknown, io: CliIo, prog: string, json: boolean, formatter?: CliErrorFormatter): number {\n  return emitError(io, { body: errorJson(error), text: formatError(error, prog), exitCode: exitCodeOf(error), json }, formatter)\n}\n\nfunction usageError(message: string): MextError<\"INVALID_ARGUMENT\"> {\n  return new MextError(\"INVALID_ARGUMENT\", message, {\n    command: \"\",\n    missing_fields: [],\n    issues: [{ path: \"\", code: \"unknown_flag\", message }],\n    expected_schema: {},\n    examples: [],\n  })\n}\n\n\n/**\n * ctx.ask. --yes = confirm 승인. TTY 없음 = 즉시 INPUT_UNAVAILABLE.\n * TTY = stderr 프롬프트 + stdin 한 줄 (confirm = y/yes, input = 필드별 입력을 스키마 모양으로 변환)\n */\nfunction askHandler(io: CliIo, lines: LineReader, yes: boolean, signal: AbortSignal): AskHandler {\n  return async (request) => {\n    if (request.kind === \"confirm\" && yes) return true\n    if (!io.isTTY) {\n      const hint = request.kind === \"confirm\" ? \" Pass --yes to approve.\" : \" Run it in an interactive terminal.\"\n      throw new MextError(\n        \"INPUT_UNAVAILABLE\",\n        `${request.command} asked \"${request.message}\", but stdin is not a terminal.${hint}`,\n        { command: request.command },\n      )\n    }\n    if (request.kind === \"confirm\") {\n      const answer = await lines.question(`${request.message} [y/N] `, signal)\n      if (signal.aborted) throw new CliInterrupted()\n      return /^y(es)?$/i.test((answer ?? \"\").trim())\n    }\n    io.stderr.write(`${request.message}\\n`)\n    const { spec } = analyzeInput(request.schema, request.requestedSchema)\n    const out: Record<string, unknown> = {}\n    for (const f of spec.fields) {\n      const answer = await lines.question(`  ${f.key}${f.required ? \"\" : \" (optional)\"}: `, signal)\n      if (signal.aborted) throw new CliInterrupted()\n      if (answer === undefined || answer === \"\") continue\n      if (f.kind.type === \"array\") {\n        const kind = f.kind\n        out[f.key] = answer.split(\",\").map((s) => {\n          const r = coerceValue(kind, s.trim())\n          return r.ok ? r.value : s\n        })\n        continue\n      }\n      const r = coerceValue(f.kind, answer)\n      out[f.key] = r.ok ? r.value : answer\n    }\n    return out\n  }\n}\n"]}

package/dist/cli/start.d.ts

@@ -0,0 +1,8 @@
+import type { CliIo } from "./io.ts";
+export declare const START_PROG = "mext start";
+/**
+ * mext start [--stdio] [--port <n>] [--host <h>] = startFromBuild(<cwd>/.mext) (node .mext/server.js 와 같음).
+ * .mext/ 만 읽는다 (소스 스캔 · 감시 · TypeScript 없음). 종료 = SIGINT · SIGTERM
+ */
+export declare function startCommand(argv: readonly string[], io: CliIo): Promise<number>;
+export declare function startHelp(): string;

package/dist/cli/start.js

@@ -0,0 +1,37 @@
+import { join } from "node:path";
+import { BUILD_DIR } from "../build.js";
+import { startFromBuild } from "../start.js";
+import { table } from "./help.js";
+import { EXIT } from "./output.js";
+export const START_PROG = "mext start";
+/**
+ * mext start [--stdio] [--port <n>] [--host <h>] = startFromBuild(<cwd>/.mext) (node .mext/server.js 와 같음).
+ * .mext/ 만 읽는다 (소스 스캔 · 감시 · TypeScript 없음). 종료 = SIGINT · SIGTERM
+ */
+export async function startCommand(argv, io) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        io.stdout.write(startHelp());
+        return EXIT.ok;
+    }
+    return startFromBuild(join(io.cwd, BUILD_DIR), { argv, env: io.env, stderr: io.stderr });
+}
+export function startHelp() {
+    const lines = [
+        "Production MCP server from .mext/ (run mext build first). No source scan, no file watching.",
+        "",
+        "Usage:",
+        `  ${START_PROG} [--port <n>] [--host <h>]   Streamable HTTP (POST /mcp)`,
+        `  ${START_PROG} --stdio                     stdio`,
+        "",
+        "Flags:",
+        ...table([
+            ["--stdio", "Serve MCP over stdin/stdout"],
+            ["--port <n>", "HTTP port (default: PORT, then mext.config.ts server.port, then 3100)"],
+            ["--host <h>", "HTTP host (default: HOST, then mext.config.ts server.host, then 127.0.0.1)"],
+        ]).map((l) => `  ${l}`),
+        "",
+        "Same as: node .mext/server.js [--stdio]",
+    ];
+    return `${lines.join("\n")}\n`;
+}
+//# sourceMappingURL=start.js.map

package/dist/cli/start.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.js","sourceRoot":"","sources":["../../src/cli/start.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAA;AAEjC,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAElC,MAAM,CAAC,MAAM,UAAU,GAAG,YAAY,CAAA;AAEtC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAuB,EAAE,EAAS;IACnE,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,CAAA;QAC5B,OAAO,IAAI,CAAC,EAAE,CAAA;IAChB,CAAC;IACD,OAAO,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAA;AAC1F,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,MAAM,KAAK,GAAG;QACZ,6FAA6F;QAC7F,EAAE;QACF,QAAQ;QACR,KAAK,UAAU,0DAA0D;QACzE,KAAK,UAAU,oCAAoC;QACnD,EAAE;QACF,QAAQ;QACR,GAAG,KAAK,CAAC;YACP,CAAC,SAAS,EAAE,6BAA6B,CAAC;YAC1C,CAAC,YAAY,EAAE,uEAAuE,CAAC;YACvF,CAAC,YAAY,EAAE,4EAA4E,CAAC;SAC7F,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,EAAE;QACF,yCAAyC;KAC1C,CAAA;IACD,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAA;AAChC,CAAC","sourcesContent":["import { join } from \"node:path\"\nimport { BUILD_DIR } from \"../build.ts\"\nimport { startFromBuild } from \"../start.ts\"\nimport { table } from \"./help.ts\"\nimport type { CliIo } from \"./io.ts\"\nimport { EXIT } from \"./output.ts\"\n\nexport const START_PROG = \"mext start\"\n\n/**\n * mext start [--stdio] [--port <n>] [--host <h>] = startFromBuild(<cwd>/.mext) (node .mext/server.js 와 같음).\n * .mext/ 만 읽는다 (소스 스캔 · 감시 · TypeScript 없음). 종료 = SIGINT · SIGTERM\n */\nexport async function startCommand(argv: readonly string[], io: CliIo): Promise<number> {\n  if (argv.includes(\"--help\") || argv.includes(\"-h\")) {\n    io.stdout.write(startHelp())\n    return EXIT.ok\n  }\n  return startFromBuild(join(io.cwd, BUILD_DIR), { argv, env: io.env, stderr: io.stderr })\n}\n\nexport function startHelp(): string {\n  const lines = [\n    \"Production MCP server from .mext/ (run mext build first). No source scan, no file watching.\",\n    \"\",\n    \"Usage:\",\n    `  ${START_PROG} [--port <n>] [--host <h>]   Streamable HTTP (POST /mcp)`,\n    `  ${START_PROG} --stdio                     stdio`,\n    \"\",\n    \"Flags:\",\n    ...table([\n      [\"--stdio\", \"Serve MCP over stdin/stdout\"],\n      [\"--port <n>\", \"HTTP port (default: PORT, then mext.config.ts server.port, then 3100)\"],\n      [\"--host <h>\", \"HTTP host (default: HOST, then mext.config.ts server.host, then 127.0.0.1)\"],\n    ]).map((l) => `  ${l}`),\n    \"\",\n    \"Same as: node .mext/server.js [--stdio]\",\n  ]\n  return `${lines.join(\"\\n\")}\\n`\n}\n"]}

package/dist/client/cache.d.ts

@@ -0,0 +1,104 @@
+import type { Help } from "../mcp/help.ts";
+import { type RemoteTool } from "../remote/client.ts";
+import { type ClientManifest } from "./manifest.ts";
+/**
+ * 원격 스키마 캐시 · drift 감지 (§5 스키마 drift). 고객 CLI · mext run --url 공용 (번들 포함, Node 내장만 import).
+ *
+ * D4. 파일 = <cache dir>/<sha256(정규화 서버 URL) 앞 16 hex>.json, 쓰기 = 같은 폴더 임시 파일 → rename (원자적).
+ * cache dir = <BIN>_CACHE_DIR → $XDG_CACHE_HOME/<bin> → $HOME/.cache/<bin>. 셋 다 없음 = 캐시 없음.
+ * 내용 = SchemaCacheEntry. url · client (bin · version · mext 버전) 가 다르면 무효, 수명 = tools/list ttlMs.
+ *
+ * 이번 실행의 help 출처 (mode):
+ *   cache     유효 캐시 (수명 안 · stale 아님). help = 캐시 → (해시 = 내장 manifest 면) 내장 manifest → 서버 (캐시에 추가)
+ *   embedded  번들 형태 · 유효 캐시 없음 · 서버가 내장 manifest 와 다르다는 기록 없음. help = 내장 manifest
+ *   server    그 외 (범용 · stale · 서버가 내장 manifest 와 다름). help = 서버 (tools/list + help), 캐시 새로 씀
+ * tools/call 결과 _meta 의 manifestHash ≠ 이번 help 의 해시 = stale 표시 (이번 결과는 그대로, 다음 실행이 server).
+ * 로컬 파싱 실패 = refetch() 로 server 전환 후 1회 재시도 (runner). 오프라인 = 남은 캐시 · 내장 manifest 로 help 만
+ */
+export declare const SCHEMA_CACHE_FORMAT = 1;
+/** 캐시 무효화 단위. 하나라도 다르면 캐시 무시 */
+export interface CacheClient {
+    /** 실행 파일 이름 (clientInfo.name) */
+    bin: string;
+    /** clientInfo.version (고객 CLI = cli.version, mext = mext 버전) */
+    version: string;
+    /** 클라이언트 런타임의 @obov/mext 버전 (help 해석 코드) */
+    mext: string;
+}
+/** help 결과 또는 UNKNOWN_COMMAND (경로 해석이 가장 긴 접두부터 시도하므로 없는 대상도 기록) */
+export type CachedHelp = {
+    help: Help;
+} | {
+    error: Record<string, unknown> & {
+        code: string;
+        message: string;
+    };
+};
+export interface SchemaCacheEntry {
+    format: typeof SCHEMA_CACHE_FORMAT;
+    /** 정규화 서버 URL (파일 이름 해시 충돌 확인) */
+    url: string;
+    client: CacheClient;
+    /** help · tools 가 속한 서버 manifestHash. 없음 = 서버가 보내지 않음 */
+    manifestHash?: string;
+    /** tools/list 받은 시각 (epoch ms) */
+    fetchedAt: number;
+    /** tools/list ttlMs. 0 = 매 실행 재조회 (오프라인 help 용으로만 남김) */
+    ttlMs: number;
+    /** 서버 manifestHash 가 help 와 다름을 관찰. 다음 실행에서 서버 help 재조회 */
+    stale?: true;
+    /** tools/list 결과 */
+    tools: RemoteTool[];
+    /** help 대상 ("" = 루트) → 결과 */
+    help: Record<string, CachedHelp>;
+}
+/** <BIN>_CACHE_DIR → $XDG_CACHE_HOME/<bin> → $HOME/.cache/<bin> (USERPROFILE). 없으면 undefined (캐시 없음) */
+export declare function schemaCacheDir(bin: string, env: Record<string, string | undefined>): string | undefined;
+/** <dir>/<sha256(canonicalServerUrl(url)) 앞 16 hex>.json */
+export declare function schemaCacheFile(dir: string, url: string): string;
+/** 읽기 + 형식 · url · client 확인. 없음 · 깨짐 · 불일치 = undefined */
+export declare function readSchemaCache(file: string, url: string, client: CacheClient): Promise<SchemaCacheEntry | undefined>;
+/** 원자적 쓰기 (임시 파일 → rename). 실패는 호출자가 무시 (캐시는 최선) */
+export declare function writeSchemaCache(file: string, entry: SchemaCacheEntry): Promise<void>;
+export declare function isFresh(entry: SchemaCacheEntry, now: number): boolean;
+export type SchemaMode = "cache" | "embedded" | "server";
+export interface FetchedHelp {
+    value: CachedHelp;
+    /** 응답 _meta["dev.mext/manifestHash"] */
+    hash: string | undefined;
+}
+export interface SchemaOptions {
+    /** 캐시 파일. undefined = 캐시 없음 (읽기 · 쓰기 안 함) */
+    file: string | undefined;
+    url: string;
+    client: CacheClient;
+    /** 번들 형태의 내장 manifest + 빌드 시 manifestHash */
+    embedded?: {
+        manifest: ClientManifest;
+        hash: string;
+    };
+    /** 서버 help (tools/call help). UNKNOWN_COMMAND 는 value.error, 그 외 오류 = throw */
+    fetchHelp(target: string, tools: () => Promise<RemoteTool[]>): Promise<FetchedHelp>;
+    /** 서버 tools/list */
+    fetchTools(): Promise<{
+        tools: RemoteTool[];
+        ttlMs?: number;
+    }>;
+    /** 오프라인 help 안내 (stderr) */
+    warn(message: string): void;
+    now?: () => number;
+}
+export interface Schema {
+    readonly mode: SchemaMode;
+    /** HelpSource: 대상 → help. 없는 대상 = MextError UNKNOWN_COMMAND */
+    help(target: string): Promise<Help>;
+    /** 로컬 (cache · embedded) 파싱 실패 후 서버 help 로 전환. 이미 server = false (재시도 안 함) */
+    refetch(): boolean;
+    /** dispatcher 도구 목록 (유효 캐시 = 네트워크 없음) */
+    tools(): Promise<RemoteTool[]>;
+    /** tools/call 결과 _meta 의 manifestHash 관찰. 이번 help 의 해시와 다르면 stale */
+    observe(hash: string | undefined): void;
+    /** 바뀐 내용이 있으면 캐시 파일 쓰기 (실패 무시) */
+    save(): Promise<void>;
+}
+export declare function openSchema(options: SchemaOptions): Promise<Schema>;

package/dist/client/cache.js

@@ -0,0 +1,208 @@
+import { createHash, randomBytes } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { MextError } from "../errors.js";
+import { isRecord, RemoteTransportError } from "../remote/client.js";
+import { canonicalServerUrl, envPrefix } from "../remote/credentials.js";
+import { manifestHelp } from "./manifest.js";
+/**
+ * 원격 스키마 캐시 · drift 감지 (§5 스키마 drift). 고객 CLI · mext run --url 공용 (번들 포함, Node 내장만 import).
+ *
+ * D4. 파일 = <cache dir>/<sha256(정규화 서버 URL) 앞 16 hex>.json, 쓰기 = 같은 폴더 임시 파일 → rename (원자적).
+ * cache dir = <BIN>_CACHE_DIR → $XDG_CACHE_HOME/<bin> → $HOME/.cache/<bin>. 셋 다 없음 = 캐시 없음.
+ * 내용 = SchemaCacheEntry. url · client (bin · version · mext 버전) 가 다르면 무효, 수명 = tools/list ttlMs.
+ *
+ * 이번 실행의 help 출처 (mode):
+ *   cache     유효 캐시 (수명 안 · stale 아님). help = 캐시 → (해시 = 내장 manifest 면) 내장 manifest → 서버 (캐시에 추가)
+ *   embedded  번들 형태 · 유효 캐시 없음 · 서버가 내장 manifest 와 다르다는 기록 없음. help = 내장 manifest
+ *   server    그 외 (범용 · stale · 서버가 내장 manifest 와 다름). help = 서버 (tools/list + help), 캐시 새로 씀
+ * tools/call 결과 _meta 의 manifestHash ≠ 이번 help 의 해시 = stale 표시 (이번 결과는 그대로, 다음 실행이 server).
+ * 로컬 파싱 실패 = refetch() 로 server 전환 후 1회 재시도 (runner). 오프라인 = 남은 캐시 · 내장 manifest 로 help 만
+ */
+export const SCHEMA_CACHE_FORMAT = 1;
+/** <BIN>_CACHE_DIR → $XDG_CACHE_HOME/<bin> → $HOME/.cache/<bin> (USERPROFILE). 없으면 undefined (캐시 없음) */
+export function schemaCacheDir(bin, env) {
+    const forced = env[`${envPrefix(bin)}_CACHE_DIR`];
+    if (forced)
+        return forced;
+    if (env.XDG_CACHE_HOME)
+        return join(env.XDG_CACHE_HOME, bin);
+    const home = env.HOME || env.USERPROFILE;
+    return home ? join(home, ".cache", bin) : undefined;
+}
+/** <dir>/<sha256(canonicalServerUrl(url)) 앞 16 hex>.json */
+export function schemaCacheFile(dir, url) {
+    return join(dir, `${createHash("sha256").update(canonicalServerUrl(url)).digest("hex").slice(0, 16)}.json`);
+}
+/** 읽기 + 형식 · url · client 확인. 없음 · 깨짐 · 불일치 = undefined */
+export async function readSchemaCache(file, url, client) {
+    let value;
+    try {
+        value = JSON.parse(await readFile(file, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(value) || value.format !== SCHEMA_CACHE_FORMAT || value.url !== canonicalServerUrl(url))
+        return undefined;
+    const c = value.client;
+    if (!isRecord(c) || c.bin !== client.bin || c.version !== client.version || c.mext !== client.mext)
+        return undefined;
+    if (typeof value.fetchedAt !== "number" || typeof value.ttlMs !== "number")
+        return undefined;
+    if (!Array.isArray(value.tools) || !isRecord(value.help))
+        return undefined;
+    if (value.manifestHash !== undefined && typeof value.manifestHash !== "string")
+        return undefined;
+    return value;
+}
+/** 원자적 쓰기 (임시 파일 → rename). 실패는 호출자가 무시 (캐시는 최선) */
+export async function writeSchemaCache(file, entry) {
+    const dir = join(file, "..");
+    await mkdir(dir, { recursive: true });
+    const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    try {
+        await writeFile(tmp, `${JSON.stringify(entry)}\n`);
+        await rename(tmp, file);
+    }
+    catch (error) {
+        await rm(tmp, { force: true }).catch(() => { });
+        throw error;
+    }
+}
+export function isFresh(entry, now) {
+    return entry.stale !== true && entry.ttlMs > 0 && now >= entry.fetchedAt && now < entry.fetchedAt + entry.ttlMs;
+}
+export async function openSchema(options) {
+    const clock = options.now ?? Date.now;
+    const started = clock();
+    const { embedded } = options;
+    const previous = options.file ? await readSchemaCache(options.file, options.url, options.client) : undefined;
+    const diverged = previous !== undefined &&
+        (previous.stale === true || (embedded !== undefined && previous.manifestHash !== undefined && previous.manifestHash !== embedded.hash));
+    let mode = previous !== undefined && isFresh(previous, started) ? "cache" : embedded && !diverged ? "embedded" : "server";
+    const cached = mode === "cache" ? previous : undefined;
+    let hash = cached ? cached.manifestHash : mode === "embedded" ? embedded.hash : undefined;
+    let help = cached ? { ...cached.help } : {};
+    let tools = cached?.tools;
+    let fetchedAt = cached?.fetchedAt ?? started;
+    let ttlMs = cached?.ttlMs ?? 0;
+    let stale = false;
+    let dirty = false;
+    let refetched = false;
+    let warned = false;
+    let pendingTools;
+    const loadTools = () => {
+        if (tools)
+            return Promise.resolve(tools);
+        return (pendingTools ??= options
+            .fetchTools()
+            .then((r) => {
+            tools = r.tools;
+            ttlMs = r.ttlMs ?? 0;
+            fetchedAt = clock();
+            dirty = true;
+            return r.tools;
+        })
+            .finally(() => {
+            pendingTools = undefined;
+        }));
+    };
+    const local = (target) => {
+        const hit = help[target];
+        if (hit)
+            return unpack(hit);
+        if (embedded && mode !== "server" && hash === embedded.hash)
+            return manifestHelp(embedded.manifest, target);
+        return undefined;
+    };
+    return {
+        get mode() {
+            return mode;
+        },
+        async help(target) {
+            const found = local(target);
+            if (found)
+                return found;
+            let fetched;
+            try {
+                fetched = await options.fetchHelp(target, loadTools);
+            }
+            catch (error) {
+                // 오프라인: 남은 캐시 (수명 지남 · stale) → 내장 manifest. refetch 중이면 runner 가 원래 로컬 오류를 낸다
+                if (error instanceof RemoteTransportError && !refetched) {
+                    const old = previous?.help[target];
+                    if (old || embedded) {
+                        if (!warned)
+                            options.warn(`warning: ${error.message} Showing ${old ? "cached" : "built-in"} help.\n`);
+                        warned = true;
+                        return old ? unpack(old) : manifestHelp(embedded.manifest, target);
+                    }
+                }
+                throw error;
+            }
+            if (fetched.hash !== undefined) {
+                if (hash === undefined)
+                    hash = fetched.hash;
+                else if (fetched.hash !== hash) {
+                    if (mode === "server") {
+                        // 실행 중 서버 교체: 이전 응답 버림
+                        help = {};
+                        hash = fetched.hash;
+                    }
+                    else
+                        stale = true;
+                }
+            }
+            help[target] = fetched.value;
+            dirty = true;
+            return unpack(fetched.value);
+        },
+        refetch() {
+            if (mode === "server")
+                return false;
+            mode = "server";
+            refetched = true;
+            help = {};
+            hash = undefined;
+            return true;
+        },
+        tools: loadTools,
+        observe(observed) {
+            if (observed === undefined)
+                return;
+            if (hash === undefined) {
+                hash = observed;
+                dirty = true;
+            }
+            else if (observed !== hash) {
+                hash = observed;
+                stale = true;
+                dirty = true;
+            }
+        },
+        async save() {
+            if (!options.file || !dirty || !tools)
+                return;
+            const entry = {
+                format: SCHEMA_CACHE_FORMAT,
+                url: canonicalServerUrl(options.url),
+                client: options.client,
+                ...(hash !== undefined ? { manifestHash: hash } : {}),
+                fetchedAt,
+                ttlMs,
+                ...(stale ? { stale: true } : {}),
+                tools,
+                help,
+            };
+            await writeSchemaCache(options.file, entry).catch(() => { });
+        },
+    };
+}
+function unpack(cached) {
+    if ("help" in cached)
+        return cached.help;
+    const { code, message, ...details } = cached.error;
+    throw new MextError(code, message, details);
+}
+//# sourceMappingURL=cache.js.map