@obov/mext 0.0.0-stage → 0.2.0

package/dist/cli/args.d.ts

@@ -0,0 +1,107 @@
+import type { InputSchema } from "../command.ts";
+import { MextError, type ArgumentIssue, type BuildIssue } from "../errors.ts";
+import type { JsonSchema, RegisteredCommand, Registry } from "../registry.ts";
+/**
+ * CLI 입력 변환 (spec §4).
+ * 필드 종류는 Zod def 로, 설명 · 기본값 · 필수 여부는 input JSON Schema 로 판단한다.
+ * 파서는 문자열을 객체로 모으기만 하고 (스키마 모양에 따른 number · boolean · enum 변환 포함) 검증은 invoke 의 Zod safeParse 1회.
+ */
+export type Primitive = string | number | boolean;
+export type ScalarKind = {
+    type: "string";
+} | {
+    type: "number";
+} | {
+    type: "boolean";
+} | {
+    type: "enum";
+    values: readonly Primitive[];
+};
+export type FieldKind = ScalarKind
+/** 원시 타입 배열. 플래그 반복 */
+ | {
+    type: "array";
+    item: ScalarKind;
+}
+/** z.object 1단. 점 플래그 (--filter.status) 또는 JSON 문자열 */
+ | {
+    type: "object";
+    fields: readonly CliField[];
+}
+/** 2단 이상 · union · record 등. JSON 문자열 */
+ | {
+    type: "json";
+};
+export interface CliField {
+    /** input 키 (camelCase) */
+    key: string;
+    /** 플래그 이름 (kebab-case, "--" 제외) */
+    flag: string;
+    kind: FieldKind;
+    description: string | undefined;
+    required: boolean;
+    hasDefault: boolean;
+    default: unknown;
+}
+export interface CliSpec {
+    fields: readonly CliField[];
+    /** positional 로 받는 input 키 순서 */
+    positional: readonly string[];
+}
+/** mext run 이 명령어 플래그 위치에서도 가로채는 플래그. input 키와 겹치면 빌드 오류 */
+export declare const RESERVED_FLAGS: readonly string[];
+export interface ParsedArgs {
+    /** invoke 에 넘길 원본 입력 (검증 전) */
+    input: unknown;
+    json: boolean;
+    yes: boolean;
+    help: boolean;
+}
+export interface ParseArgsOptions {
+    /** stdin (-) · --input-json - 입력. 기본 = 빈 문자열 */
+    readStdin?: () => Promise<string>;
+}
+/** camelCase → kebab-case (userId → user-id · URLPath → url-path) */
+export declare function toKebab(key: string): string;
+/**
+ * input 스키마 → CLI 필드. problems = 변환 불가 (any · 함수 등) · 플래그로 쓸 수 없는 키 · 플래그 충돌 · 예약 플래그.
+ * jsonSchema = input JSON Schema (io input). 설명 · 기본값 · 필수 여부의 원본
+ */
+export declare function analyzeInput(schema: InputSchema, jsonSchema: JsonSchema | undefined, positional?: readonly string[]): {
+    spec: CliSpec;
+    problems: string[];
+};
+/**
+ * Registry 밖 명령어 (원격 help 로 만든 항목) 의 CLI 필드 지정. 이후 cliSpec · parseArgs · help 가 이 값을 쓴다.
+ * 로컬 명령어는 Zod 스키마로 분석하므로 쓰지 않는다
+ */
+export declare function defineCliSpec(entry: RegisteredCommand, spec: CliSpec): void;
+/**
+ * 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 declare function cliSpecFromJsonSchema(jsonSchema: JsonSchema, positional?: readonly string[]): CliSpec;
+/** 명령어의 CLI 필드 (캐시) */
+export declare function cliSpec(entry: RegisteredCommand): CliSpec;
+/** Registry 전체의 CLI 변환 불가 문제 (빌드 오류 issues) */
+export declare function cliBuildIssues(registry: Registry): BuildIssue[];
+/** 변환 불가 타입이 있으면 MextBuildError */
+export declare function assertCliConvertible(registry: Registry): void;
+/** 원시 · 배열 · 객체 · JSON 필드 종류에 맞춘 문자열 변환. JSON 파싱 실패 = undefined (호출자가 오류) */
+export declare function coerceValue(kind: FieldKind, raw: string): {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+};
+/** 파서 단계 INVALID_ARGUMENT */
+export declare function argumentError(entry: RegisteredCommand, issues: ArgumentIssue[]): MextError<"INVALID_ARGUMENT">;
+/**
+ * 명령어 경로 뒤의 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 declare function parseArgs(entry: RegisteredCommand, argv: readonly string[], options?: ParseArgsOptions): Promise<ParsedArgs>;