@obov/mext 0.0.0-stage → 0.1.0

package/dist/cli/help.d.ts

@@ -0,0 +1,31 @@
+import type { NamespaceInfo, RegisteredCommand, Registry } from "../registry.ts";
+/**
+ * help 생성 (D2). 일반 텍스트, ANSI 색 없음, 같은 Registry 에 같은 출력.
+ * 대상 = "" (루트) · 네임스페이스 ID · 명령어 ID (별칭 포함). prog = 명령어 앞 접두 ("mext run" · "myapp").
+ */
+export interface HelpOptions {
+    /** 명령어 경로 앞에 붙는 실행 접두. 예: "mext run" */
+    prog: string;
+}
+export type HelpTarget = {
+    kind: "namespace";
+    namespace: NamespaceInfo;
+    command: RegisteredCommand | undefined;
+} | {
+    kind: "command";
+    command: RegisteredCommand;
+};
+/** 대상 해석. 네임스페이스가 우선 (users = 네임스페이스 + index.ts 명령어면 둘 다). 없으면 UNKNOWN_COMMAND */
+export declare function resolveHelpTarget(registry: Registry, target: string): HelpTarget;
+/** 대상의 help 텍스트 (끝 줄바꿈 포함) */
+export declare function renderHelp(registry: Registry, target: string, options: HelpOptions): string;
+export declare function renderNamespaceHelp(registry: Registry, ns: NamespaceInfo, options: HelpOptions): string;
+export declare function renderCommandHelp(entry: RegisteredCommand, options: HelpOptions): string;
+/** 입력 객체 → CLI 호출 문자열 (positional · 점 플래그 · 반복 · JSON 문자열) */
+export declare function formatInvocation(entry: RegisteredCommand, input: unknown, options: HelpOptions): string;
+/** 명령어 · 네임스페이스 ID → CLI 경로 ("users.get" → "users get") */
+export declare function cliPath(id: string): string;
+/** 두 칸 간격 정렬 표. 끝 공백 제거 */
+export declare function table(rows: readonly (readonly string[])[]): string[];
+/** 셸에 그대로 붙여 넣을 수 있는 인용 */
+export declare function shellQuote(value: string): string;

package/dist/cli/help.js

@@ -0,0 +1,238 @@
+import { findCommand } from "../lookup.js";
+import { cliSpec } from "./args.js";
+/** 대상 해석. 네임스페이스가 우선 (users = 네임스페이스 + index.ts 명령어면 둘 다). 없으면 UNKNOWN_COMMAND */
+export function resolveHelpTarget(registry, target) {
+    const ns = registry.namespaces.get(target);
+    if (ns)
+        return { kind: "namespace", namespace: ns, command: target === "" ? undefined : registry.commands.get(target) };
+    return { kind: "command", command: findCommand(registry, target) };
+}
+/** 대상의 help 텍스트 (끝 줄바꿈 포함) */
+export function renderHelp(registry, target, options) {
+    const t = resolveHelpTarget(registry, target);
+    if (t.kind === "command")
+        return renderCommandHelp(t.command, options);
+    const text = renderNamespaceHelp(registry, t.namespace, options);
+    return t.command ? `${text}\n${renderCommandHelp(t.command, options)}` : text;
+}
+export function renderNamespaceHelp(registry, ns, options) {
+    const out = [];
+    const path = cliPath(ns.id);
+    const prefix = path === "" ? options.prog : `${options.prog} ${path}`;
+    if (ns.id !== "")
+        out.push(`Namespace: ${path}`, "");
+    if (ns.description)
+        out.push(ns.description, "");
+    out.push("Usage:");
+    out.push(`  ${prefix} <command> [args] [flags]`);
+    if (ns.id === "" && ns.namespaces.length > 0)
+        out.push(`  ${prefix} <namespace> --help`);
+    out.push(`  ${prefix} <command> --help`, "");
+    if (ns.namespaces.length > 0) {
+        out.push("Namespaces:");
+        out.push(...table(ns.namespaces.map((id) => [lastSegment(id), summaryOf(registry.namespaces.get(id)) ?? ""])).map((l) => `  ${l}`), "");
+    }
+    if (ns.commands.length > 0) {
+        out.push("Commands:");
+        out.push(...table(ns.commands.map((id) => {
+            const c = registry.commands.get(id).command;
+            return [lastSegment(id), c.description];
+        })).map((l) => `  ${l}`), "");
+    }
+    out.push("Global flags:", ...globalFlagLines(false), "");
+    return finish(out);
+}
+export function renderCommandHelp(entry, options) {
+    const c = entry.command;
+    const spec = cliSpec(entry);
+    const path = cliPath(entry.id);
+    const out = [c.description, ""];
+    const positional = spec.positional.map((k) => spec.fields.find((f) => f.key === k)).filter(Boolean);
+    const usageArgs = positional.map((f) => {
+        const name = f.kind.type === "array" ? `${f.flag}...` : f.flag;
+        return f.required ? `<${name}>` : `[${name}]`;
+    });
+    out.push("Usage:", `  ${[options.prog, path, ...usageArgs, "[flags]"].join(" ")}`, "");
+    if (positional.length > 0) {
+        out.push("Arguments:");
+        out.push(...table(positional.map((f) => [`<${f.flag}>`, annotate(f, [`or --${f.flag}`])])).map((l) => `  ${l}`), "");
+    }
+    const flagRows = [];
+    for (const f of spec.fields) {
+        if (spec.positional.includes(f.key))
+            continue;
+        flagRows.push(...fieldRows(f, ""));
+    }
+    if (flagRows.length > 0)
+        out.push("Flags:", ...table(flagRows).map((l) => `  ${l}`), "");
+    out.push("Global flags:", ...globalFlagLines(true), "");
+    const safety = [c.readOnly ? "read-only" : "writes"];
+    if (c.destructive)
+        safety.push("destructive");
+    if (c.requiresConfirmation)
+        safety.push("requires confirmation (--yes to approve)");
+    if (c.scopes.length > 0)
+        safety.push(`scopes: ${c.scopes.join(", ")}`);
+    out.push(`Safety: ${safety.join(", ")}`);
+    if (entry.aliases.length > 0)
+        out.push(`Aliases: ${entry.aliases.map(cliPath).join(", ")}`);
+    out.push("");
+    if (c.examples.length > 0) {
+        out.push("Examples:", ...c.examples.map((e) => `  ${formatInvocation(entry, e, options)}`), "");
+    }
+    return finish(out);
+}
+/** 입력 객체 → CLI 호출 문자열 (positional · 점 플래그 · 반복 · JSON 문자열) */
+export function formatInvocation(entry, input, options) {
+    const spec = cliSpec(entry);
+    const parts = [options.prog, cliPath(entry.id)];
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        return [...parts, "--input-json", shellQuote(JSON.stringify(input))].join(" ");
+    }
+    const obj = input;
+    const flags = [];
+    const known = new Set(spec.fields.map((f) => f.key));
+    if (Object.keys(obj).some((k) => !known.has(k))) {
+        return [...parts, "--input-json", shellQuote(JSON.stringify(input))].join(" ");
+    }
+    let positionalOpen = true;
+    for (const key of spec.positional) {
+        const f = spec.fields.find((x) => x.key === key);
+        const v = obj[key];
+        if (!positionalOpen || v === undefined) {
+            positionalOpen = false;
+            continue;
+        }
+        if (f.kind.type === "array" && Array.isArray(v) && key === spec.positional.at(-1)) {
+            parts.push(...v.map((x) => shellQuote(String(x))));
+        }
+        else if (isScalarKind(f.kind) && isScalarValue(v)) {
+            parts.push(shellQuote(String(v)));
+        }
+        else {
+            positionalOpen = false;
+            continue;
+        }
+        known.delete(key);
+    }
+    for (const f of spec.fields) {
+        if (!known.has(f.key) || obj[f.key] === undefined)
+            continue;
+        flags.push(...flagTokens(f, `--${f.flag}`, obj[f.key]));
+    }
+    return [...parts, ...flags].join(" ");
+}
+function flagTokens(f, flag, v) {
+    const kind = f.kind;
+    if (kind.type === "boolean" && typeof v === "boolean")
+        return [v ? flag : `--no-${flag.slice(2)}`];
+    if (kind.type === "array" && Array.isArray(v) && v.every(isScalarValue)) {
+        return v.flatMap((x) => (kind.item.type === "boolean" ? [`${flag}=${x}`] : [flag, shellQuote(String(x))]));
+    }
+    if (kind.type === "object" && typeof v === "object" && v !== null && !Array.isArray(v)) {
+        const entries = Object.entries(v);
+        const subs = kind.fields;
+        if (entries.every(([k]) => subs.some((s) => s.key === k))) {
+            return entries
+                .filter(([, x]) => x !== undefined)
+                .flatMap(([k, x]) => {
+                const s = subs.find((y) => y.key === k);
+                return flagTokens(s, `${flag}.${s.flag}`, x);
+            });
+        }
+    }
+    if (isScalarKind(kind) && isScalarValue(v))
+        return [flag, shellQuote(String(v))];
+    return [flag, shellQuote(JSON.stringify(v))];
+}
+function fieldRows(f, parent) {
+    const name = parent === "" ? f.flag : `${parent}.${f.flag}`;
+    const kind = f.kind;
+    if (kind.type === "object") {
+        const rows = [[`--${name} <json>`, annotate(f, [])]];
+        for (const s of kind.fields)
+            rows.push(...fieldRows(s, name));
+        return rows;
+    }
+    if (kind.type === "boolean")
+        return [[`--[no-]${name}`, annotate(f, [])]];
+    if (kind.type === "array") {
+        const left = kind.item.type === "boolean" ? `--${name}[=true|false]` : `--${name} <${metavar(kind.item)}>`;
+        return [[left, annotate(f, ["repeatable"])]];
+    }
+    return [[`--${name} <${metavar(kind)}>`, annotate(f, [])]];
+}
+function metavar(kind) {
+    switch (kind.type) {
+        case "string":
+            return "string";
+        case "number":
+            return "number";
+        case "boolean":
+            return "true|false";
+        case "enum":
+            return kind.values.map(String).join("|");
+        case "array":
+            return metavar(kind.item);
+        case "object":
+        case "json":
+            return "json";
+    }
+}
+function annotate(f, extra) {
+    const notes = [];
+    if (f.required)
+        notes.push("required");
+    if (f.hasDefault)
+        notes.push(`default: ${JSON.stringify(f.default)}`);
+    notes.push(...extra);
+    const tail = notes.length > 0 ? `(${notes.join(", ")})` : "";
+    return [f.description ?? "", tail].filter((s) => s !== "").join(" ");
+}
+function globalFlagLines(command) {
+    const rows = [];
+    if (command)
+        rows.push(["--input-json <json>", 'Whole input as a JSON object ("-" = read stdin)'], ["-", "Read the whole input as JSON from stdin"]);
+    rows.push(["--json", "Print the result as JSON (errors as JSON on stderr)"], ["--yes", "Approve confirmation requests"], ["-h, --help", "Show help"]);
+    return table(rows).map((l) => `  ${l}`);
+}
+function isScalarKind(kind) {
+    return kind.type === "string" || kind.type === "number" || kind.type === "boolean" || kind.type === "enum";
+}
+function isScalarValue(v) {
+    return typeof v === "string" || typeof v === "number" || typeof v === "boolean";
+}
+/** 명령어 · 네임스페이스 ID → CLI 경로 ("users.get" → "users get") */
+export function cliPath(id) {
+    return id.split(".").join(" ");
+}
+function lastSegment(id) {
+    return id.slice(id.lastIndexOf(".") + 1);
+}
+/** _index.md 첫 줄 (markdown 제목 기호 제거) */
+function summaryOf(ns) {
+    const line = ns?.description?.split("\n").find((l) => l.trim() !== "");
+    return line?.replace(/^#+\s*/, "").trim();
+}
+/** 두 칸 간격 정렬 표. 끝 공백 제거 */
+export function table(rows) {
+    const widths = [];
+    for (const row of rows)
+        row.forEach((cell, i) => (widths[i] = Math.max(widths[i] ?? 0, cell.length)));
+    return rows.map((row) => row
+        .map((cell, i) => (i === row.length - 1 ? cell : cell.padEnd(widths[i])))
+        .join("  ")
+        .trimEnd());
+}
+/** 셸에 그대로 붙여 넣을 수 있는 인용 */
+export function shellQuote(value) {
+    if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value))
+        return value;
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function finish(lines) {
+    while (lines.length > 0 && lines.at(-1) === "")
+        lines.pop();
+    return `${lines.join("\n")}\n`;
+}
+//# sourceMappingURL=help.js.map

package/dist/cli/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"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","sourcesContent":["import { findCommand } from \"../lookup.ts\"\nimport type { NamespaceInfo, RegisteredCommand, Registry } from \"../registry.ts\"\nimport { cliSpec, type CliField, type FieldKind, type ScalarKind } from \"./args.ts\"\n\n/**\n * help 생성 (D2). 일반 텍스트, ANSI 색 없음, 같은 Registry 에 같은 출력.\n * 대상 = \"\" (루트) · 네임스페이스 ID · 명령어 ID (별칭 포함). prog = 명령어 앞 접두 (\"mext run\" · \"myapp\").\n */\n\nexport interface HelpOptions {\n  /** 명령어 경로 앞에 붙는 실행 접두. 예: \"mext run\" */\n  prog: string\n}\n\nexport type HelpTarget =\n  | { kind: \"namespace\"; namespace: NamespaceInfo; command: RegisteredCommand | undefined }\n  | { kind: \"command\"; command: RegisteredCommand }\n\n/** 대상 해석. 네임스페이스가 우선 (users = 네임스페이스 + index.ts 명령어면 둘 다). 없으면 UNKNOWN_COMMAND */\nexport function resolveHelpTarget(registry: Registry, target: string): HelpTarget {\n  const ns = registry.namespaces.get(target)\n  if (ns) return { kind: \"namespace\", namespace: ns, command: target === \"\" ? undefined : registry.commands.get(target) }\n  return { kind: \"command\", command: findCommand(registry, target) }\n}\n\n/** 대상의 help 텍스트 (끝 줄바꿈 포함) */\nexport function renderHelp(registry: Registry, target: string, options: HelpOptions): string {\n  const t = resolveHelpTarget(registry, target)\n  if (t.kind === \"command\") return renderCommandHelp(t.command, options)\n  const text = renderNamespaceHelp(registry, t.namespace, options)\n  return t.command ? `${text}\\n${renderCommandHelp(t.command, options)}` : text\n}\n\nexport function renderNamespaceHelp(registry: Registry, ns: NamespaceInfo, options: HelpOptions): string {\n  const out: string[] = []\n  const path = cliPath(ns.id)\n  const prefix = path === \"\" ? options.prog : `${options.prog} ${path}`\n  if (ns.id !== \"\") out.push(`Namespace: ${path}`, \"\")\n  if (ns.description) out.push(ns.description, \"\")\n  out.push(\"Usage:\")\n  out.push(`  ${prefix} <command> [args] [flags]`)\n  if (ns.id === \"\" && ns.namespaces.length > 0) out.push(`  ${prefix} <namespace> --help`)\n  out.push(`  ${prefix} <command> --help`, \"\")\n  if (ns.namespaces.length > 0) {\n    out.push(\"Namespaces:\")\n    out.push(\n      ...table(ns.namespaces.map((id) => [lastSegment(id), summaryOf(registry.namespaces.get(id)) ?? \"\"])).map(\n        (l) => `  ${l}`,\n      ),\n      \"\",\n    )\n  }\n  if (ns.commands.length > 0) {\n    out.push(\"Commands:\")\n    out.push(\n      ...table(\n        ns.commands.map((id) => {\n          const c = registry.commands.get(id)!.command\n          return [lastSegment(id), c.description]\n        }),\n      ).map((l) => `  ${l}`),\n      \"\",\n    )\n  }\n  out.push(\"Global flags:\", ...globalFlagLines(false), \"\")\n  return finish(out)\n}\n\nexport function renderCommandHelp(entry: RegisteredCommand, options: HelpOptions): string {\n  const c = entry.command\n  const spec = cliSpec(entry)\n  const path = cliPath(entry.id)\n  const out: string[] = [c.description, \"\"]\n\n  const positional = spec.positional.map((k) => spec.fields.find((f) => f.key === k)!).filter(Boolean)\n  const usageArgs = positional.map((f) => {\n    const name = f.kind.type === \"array\" ? `${f.flag}...` : f.flag\n    return f.required ? `<${name}>` : `[${name}]`\n  })\n  out.push(\"Usage:\", `  ${[options.prog, path, ...usageArgs, \"[flags]\"].join(\" \")}`, \"\")\n\n  if (positional.length > 0) {\n    out.push(\"Arguments:\")\n    out.push(\n      ...table(positional.map((f) => [`<${f.flag}>`, annotate(f, [`or --${f.flag}`])])).map((l) => `  ${l}`),\n      \"\",\n    )\n  }\n\n  const flagRows: string[][] = []\n  for (const f of spec.fields) {\n    if (spec.positional.includes(f.key)) continue\n    flagRows.push(...fieldRows(f, \"\"))\n  }\n  if (flagRows.length > 0) out.push(\"Flags:\", ...table(flagRows).map((l) => `  ${l}`), \"\")\n\n  out.push(\"Global flags:\", ...globalFlagLines(true), \"\")\n\n  const safety = [c.readOnly ? \"read-only\" : \"writes\"]\n  if (c.destructive) safety.push(\"destructive\")\n  if (c.requiresConfirmation) safety.push(\"requires confirmation (--yes to approve)\")\n  if (c.scopes.length > 0) safety.push(`scopes: ${c.scopes.join(\", \")}`)\n  out.push(`Safety: ${safety.join(\", \")}`)\n  if (entry.aliases.length > 0) out.push(`Aliases: ${entry.aliases.map(cliPath).join(\", \")}`)\n  out.push(\"\")\n\n  if (c.examples.length > 0) {\n    out.push(\"Examples:\", ...c.examples.map((e) => `  ${formatInvocation(entry, e, options)}`), \"\")\n  }\n  return finish(out)\n}\n\n/** 입력 객체 → CLI 호출 문자열 (positional · 점 플래그 · 반복 · JSON 문자열) */\nexport function formatInvocation(entry: RegisteredCommand, input: unknown, options: HelpOptions): string {\n  const spec = cliSpec(entry)\n  const parts = [options.prog, cliPath(entry.id)]\n  if (typeof input !== \"object\" || input === null || Array.isArray(input)) {\n    return [...parts, \"--input-json\", shellQuote(JSON.stringify(input))].join(\" \")\n  }\n  const obj = input as Record<string, unknown>\n  const flags: string[] = []\n  const known = new Set(spec.fields.map((f) => f.key))\n  if (Object.keys(obj).some((k) => !known.has(k))) {\n    return [...parts, \"--input-json\", shellQuote(JSON.stringify(input))].join(\" \")\n  }\n  let positionalOpen = true\n  for (const key of spec.positional) {\n    const f = spec.fields.find((x) => x.key === key)!\n    const v = obj[key]\n    if (!positionalOpen || v === undefined) {\n      positionalOpen = false\n      continue\n    }\n    if (f.kind.type === \"array\" && Array.isArray(v) && key === spec.positional.at(-1)) {\n      parts.push(...v.map((x) => shellQuote(String(x))))\n    } else if (isScalarKind(f.kind) && isScalarValue(v)) {\n      parts.push(shellQuote(String(v)))\n    } else {\n      positionalOpen = false\n      continue\n    }\n    known.delete(key)\n  }\n  for (const f of spec.fields) {\n    if (!known.has(f.key) || obj[f.key] === undefined) continue\n    flags.push(...flagTokens(f, `--${f.flag}`, obj[f.key]))\n  }\n  return [...parts, ...flags].join(\" \")\n}\n\nfunction flagTokens(f: CliField, flag: string, v: unknown): string[] {\n  const kind = f.kind\n  if (kind.type === \"boolean\" && typeof v === \"boolean\") return [v ? flag : `--no-${flag.slice(2)}`]\n  if (kind.type === \"array\" && Array.isArray(v) && v.every(isScalarValue)) {\n    return v.flatMap((x) => (kind.item.type === \"boolean\" ? [`${flag}=${x}`] : [flag, shellQuote(String(x))]))\n  }\n  if (kind.type === \"object\" && typeof v === \"object\" && v !== null && !Array.isArray(v)) {\n    const entries = Object.entries(v as Record<string, unknown>)\n    const subs = kind.fields\n    if (entries.every(([k]) => subs.some((s) => s.key === k))) {\n      return entries\n        .filter(([, x]) => x !== undefined)\n        .flatMap(([k, x]) => {\n          const s = subs.find((y) => y.key === k)!\n          return flagTokens(s, `${flag}.${s.flag}`, x)\n        })\n    }\n  }\n  if (isScalarKind(kind) && isScalarValue(v)) return [flag, shellQuote(String(v))]\n  return [flag, shellQuote(JSON.stringify(v))]\n}\n\nfunction fieldRows(f: CliField, parent: string): string[][] {\n  const name = parent === \"\" ? f.flag : `${parent}.${f.flag}`\n  const kind = f.kind\n  if (kind.type === \"object\") {\n    const rows = [[`--${name} <json>`, annotate(f, [])]]\n    for (const s of kind.fields) rows.push(...fieldRows(s, name))\n    return rows\n  }\n  if (kind.type === \"boolean\") return [[`--[no-]${name}`, annotate(f, [])]]\n  if (kind.type === \"array\") {\n    const left = kind.item.type === \"boolean\" ? `--${name}[=true|false]` : `--${name} <${metavar(kind.item)}>`\n    return [[left, annotate(f, [\"repeatable\"])]]\n  }\n  return [[`--${name} <${metavar(kind)}>`, annotate(f, [])]]\n}\n\nfunction metavar(kind: FieldKind): string {\n  switch (kind.type) {\n    case \"string\":\n      return \"string\"\n    case \"number\":\n      return \"number\"\n    case \"boolean\":\n      return \"true|false\"\n    case \"enum\":\n      return kind.values.map(String).join(\"|\")\n    case \"array\":\n      return metavar(kind.item)\n    case \"object\":\n    case \"json\":\n      return \"json\"\n  }\n}\n\nfunction annotate(f: CliField, extra: string[]): string {\n  const notes: string[] = []\n  if (f.required) notes.push(\"required\")\n  if (f.hasDefault) notes.push(`default: ${JSON.stringify(f.default)}`)\n  notes.push(...extra)\n  const tail = notes.length > 0 ? `(${notes.join(\", \")})` : \"\"\n  return [f.description ?? \"\", tail].filter((s) => s !== \"\").join(\" \")\n}\n\nfunction globalFlagLines(command: boolean): string[] {\n  const rows: string[][] = []\n  if (command) rows.push([\"--input-json <json>\", 'Whole input as a JSON object (\"-\" = read stdin)'], [\"-\", \"Read the whole input as JSON from stdin\"])\n  rows.push(\n    [\"--json\", \"Print the result as JSON (errors as JSON on stderr)\"],\n    [\"--yes\", \"Approve confirmation requests\"],\n    [\"-h, --help\", \"Show help\"],\n  )\n  return table(rows).map((l) => `  ${l}`)\n}\n\nfunction isScalarKind(kind: FieldKind): kind is ScalarKind {\n  return kind.type === \"string\" || kind.type === \"number\" || kind.type === \"boolean\" || kind.type === \"enum\"\n}\n\nfunction isScalarValue(v: unknown): v is string | number | boolean {\n  return typeof v === \"string\" || typeof v === \"number\" || typeof v === \"boolean\"\n}\n\n/** 명령어 · 네임스페이스 ID → CLI 경로 (\"users.get\" → \"users get\") */\nexport function cliPath(id: string): string {\n  return id.split(\".\").join(\" \")\n}\n\nfunction lastSegment(id: string): string {\n  return id.slice(id.lastIndexOf(\".\") + 1)\n}\n\n/** _index.md 첫 줄 (markdown 제목 기호 제거) */\nfunction summaryOf(ns: NamespaceInfo | undefined): string | undefined {\n  const line = ns?.description?.split(\"\\n\").find((l) => l.trim() !== \"\")\n  return line?.replace(/^#+\\s*/, \"\").trim()\n}\n\n/** 두 칸 간격 정렬 표. 끝 공백 제거 */\nexport function table(rows: readonly (readonly string[])[]): string[] {\n  const widths: number[] = []\n  for (const row of rows) row.forEach((cell, i) => (widths[i] = Math.max(widths[i] ?? 0, cell.length)))\n  return rows.map((row) =>\n    row\n      .map((cell, i) => (i === row.length - 1 ? cell : cell.padEnd(widths[i]!)))\n      .join(\"  \")\n      .trimEnd(),\n  )\n}\n\n/** 셸에 그대로 붙여 넣을 수 있는 인용 */\nexport function shellQuote(value: string): string {\n  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) return value\n  return `'${value.replace(/'/g, `'\\\\''`)}'`\n}\n\nfunction finish(lines: string[]): string {\n  while (lines.length > 0 && lines.at(-1) === \"\") lines.pop()\n  return `${lines.join(\"\\n\")}\\n`\n}\n"]}

package/dist/cli/io.d.ts

@@ -0,0 +1,26 @@
+import type { Readable } from "node:stream";
+export interface CliWriter {
+    write(chunk: string): unknown;
+}
+/** CLI 실행 환경. 테스트는 일부만 주입 (나머지 = process) */
+export interface CliIo {
+    stdin: Readable;
+    stdout: CliWriter;
+    stderr: CliWriter;
+    /** 대화형 터미널 여부 (stdin · stderr). false 면 ctx.ask = 즉시 오류 (--yes 의 confirm 제외) */
+    isTTY: boolean;
+    env: Record<string, string | undefined>;
+    cwd: string;
+    /** abort = SIGINT. ctx.signal 로 전달, exit 130 */
+    signal?: AbortSignal;
+}
+export declare function resolveIo(io?: Partial<CliIo>): CliIo;
+/** stdin 전체 (stdin - 입력) */
+export declare function readAll(stdin: Readable): Promise<string>;
+/** 대화형 프롬프트용 줄 읽기. 한 실행에서 readline 하나를 공유 (버퍼 유실 방지) */
+export interface LineReader {
+    /** 프롬프트를 stderr 에 쓰고 한 줄 읽기. EOF = undefined. signal abort = undefined */
+    question(prompt: string, signal?: AbortSignal): Promise<string | undefined>;
+    close(): void;
+}
+export declare function createLineReader(io: CliIo): LineReader;

package/dist/cli/io.js

@@ -0,0 +1,74 @@
+import { createInterface } from "node:readline";
+export function resolveIo(io = {}) {
+    return {
+        stdin: io.stdin ?? process.stdin,
+        stdout: io.stdout ?? process.stdout,
+        stderr: io.stderr ?? process.stderr,
+        isTTY: io.isTTY ?? (process.stdin.isTTY === true && process.stderr.isTTY === true),
+        env: io.env ?? process.env,
+        cwd: io.cwd ?? process.cwd(),
+        signal: io.signal,
+    };
+}
+/** stdin 전체 (stdin - 입력) */
+export async function readAll(stdin) {
+    let text = "";
+    for await (const chunk of stdin)
+        text += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+    return text;
+}
+export function createLineReader(io) {
+    let rl;
+    const lines = [];
+    const waiting = [];
+    let closed = false;
+    const open = () => {
+        if (rl || closed)
+            return;
+        rl = createInterface({ input: io.stdin, terminal: false });
+        rl.on("line", (line) => {
+            const next = waiting.shift();
+            if (next)
+                next(line);
+            else
+                lines.push(line);
+        });
+        rl.on("close", () => {
+            closed = true;
+            for (const w of waiting.splice(0))
+                w(undefined);
+        });
+    };
+    return {
+        question(prompt, signal) {
+            io.stderr.write(prompt);
+            if (lines.length > 0)
+                return Promise.resolve(lines.shift());
+            open();
+            if (closed)
+                return Promise.resolve(undefined);
+            return new Promise((resolve) => {
+                const done = (line) => {
+                    signal?.removeEventListener("abort", onAbort);
+                    resolve(line);
+                };
+                const onAbort = () => {
+                    const i = waiting.indexOf(done);
+                    if (i >= 0)
+                        waiting.splice(i, 1);
+                    done(undefined);
+                };
+                if (signal?.aborted)
+                    return done(undefined);
+                signal?.addEventListener("abort", onAbort, { once: true });
+                waiting.push(done);
+            });
+        },
+        close() {
+            closed = true;
+            rl?.close();
+            rl = undefined;
+        },
+    };
+}
+//# sourceMappingURL=io.js.map

package/dist/cli/io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.js","sourceRoot":"","sources":["../../src/cli/io.ts"],"names":[],"mappings":"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","sourcesContent":["import { createInterface, type Interface } from \"node:readline\"\nimport type { Readable } from \"node:stream\"\n\nexport interface CliWriter {\n  write(chunk: string): unknown\n}\n\n/** CLI 실행 환경. 테스트는 일부만 주입 (나머지 = process) */\nexport interface CliIo {\n  stdin: Readable\n  stdout: CliWriter\n  stderr: CliWriter\n  /** 대화형 터미널 여부 (stdin · stderr). false 면 ctx.ask = 즉시 오류 (--yes 의 confirm 제외) */\n  isTTY: boolean\n  env: Record<string, string | undefined>\n  cwd: string\n  /** abort = SIGINT. ctx.signal 로 전달, exit 130 */\n  signal?: AbortSignal\n}\n\nexport function resolveIo(io: Partial<CliIo> = {}): CliIo {\n  return {\n    stdin: io.stdin ?? process.stdin,\n    stdout: io.stdout ?? process.stdout,\n    stderr: io.stderr ?? process.stderr,\n    isTTY: io.isTTY ?? (process.stdin.isTTY === true && process.stderr.isTTY === true),\n    env: io.env ?? process.env,\n    cwd: io.cwd ?? process.cwd(),\n    signal: io.signal,\n  }\n}\n\n/** stdin 전체 (stdin - 입력) */\nexport async function readAll(stdin: Readable): Promise<string> {\n  let text = \"\"\n  for await (const chunk of stdin) text += typeof chunk === \"string\" ? chunk : Buffer.from(chunk as Uint8Array).toString(\"utf8\")\n  return text\n}\n\n/** 대화형 프롬프트용 줄 읽기. 한 실행에서 readline 하나를 공유 (버퍼 유실 방지) */\nexport interface LineReader {\n  /** 프롬프트를 stderr 에 쓰고 한 줄 읽기. EOF = undefined. signal abort = undefined */\n  question(prompt: string, signal?: AbortSignal): Promise<string | undefined>\n  close(): void\n}\n\nexport function createLineReader(io: CliIo): LineReader {\n  let rl: Interface | undefined\n  const lines: string[] = []\n  const waiting: ((line: string | undefined) => void)[] = []\n  let closed = false\n\n  const open = (): void => {\n    if (rl || closed) return\n    rl = createInterface({ input: io.stdin, terminal: false })\n    rl.on(\"line\", (line) => {\n      const next = waiting.shift()\n      if (next) next(line)\n      else lines.push(line)\n    })\n    rl.on(\"close\", () => {\n      closed = true\n      for (const w of waiting.splice(0)) w(undefined)\n    })\n  }\n\n  return {\n    question(prompt, signal) {\n      io.stderr.write(prompt)\n      if (lines.length > 0) return Promise.resolve(lines.shift())\n      open()\n      if (closed) return Promise.resolve(undefined)\n      return new Promise((resolve) => {\n        const done = (line: string | undefined): void => {\n          signal?.removeEventListener(\"abort\", onAbort)\n          resolve(line)\n        }\n        const onAbort = (): void => {\n          const i = waiting.indexOf(done)\n          if (i >= 0) waiting.splice(i, 1)\n          done(undefined)\n        }\n        if (signal?.aborted) return done(undefined)\n        signal?.addEventListener(\"abort\", onAbort, { once: true })\n        waiting.push(done)\n      })\n    },\n    close() {\n      closed = true\n      rl?.close()\n      rl = undefined\n    },\n  }\n}\n"]}

package/dist/cli/login.d.ts

@@ -0,0 +1,32 @@
+import { type BrowserOpener } from "../remote/browser.ts";
+import { type CliIo } from "./io.ts";
+/**
+ * login · logout 명령 공통 설정. mext CLI = { bin: "mext" }, 고객 CLI = { bin, url } (설정의 cli.bin · cli.url).
+ * bin = 안내 문구의 실행 파일 이름 · 환경변수 접두 (<BIN>_URL · <BIN>_CREDENTIALS_FILE · <BIN>_NO_KEYRING) ·
+ * 자격 증명 위치 (~/.config/<bin> · 키체인 service "<bin> credentials") · 동적 등록 client_name.
+ */
+export interface AuthCommandOptions {
+    bin: string;
+    /** 고정 서버 URL (고객 CLI). --url 로 덮어쓸 수 있다. 없으면 --url 또는 <BIN>_URL 필수 */
+    url?: string;
+    /** 브라우저 열기 (테스트 주입). 기본 = BROWSER · open · xdg-open */
+    openBrowser?: BrowserOpener;
+    /** 브라우저 판정용 (테스트 주입). 기본 process.platform */
+    platform?: NodeJS.Platform;
+    /** 인가 서버 요청 (테스트 주입) */
+    fetch?: typeof fetch;
+    /** device flow polling 대기 (테스트 주입) */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/**
+ * <bin> login — MCP authorization (OAuth 2.1 · PKCE) 로 토큰 발급 · 저장. 서버 URL 별 (키체인 · credentials.json).
+ * redirect = loopback (127.0.0.1) 또는 붙여넣은 redirect URL (TTY). device flow = 인가 서버가 지원할 때 (--device,
+ * 브라우저를 열지 않는 환경이면 자동). --with-token = stdin 한 줄을 API key 로 저장.
+ */
+export declare function loginCommand(options: AuthCommandOptions): (argv: readonly string[], io: CliIo) => Promise<number>;
+/** mext login */
+export declare const runLogin: (argv: readonly string[], io: CliIo) => Promise<number>;
+/** 서버 URL = --url → 고정 URL (고객 CLI) → <BIN>_URL */
+export declare function resolveServerUrl(options: AuthCommandOptions, flag: string | undefined, io: CliIo): string | {
+    error: string;
+};