@obov/mext 0.0.0-stage → 0.1.0

package/dist/cli/args.js

@@ -0,0 +1,621 @@
+import { MextBuildError, MextError } from "../errors.js";
+import { closest } from "../suggest.js";
+/** mext run 이 명령어 플래그 위치에서도 가로채는 플래그. input 키와 겹치면 빌드 오류 */
+export const RESERVED_FLAGS = ["help", "json", "yes", "input-json"];
+const WRAPPERS = new Set(["optional", "nullable", "default", "prefault", "catch", "readonly", "nonoptional"]);
+const UNCONVERTIBLE = new Set([
+    "any",
+    "unknown",
+    "function",
+    "promise",
+    "symbol",
+    "custom",
+    "transform",
+    "never",
+    "void",
+    "undefined",
+    "bigint",
+    "date",
+    "map",
+    "set",
+    "file",
+]);
+function defOf(schema) {
+    return schema._zod.def;
+}
+/** optional · nullable · default · pipe (입력 쪽) · lazy 등을 벗긴 실제 타입 */
+function unwrap(schema) {
+    let cur = schema;
+    for (let depth = 0; depth < 32; depth++) {
+        const def = defOf(cur);
+        if (WRAPPERS.has(def.type) && def.innerType)
+            cur = def.innerType;
+        else if (def.type === "pipe" && def.in && def.out)
+            cur = defOf(def.in).type === "transform" ? def.out : def.in;
+        else if (def.type === "lazy" && def.getter)
+            cur = def.getter();
+        else
+            return cur;
+    }
+    return cur;
+}
+function scalarOf(schema) {
+    const base = unwrap(schema);
+    const def = defOf(base);
+    switch (def.type) {
+        case "string":
+        case "template_literal":
+            return { type: "string" };
+        case "number":
+            return { type: "number" };
+        case "boolean":
+            return { type: "boolean" };
+        case "enum":
+        case "literal":
+        case "union": {
+            const values = literalValues(base);
+            return values ? { type: "enum", values } : undefined;
+        }
+    }
+    if (UNCONVERTIBLE.has(def.type))
+        return { type: "unconvertible", zodType: def.type };
+    return undefined;
+}
+/** enum · 리터럴 · 리터럴만의 union → 값 목록. 그 외 undefined */
+function literalValues(schema) {
+    const def = defOf(unwrap(schema));
+    let raw;
+    if (def.type === "enum")
+        raw = Object.values(def.entries ?? {});
+    else if (def.type === "literal")
+        raw = [...(def.values ?? [])];
+    else if (def.type === "union") {
+        raw = [];
+        for (const option of def.options ?? []) {
+            const values = literalValues(option);
+            if (!values)
+                return undefined;
+            raw.push(...values);
+        }
+    }
+    else
+        return undefined;
+    if (!raw.every((v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean"))
+        return undefined;
+    return [...new Set(raw)];
+}
+function analyze(schema, topLevel) {
+    const scalar = scalarOf(schema);
+    if (scalar)
+        return scalar;
+    const base = unwrap(schema);
+    const def = defOf(base);
+    if (def.type === "array" && def.element) {
+        const item = scalarOf(def.element);
+        return item && item.type !== "unconvertible" ? { type: "array", item } : { type: "json" };
+    }
+    if (def.type === "object" && topLevel) {
+        const fields = [];
+        for (const [key, sub] of Object.entries(def.shape ?? {})) {
+            const kind = analyze(sub, false);
+            if (kind.type === "unconvertible" || kind.type === "json" || kind.type === "object")
+                return { type: "json" };
+            fields.push(field(key, kind, undefined));
+        }
+        return { type: "object", fields };
+    }
+    return { type: "json" };
+}
+function field(key, kind, json, required = false) {
+    const has = json !== undefined && Object.hasOwn(json, "default");
+    return {
+        key,
+        flag: toKebab(key),
+        kind,
+        description: typeof json?.description === "string" ? json.description : undefined,
+        required,
+        hasDefault: has,
+        default: has ? json.default : undefined,
+    };
+}
+/** camelCase → kebab-case (userId → user-id · URLPath → url-path) */
+export function toKebab(key) {
+    return key
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/([A-Z])([A-Z][a-z])/g, "$1-$2")
+        .toLowerCase();
+}
+const FLAG_PATTERN = /^[a-z0-9]+(?:[-_][a-z0-9]+)*$/;
+/** JSON Schema 의 객체 (nullable 이면 anyOf 안) */
+function objectSchema(json) {
+    if (!json)
+        return undefined;
+    if (typeof json.properties === "object" && json.properties !== null)
+        return json;
+    for (const key of ["anyOf", "oneOf"]) {
+        const list = json[key];
+        if (Array.isArray(list)) {
+            const found = list.find((s) => typeof s === "object" && s !== null && "properties" in s);
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+function propertiesOf(json) {
+    const obj = objectSchema(json);
+    return {
+        props: obj?.properties ?? {},
+        required: Array.isArray(obj?.required) ? obj.required : [],
+    };
+}
+/**
+ * input 스키마 → CLI 필드. problems = 변환 불가 (any · 함수 등) · 플래그로 쓸 수 없는 키 · 플래그 충돌 · 예약 플래그.
+ * jsonSchema = input JSON Schema (io input). 설명 · 기본값 · 필수 여부의 원본
+ */
+export function analyzeInput(schema, jsonSchema, positional = []) {
+    const problems = [];
+    const fields = [];
+    const { props, required } = propertiesOf(jsonSchema);
+    const shape = schema._zod.def.shape ?? {};
+    const flags = new Map();
+    for (const [key, sub] of Object.entries(shape)) {
+        const kind = analyze(sub, true);
+        if (kind.type === "unconvertible") {
+            problems.push(`input "${key}": z.${kind.zodType}() is not convertible to CLI flags`);
+            continue;
+        }
+        const f = field(key, kind, props[key], required.includes(key));
+        if (!FLAG_PATTERN.test(f.flag)) {
+            problems.push(`input "${key}": key cannot be a CLI flag (use camelCase letters and digits)`);
+            continue;
+        }
+        if (RESERVED_FLAGS.includes(f.flag)) {
+            problems.push(`input "${key}": --${f.flag} is reserved by the CLI`);
+            continue;
+        }
+        const other = flags.get(f.flag);
+        if (other !== undefined) {
+            problems.push(`input "${key}": --${f.flag} collides with input "${other}"`);
+            continue;
+        }
+        if (kind.type === "object") {
+            const sub = propertiesOf(props[key]);
+            const subFlags = new Set();
+            const subs = [];
+            for (const s of kind.fields) {
+                const sf = field(s.key, s.kind, sub.props[s.key], sub.required.includes(s.key));
+                if (!FLAG_PATTERN.test(sf.flag)) {
+                    problems.push(`input "${key}.${s.key}": key cannot be a CLI flag (use camelCase letters and digits)`);
+                    continue;
+                }
+                if (subFlags.has(sf.flag)) {
+                    problems.push(`input "${key}.${s.key}": --${f.flag}.${sf.flag} collides with another key`);
+                    continue;
+                }
+                subFlags.add(sf.flag);
+                subs.push(sf);
+            }
+            f.kind = { type: "object", fields: subs };
+        }
+        flags.set(f.flag, key);
+        fields.push(f);
+    }
+    // --no-x 와 같은 이름의 플래그가 있으면 모호
+    for (const f of fields) {
+        if (f.flag.startsWith("no-") && isBooleanKind(fields.find((g) => g.flag === f.flag.slice(3))?.kind)) {
+            problems.push(`input "${f.key}": --${f.flag} collides with the negation of --${f.flag.slice(3)}`);
+        }
+    }
+    return { spec: { fields, positional: [...positional] }, problems };
+}
+function isBooleanKind(kind) {
+    return kind?.type === "boolean" || (kind?.type === "array" && kind.item.type === "boolean");
+}
+const specCache = new WeakMap();
+function analyzed(entry) {
+    let result = specCache.get(entry);
+    if (!result) {
+        result = analyzeInput(entry.command.input, entry.inputSchema, entry.command.positional);
+        specCache.set(entry, result);
+    }
+    return result;
+}
+/**
+ * Registry 밖 명령어 (원격 help 로 만든 항목) 의 CLI 필드 지정. 이후 cliSpec · parseArgs · help 가 이 값을 쓴다.
+ * 로컬 명령어는 Zod 스키마로 분석하므로 쓰지 않는다
+ */
+export function defineCliSpec(entry, spec) {
+    specCache.set(entry, { spec, problems: [] });
+}
+// ---------------------------------------------------------------- JSON Schema 분석 (원격)
+/**
+ * input JSON Schema (원격 help 의 inputSchema) → CLI 필드. 로컬 (Zod) 분석과 같은 규칙을 JSON Schema 모양으로:
+ * type string · number · integer · boolean · enum · const · 리터럴 anyOf = 원시, nullable (anyOf null) 은 벗김,
+ * 원시 배열 = 반복, 최상위 1단 객체 (하위 전부 원시 · 원시 배열) = 점 플래그, 그 외 = JSON 문자열.
+ * 플래그로 쓸 수 없는 키 · 예약 플래그 · 충돌 키는 건너뛴다 (--input-json 으로 전달)
+ */
+export function cliSpecFromJsonSchema(jsonSchema, positional = []) {
+    const { props, required } = propertiesOf(jsonSchema);
+    const fields = [];
+    const flags = new Set();
+    for (const [key, sub] of Object.entries(props)) {
+        const kind = jsonKind(sub, true);
+        const f = field(key, kind, sub, required.includes(key));
+        if (!FLAG_PATTERN.test(f.flag) || RESERVED_FLAGS.includes(f.flag) || flags.has(f.flag))
+            continue;
+        if (kind.type === "object") {
+            const subProps = propertiesOf(stripNullable(sub));
+            const subs = [];
+            const subFlags = new Set();
+            for (const s of kind.fields) {
+                const sf = field(s.key, s.kind, subProps.props[s.key], subProps.required.includes(s.key));
+                if (!FLAG_PATTERN.test(sf.flag) || subFlags.has(sf.flag))
+                    continue;
+                subFlags.add(sf.flag);
+                subs.push(sf);
+            }
+            f.kind = { type: "object", fields: subs };
+        }
+        flags.add(f.flag);
+        fields.push(f);
+    }
+    return { fields, positional: positional.filter((k) => fields.some((f) => f.key === k)) };
+}
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPrimitive(value) {
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+/** anyOf · oneOf 에서 { type: "null" } 을 뺀 나머지가 하나면 그것, type 배열의 "null" 제거 */
+function stripNullable(schema) {
+    for (const key of ["anyOf", "oneOf"]) {
+        const list = schema[key];
+        if (!Array.isArray(list))
+            continue;
+        const rest = list.filter((s) => !(isJsonObject(s) && s.type === "null"));
+        if (rest.length === 1 && rest.length < list.length && isJsonObject(rest[0]))
+            return rest[0];
+    }
+    if (Array.isArray(schema.type)) {
+        const types = schema.type.filter((t) => t !== "null");
+        if (types.length === 1)
+            return { ...schema, type: types[0] };
+    }
+    return schema;
+}
+function jsonLiterals(schema) {
+    if (Array.isArray(schema.enum))
+        return schema.enum.every(isPrimitive) ? [...new Set(schema.enum)] : undefined;
+    if ("const" in schema)
+        return isPrimitive(schema.const) ? [schema.const] : undefined;
+    for (const key of ["anyOf", "oneOf"]) {
+        const list = schema[key];
+        if (!Array.isArray(list))
+            continue;
+        const out = [];
+        for (const option of list) {
+            const values = isJsonObject(option) ? jsonLiterals(option) : undefined;
+            if (!values)
+                return undefined;
+            out.push(...values);
+        }
+        return [...new Set(out)];
+    }
+    return undefined;
+}
+function jsonScalar(raw) {
+    if (!isJsonObject(raw))
+        return undefined;
+    const schema = stripNullable(raw);
+    const values = jsonLiterals(schema);
+    if (values)
+        return { type: "enum", values };
+    switch (schema.type) {
+        case "string":
+            return { type: "string" };
+        case "number":
+        case "integer":
+            return { type: "number" };
+        case "boolean":
+            return { type: "boolean" };
+    }
+    return undefined;
+}
+function jsonKind(raw, topLevel) {
+    const scalar = jsonScalar(raw);
+    if (scalar)
+        return scalar;
+    if (!isJsonObject(raw))
+        return { type: "json" };
+    const schema = stripNullable(raw);
+    if (schema.type === "array" && isJsonObject(schema.items)) {
+        const item = jsonScalar(schema.items);
+        return item ? { type: "array", item } : { type: "json" };
+    }
+    if (topLevel && schema.type === "object" && isJsonObject(schema.properties)) {
+        const fields = [];
+        for (const [key, sub] of Object.entries(schema.properties)) {
+            const kind = jsonKind(sub, false);
+            if (kind.type === "json" || kind.type === "object")
+                return { type: "json" };
+            fields.push(field(key, kind, undefined));
+        }
+        return { type: "object", fields };
+    }
+    return { type: "json" };
+}
+/** 명령어의 CLI 필드 (캐시) */
+export function cliSpec(entry) {
+    return analyzed(entry).spec;
+}
+/** Registry 전체의 CLI 변환 불가 문제 (빌드 오류 issues) */
+export function cliBuildIssues(registry) {
+    const issues = [];
+    for (const entry of registry.commands.values()) {
+        for (const message of analyzed(entry).problems) {
+            issues.push({ code: "CLI_UNCONVERTIBLE", message, id: entry.id, file: entry.file });
+        }
+    }
+    return issues;
+}
+/** 변환 불가 타입이 있으면 MextBuildError */
+export function assertCliConvertible(registry) {
+    const issues = cliBuildIssues(registry);
+    if (issues.length > 0)
+        throw new MextBuildError(issues);
+}
+function resolveFlag(spec, name) {
+    const top = spec.fields.find((f) => f.flag === name);
+    if (top)
+        return { field: top, negated: false };
+    const dot = name.indexOf(".");
+    if (dot > 0) {
+        const parent = spec.fields.find((f) => f.flag === name.slice(0, dot));
+        if (parent?.kind.type === "object") {
+            const sub = parent.kind.fields.find((f) => f.flag === name.slice(dot + 1));
+            if (sub)
+                return { field: parent, sub, negated: false };
+        }
+    }
+    if (name.startsWith("no-")) {
+        const r = resolveFlag(spec, name.slice(3));
+        if (r && !r.negated && isBooleanKind((r.sub ?? r.field).kind))
+            return { ...r, negated: true };
+    }
+    return undefined;
+}
+/** 사용 가능한 플래그 이름 전체 (제안용) */
+function allFlags(spec) {
+    const out = [];
+    for (const f of spec.fields) {
+        out.push(f.flag);
+        if (isBooleanKind(f.kind))
+            out.push(`no-${f.flag}`);
+        if (f.kind.type === "object") {
+            for (const s of f.kind.fields) {
+                out.push(`${f.flag}.${s.flag}`);
+                if (isBooleanKind(s.kind))
+                    out.push(`no-${f.flag}.${s.flag}`);
+            }
+        }
+    }
+    return [...out, ...RESERVED_FLAGS];
+}
+function coerceScalar(kind, raw) {
+    switch (kind.type) {
+        case "string":
+            return raw;
+        case "number": {
+            const n = Number(raw);
+            return raw.trim() !== "" && Number.isFinite(n) ? n : raw;
+        }
+        case "boolean":
+            return raw === "true" ? true : raw === "false" ? false : raw;
+        case "enum":
+            return kind.values.find((v) => String(v) === raw) ?? raw;
+    }
+}
+/** 원시 · 배열 · 객체 · JSON 필드 종류에 맞춘 문자열 변환. JSON 파싱 실패 = undefined (호출자가 오류) */
+export function coerceValue(kind, raw) {
+    if (kind.type === "array")
+        return { ok: true, value: coerceScalar(kind.item, raw) };
+    if (kind.type === "object" || kind.type === "json") {
+        try {
+            return { ok: true, value: JSON.parse(raw) };
+        }
+        catch {
+            return { ok: false };
+        }
+    }
+    return { ok: true, value: coerceScalar(kind, raw) };
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** 파서 단계 INVALID_ARGUMENT */
+export function argumentError(entry, issues) {
+    return new MextError("INVALID_ARGUMENT", `Invalid arguments for ${entry.id}: ${issues.map((i) => i.message).join("; ")}`, {
+        command: entry.id,
+        missing_fields: [],
+        issues,
+        expected_schema: entry.inputSchema,
+        examples: [...entry.command.examples],
+    });
+}
+/**
+ * 명령어 경로 뒤의 argv → 원본 입력.
+ * --flag v · --flag=v · boolean --x · --x=true|false · --no-x · 반복 (배열) · --obj.key v · JSON 문자열 ·
+ * --input-json <json|-> · - (stdin) · positional · -- 이후 = positional. 모르는 플래그는 항상 오류.
+ * 개별 플래그는 --input-json · stdin 입력의 같은 키를 덮어쓴다 (점 플래그는 객체 안에 병합).
+ */
+export async function parseArgs(entry, argv, options = {}) {
+    const spec = cliSpec(entry);
+    const fail = (path, code, message) => {
+        throw argumentError(entry, [{ path, code, message }]);
+    };
+    const values = {};
+    const given = new Set(); // 지정된 경로 (배열 제외). "filter" = JSON 전체 · "filter.status" = 점 플래그
+    const flags = { json: false, yes: false, help: false };
+    const positionals = [];
+    let source;
+    let rest = false;
+    const setInput = (next, label) => {
+        if (source)
+            fail("", "duplicate_input", `${label}: whole input given more than once (--input-json · -)`);
+        source = next;
+    };
+    const assign = (r, value, label) => {
+        const target = r.sub ?? r.field;
+        const path = r.sub ? `${r.field.key}.${r.sub.key}` : r.field.key;
+        if (r.sub) {
+            if (given.has(r.field.key))
+                fail(path, "conflict", `${label} cannot be combined with --${r.field.flag} <json>`);
+        }
+        else if (r.field.kind.type === "object" && [...given].some((p) => p.startsWith(`${r.field.key}.`))) {
+            fail(path, "conflict", `${label} <json> cannot be combined with --${r.field.flag}.<key>`);
+        }
+        let container = values;
+        if (r.sub) {
+            const existing = values[r.field.key];
+            if (!isPlainObject(existing))
+                values[r.field.key] = {};
+            container = values[r.field.key];
+        }
+        if (target.kind.type === "array") {
+            const list = container[target.key];
+            if (Array.isArray(list))
+                list.push(value);
+            else
+                container[target.key] = [value];
+            return;
+        }
+        if (given.has(path))
+            fail(path, "duplicate_flag", `${label} given more than once`);
+        given.add(path);
+        container[target.key] = value;
+    };
+    const coerce = (r, raw, label) => {
+        const kind = r.sub ? r.sub.kind : r.field.kind;
+        const result = coerceValue(kind, raw);
+        if (!result.ok) {
+            return fail(r.sub ? `${r.field.key}.${r.sub.key}` : r.field.key, "invalid_json", `${label}: value is not valid JSON`);
+        }
+        return result.value;
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        if (rest) {
+            positionals.push(tok);
+            continue;
+        }
+        if (tok === "--") {
+            rest = true;
+            continue;
+        }
+        if (tok === "-") {
+            setInput({ kind: "stdin" }, "-");
+            continue;
+        }
+        if (tok === "-h") {
+            flags.help = true;
+            continue;
+        }
+        if (tok.startsWith("--")) {
+            const body = tok.slice(2);
+            const eq = body.indexOf("=");
+            const name = eq < 0 ? body : body.slice(0, eq);
+            const inline = eq < 0 ? undefined : body.slice(eq + 1);
+            const label = `--${name}`;
+            const takeValue = () => {
+                if (inline !== undefined)
+                    return inline;
+                const next = argv[i + 1];
+                if (next === undefined || (next.startsWith("--") && next.length > 2)) {
+                    return fail("", "missing_value", `${label} requires a value`);
+                }
+                i++;
+                return next;
+            };
+            if (name === "help" || name === "json" || name === "yes") {
+                if (inline !== undefined)
+                    fail("", "unexpected_value", `${label} does not take a value`);
+                flags[name] = true;
+                continue;
+            }
+            if (name === "input-json") {
+                const text = takeValue();
+                setInput(text === "-" ? { kind: "stdin" } : { kind: "json", text }, label);
+                continue;
+            }
+            const r = resolveFlag(spec, name);
+            if (!r) {
+                const suggested = closest(name, allFlags(spec).map((f) => [f, f]));
+                const hint = suggested.length > 0 ? ` Did you mean --${suggested[0]}?` : "";
+                return fail("", "unknown_flag", `unknown flag ${label}.${hint}`);
+            }
+            const kind = (r.sub ?? r.field).kind;
+            if (isBooleanKind(kind)) {
+                if (r.negated) {
+                    if (inline !== undefined)
+                        fail("", "unexpected_value", `${label} does not take a value`);
+                    assign(r, false, label);
+                }
+                else {
+                    assign(r, inline === undefined ? true : coerceScalar({ type: "boolean" }, inline), label);
+                }
+                continue;
+            }
+            assign(r, coerce(r, takeValue(), label), label);
+            continue;
+        }
+        if (tok.startsWith("-") && !/^-[\d.]/.test(tok)) {
+            fail("", "unknown_flag", `unknown flag ${tok} (short flags are not supported)`);
+        }
+        positionals.push(tok);
+    }
+    // positional
+    let p = 0;
+    for (let k = 0; k < spec.positional.length && p < positionals.length; k++) {
+        const f = spec.fields.find((x) => x.key === spec.positional[k]);
+        if (!f)
+            continue;
+        const r = { field: f, negated: false };
+        const label = `<${f.flag}>`;
+        const variadic = f.kind.type === "array" && k === spec.positional.length - 1;
+        do {
+            assign(r, coerce(r, positionals[p], label), label);
+            p++;
+        } while (variadic && p < positionals.length);
+    }
+    if (p < positionals.length)
+        fail("", "unexpected_argument", `unexpected argument "${positionals[p]}"`);
+    let input = values;
+    if (source) {
+        const text = source.kind === "stdin" ? await (options.readStdin ?? (async () => ""))() : source.text;
+        let base;
+        try {
+            base = JSON.parse(text);
+        }
+        catch {
+            return fail("", "invalid_json", `${source.kind === "stdin" ? "stdin" : "--input-json"} is not valid JSON`);
+        }
+        if (Object.keys(values).length === 0)
+            input = base;
+        else if (!isPlainObject(base)) {
+            fail("", "invalid_json", "whole input must be a JSON object to combine with flags");
+        }
+        else {
+            const merged = { ...base };
+            for (const [key, value] of Object.entries(values)) {
+                // 점 플래그로 모은 객체는 병합, 그 외 (JSON 문자열 포함) 는 덮어쓰기
+                const dotted = !given.has(key) && spec.fields.find((x) => x.key === key)?.kind.type === "object";
+                merged[key] = dotted && isPlainObject(base[key]) && isPlainObject(value) ? { ...base[key], ...value } : value;
+            }
+            input = merged;
+        }
+    }
+    return { input, ...flags };
+}
+//# sourceMappingURL=args.js.map