@procedures/mark 0.33.0 → 0.35.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +108 -0
- package/README.md +2 -0
- package/dist/.tsbuildinfo +1 -1
- package/dist/args.d.ts +5 -53
- package/dist/args.d.ts.map +1 -1
- package/dist/args.js +9 -341
- package/dist/args.js.map +1 -1
- package/dist/ask.d.ts +3 -38
- package/dist/ask.d.ts.map +1 -1
- package/dist/ask.js +3 -81
- package/dist/ask.js.map +1 -1
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +18 -64
- package/dist/cli.js.map +1 -1
- package/dist/client-mode.js +3 -3
- package/dist/client-mode.js.map +1 -1
- package/dist/failure.d.ts +3 -2
- package/dist/failure.d.ts.map +1 -1
- package/dist/failure.js +3 -33
- package/dist/failure.js.map +1 -1
- package/dist/format.d.ts +3 -25
- package/dist/format.d.ts.map +1 -1
- package/dist/format.js +3 -120
- package/dist/format.js.map +1 -1
- package/dist/manifest.d.ts.map +1 -1
- package/dist/manifest.js +3 -9
- package/dist/manifest.js.map +1 -1
- package/dist/manifest.json +23 -21
- package/dist/parse.d.ts +4 -114
- package/dist/parse.d.ts.map +1 -1
- package/dist/parse.js +7 -445
- package/dist/parse.js.map +1 -1
- package/package.json +50 -50
- package/src/args.ts +14 -403
- package/src/ask.ts +14 -109
- package/src/cli.ts +16 -70
- package/src/client-mode.ts +3 -3
- package/src/failure.ts +3 -33
- package/src/format.ts +3 -172
- package/src/manifest.ts +3 -8
- package/src/parse.ts +33 -570
- package/dist/prompts.d.ts +0 -58
- package/dist/prompts.d.ts.map +0 -1
- package/dist/prompts.js +0 -124
- package/dist/prompts.js.map +0 -1
- package/src/prompts.ts +0 -181
package/src/parse.ts
CHANGED
|
@@ -1,378 +1,39 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Schema-based CLI Argument Parser
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
4
|
+
* The field types, the conversion of CLI text and the help text are in `@procedures/cli-kit`
|
|
5
|
+
* (roadmap O61). This module gives them to mark with the name `mark` and the global flags of mark.
|
|
6
6
|
*/
|
|
7
7
|
|
|
8
8
|
import { CLI_GLOBAL_FLAGS } from "@procedures/lib/cli-flags";
|
|
9
|
-
import {
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
| "literal"
|
|
38
|
-
| "date"
|
|
39
|
-
| "array"
|
|
40
|
-
| "record"
|
|
41
|
-
| "object"
|
|
42
|
-
| "union"
|
|
43
|
-
| "any";
|
|
44
|
-
|
|
45
|
-
/**
|
|
46
|
-
* The type of a schema field, as the CLI sees it
|
|
47
|
-
*/
|
|
48
|
-
export interface FieldType {
|
|
49
|
-
kind: FieldKind;
|
|
50
|
-
/** The item type of an array */
|
|
51
|
-
item?: FieldType;
|
|
52
|
-
/** The value type of a record */
|
|
53
|
-
value?: FieldType;
|
|
54
|
-
/** The member types of a union */
|
|
55
|
-
options?: FieldType[];
|
|
56
|
-
/** The values of an enum */
|
|
57
|
-
values?: readonly string[];
|
|
58
|
-
/** The value of a literal */
|
|
59
|
-
literal?: unknown;
|
|
60
|
-
}
|
|
61
|
-
|
|
62
|
-
/**
|
|
63
|
-
* Extracted schema field info for help generation
|
|
64
|
-
*/
|
|
65
|
-
export interface SchemaFieldInfo {
|
|
66
|
-
name: string;
|
|
67
|
-
/** The display name of the type, for the help text */
|
|
68
|
-
type: string;
|
|
69
|
-
/** The type the CLI converts values to */
|
|
70
|
-
fieldType: FieldType;
|
|
71
|
-
required: boolean;
|
|
72
|
-
description: string | undefined;
|
|
73
|
-
defaultValue: unknown;
|
|
74
|
-
enumValues: readonly string[] | undefined;
|
|
75
|
-
}
|
|
76
|
-
|
|
77
|
-
/**
|
|
78
|
-
* A JSON Schema node, as `jsonSchemaOf()` of the core gives it (draft-07).
|
|
79
|
-
*/
|
|
80
|
-
interface JsonNode {
|
|
81
|
-
type?: string | string[];
|
|
82
|
-
description?: string;
|
|
83
|
-
default?: unknown;
|
|
84
|
-
enum?: unknown[];
|
|
85
|
-
const?: unknown;
|
|
86
|
-
format?: string;
|
|
87
|
-
items?: JsonNode | JsonNode[];
|
|
88
|
-
properties?: Record<string, JsonNode>;
|
|
89
|
-
required?: string[];
|
|
90
|
-
additionalProperties?: boolean | JsonNode;
|
|
91
|
-
anyOf?: JsonNode[];
|
|
92
|
-
oneOf?: JsonNode[];
|
|
93
|
-
allOf?: JsonNode[];
|
|
94
|
-
}
|
|
95
|
-
|
|
96
|
-
/** True for the JSON Schema of `null` (a nullable field is `anyOf: [T, null]`). */
|
|
97
|
-
function isNull(node: JsonNode): boolean {
|
|
98
|
-
return node.type === "null" || (node.const === null && node.type === undefined);
|
|
99
|
-
}
|
|
100
|
-
|
|
101
|
-
/** The members of a union, without `null` (a nullable value is the type itself on the CLI). */
|
|
102
|
-
function unionMembers(node: JsonNode): JsonNode[] | undefined {
|
|
103
|
-
const members = node.anyOf ?? node.oneOf;
|
|
104
|
-
return members?.filter((member) => !isNull(member));
|
|
105
|
-
}
|
|
106
|
-
|
|
107
|
-
/**
|
|
108
|
-
* The CLI type of a JSON Schema node.
|
|
109
|
-
*/
|
|
110
|
-
function fieldTypeOfJson(node: JsonNode | undefined): FieldType {
|
|
111
|
-
if (!node || typeof node !== "object") {
|
|
112
|
-
return { kind: "any" };
|
|
113
|
-
}
|
|
114
|
-
const members = unionMembers(node);
|
|
115
|
-
if (members) {
|
|
116
|
-
if (members.length === 1) return fieldTypeOfJson(members[0]);
|
|
117
|
-
// A union of string constants is an enum on the CLI
|
|
118
|
-
if (members.length > 1 && members.every((member) => typeof member.const === "string")) {
|
|
119
|
-
return { kind: "enum", values: members.map((member) => member.const as string) };
|
|
120
|
-
}
|
|
121
|
-
return { kind: "union", options: members.map((member) => fieldTypeOfJson(member)) };
|
|
122
|
-
}
|
|
123
|
-
if (node.allOf?.length === 1) {
|
|
124
|
-
return fieldTypeOfJson(node.allOf[0]);
|
|
125
|
-
}
|
|
126
|
-
if (Array.isArray(node.enum)) {
|
|
127
|
-
return node.enum.every((value) => typeof value === "string")
|
|
128
|
-
? { kind: "enum", values: node.enum as string[] }
|
|
129
|
-
: { kind: "any" };
|
|
130
|
-
}
|
|
131
|
-
if ("const" in node && node.const !== undefined) {
|
|
132
|
-
return { kind: "literal", literal: node.const };
|
|
133
|
-
}
|
|
134
|
-
const types = Array.isArray(node.type) ? node.type.filter((type) => type !== "null") : node.type ? [node.type] : [];
|
|
135
|
-
if (types.length > 1) {
|
|
136
|
-
return { kind: "union", options: types.map((type) => fieldTypeOfJson({ ...node, type })) };
|
|
137
|
-
}
|
|
138
|
-
switch (types[0]) {
|
|
139
|
-
case "string":
|
|
140
|
-
return node.format === "date-time" || node.format === "date" ? { kind: "date" } : { kind: "string" };
|
|
141
|
-
case "number":
|
|
142
|
-
case "integer":
|
|
143
|
-
return { kind: "number" };
|
|
144
|
-
case "boolean":
|
|
145
|
-
return { kind: "boolean" };
|
|
146
|
-
case "array":
|
|
147
|
-
return { kind: "array", item: fieldTypeOfJson(Array.isArray(node.items) ? undefined : node.items) };
|
|
148
|
-
case "object": {
|
|
149
|
-
const extra = node.additionalProperties;
|
|
150
|
-
const hasFields = node.properties && Object.keys(node.properties).length > 0;
|
|
151
|
-
if (!hasFields && extra && typeof extra === "object") {
|
|
152
|
-
return { kind: "record", value: fieldTypeOfJson(extra) };
|
|
153
|
-
}
|
|
154
|
-
return { kind: "object" };
|
|
155
|
-
}
|
|
156
|
-
default:
|
|
157
|
-
return { kind: "any" };
|
|
158
|
-
}
|
|
159
|
-
}
|
|
160
|
-
|
|
161
|
-
/**
|
|
162
|
-
* The JSON Schema of a procedure schema (or a JSON Schema itself, as the manifest stores it).
|
|
163
|
-
*/
|
|
164
|
-
function asJsonSchema(schema: unknown): JsonNode | undefined {
|
|
165
|
-
if (!schema || typeof schema !== "object") {
|
|
166
|
-
return undefined;
|
|
167
|
-
}
|
|
168
|
-
// A JSON Schema already (from the manifest): it has no validator
|
|
169
|
-
const props = schema as Record<string, unknown>;
|
|
170
|
-
if (!("~standard" in props) && typeof props["safeParse"] !== "function" && typeof props["parse"] !== "function") {
|
|
171
|
-
return schema as JsonNode;
|
|
172
|
-
}
|
|
173
|
-
return jsonSchemaOf(schema as ProcedureSchema) as JsonNode | undefined;
|
|
174
|
-
}
|
|
175
|
-
|
|
176
|
-
/**
|
|
177
|
-
* The CLI type of a schema: a procedure schema (a Standard Schema such as zod 4) or its JSON
|
|
178
|
-
* Schema. The type comes from the JSON Schema, so every schema library works. (Before, the
|
|
179
|
-
* parser read the private fields of zod 3.)
|
|
180
|
-
*/
|
|
181
|
-
export function fieldTypeOf(schema: unknown): FieldType {
|
|
182
|
-
return fieldTypeOfJson(asJsonSchema(schema));
|
|
183
|
-
}
|
|
184
|
-
|
|
185
|
-
/**
|
|
186
|
-
* The display name of a type, for the help text
|
|
187
|
-
*/
|
|
188
|
-
function typeName(type: FieldType): string {
|
|
189
|
-
switch (type.kind) {
|
|
190
|
-
case "array":
|
|
191
|
-
return `${typeName(type.item ?? { kind: "any" })}[]`;
|
|
192
|
-
case "record":
|
|
193
|
-
return "key=value";
|
|
194
|
-
case "object":
|
|
195
|
-
case "any":
|
|
196
|
-
return "json";
|
|
197
|
-
case "union":
|
|
198
|
-
return (type.options ?? []).map(typeName).join("|");
|
|
199
|
-
case "literal":
|
|
200
|
-
return JSON.stringify(type.literal);
|
|
201
|
-
default:
|
|
202
|
-
return type.kind;
|
|
203
|
-
}
|
|
204
|
-
}
|
|
205
|
-
|
|
206
|
-
/**
|
|
207
|
-
* Extract field information from a schema: a procedure schema or its JSON Schema. A schema that
|
|
208
|
-
* is not an object (or that has no JSON Schema) gives no fields: the CLI then passes its flags
|
|
209
|
-
* through.
|
|
210
|
-
*/
|
|
211
|
-
export function extractSchemaFields(schema: unknown): SchemaFieldInfo[] {
|
|
212
|
-
const json = asJsonSchema(schema);
|
|
213
|
-
const object = json && !json.properties ? unionMembers(json)?.find((member) => member.properties) : json;
|
|
214
|
-
if (!object?.properties) {
|
|
215
|
-
return [];
|
|
216
|
-
}
|
|
217
|
-
const required = new Set(object.required ?? []);
|
|
218
|
-
const fields: SchemaFieldInfo[] = [];
|
|
219
|
-
for (const [name, field] of Object.entries(object.properties)) {
|
|
220
|
-
if (!field || typeof field !== "object") {
|
|
221
|
-
continue;
|
|
222
|
-
}
|
|
223
|
-
const fieldType = fieldTypeOfJson(field);
|
|
224
|
-
const description = field.description ?? unionMembers(field)?.find((member) => member.description)?.description;
|
|
225
|
-
fields.push({
|
|
226
|
-
name,
|
|
227
|
-
type: fieldType.kind === "enum" ? "enum" : typeName(fieldType),
|
|
228
|
-
fieldType,
|
|
229
|
-
required: required.has(name) && field.default === undefined,
|
|
230
|
-
description,
|
|
231
|
-
defaultValue: field.default,
|
|
232
|
-
enumValues: fieldType.kind === "enum" ? fieldType.values : undefined,
|
|
233
|
-
});
|
|
234
|
-
}
|
|
235
|
-
return fields;
|
|
236
|
-
}
|
|
237
|
-
|
|
238
|
-
// =============================================================================
|
|
239
|
-
// Conversion of CLI text to the field types
|
|
240
|
-
// =============================================================================
|
|
241
|
-
|
|
242
|
-
/** The result of a conversion: the value, or a message for the user */
|
|
243
|
-
export type Converted = { ok: true; value: unknown } | { ok: false; error: string };
|
|
244
|
-
|
|
245
|
-
// The digits before the point and the digits after it are two groups, so each text has one match
|
|
246
|
-
const NUMBER_TEXT = /^[-+]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][-+]?\d+)?$|^0[xX][0-9a-fA-F]+$/;
|
|
247
|
-
const SAFE_INTEGER_LIMIT = BigInt(Number.MAX_SAFE_INTEGER);
|
|
248
|
-
|
|
249
|
-
/**
|
|
250
|
-
* Text as a JSON value, when it is JSON. A whole number that a JavaScript number cannot hold
|
|
251
|
-
* exactly stays text. Anything that is not JSON stays text.
|
|
252
|
-
*/
|
|
253
|
-
function jsonOrText(text: string): unknown {
|
|
254
|
-
const trimmed = text.trim();
|
|
255
|
-
if (/^-?\d+$/.test(trimmed)) {
|
|
256
|
-
const big = BigInt(trimmed);
|
|
257
|
-
if (big > SAFE_INTEGER_LIMIT || big < -SAFE_INTEGER_LIMIT) {
|
|
258
|
-
return text;
|
|
259
|
-
}
|
|
260
|
-
}
|
|
261
|
-
try {
|
|
262
|
-
return JSON.parse(trimmed);
|
|
263
|
-
} catch {
|
|
264
|
-
return text;
|
|
265
|
-
}
|
|
266
|
-
}
|
|
267
|
-
|
|
268
|
-
/**
|
|
269
|
-
* Convert the CLI text of one value to a field type
|
|
270
|
-
*/
|
|
271
|
-
export function convertValue(text: string, type: FieldType, label: string): Converted {
|
|
272
|
-
switch (type.kind) {
|
|
273
|
-
case "string":
|
|
274
|
-
case "date":
|
|
275
|
-
return { ok: true, value: text };
|
|
276
|
-
case "enum":
|
|
277
|
-
return { ok: true, value: text };
|
|
278
|
-
case "number": {
|
|
279
|
-
if (!NUMBER_TEXT.test(text.trim())) {
|
|
280
|
-
return { ok: false, error: `${label} needs a number, not "${text}"` };
|
|
281
|
-
}
|
|
282
|
-
return { ok: true, value: Number(text) };
|
|
283
|
-
}
|
|
284
|
-
case "bigint":
|
|
285
|
-
try {
|
|
286
|
-
return { ok: true, value: BigInt(text) };
|
|
287
|
-
} catch {
|
|
288
|
-
return { ok: false, error: `${label} needs a whole number, not "${text}"` };
|
|
289
|
-
}
|
|
290
|
-
case "boolean":
|
|
291
|
-
if (text === "true") return { ok: true, value: true };
|
|
292
|
-
if (text === "false") return { ok: true, value: false };
|
|
293
|
-
return { ok: false, error: `${label} needs true or false, not "${text}"` };
|
|
294
|
-
case "literal": {
|
|
295
|
-
const literal = type.literal;
|
|
296
|
-
if (typeof literal === "number") return convertValue(text, { kind: "number" }, label);
|
|
297
|
-
if (typeof literal === "boolean") return convertValue(text, { kind: "boolean" }, label);
|
|
298
|
-
return { ok: true, value: text };
|
|
299
|
-
}
|
|
300
|
-
case "array": {
|
|
301
|
-
const item = type.item ?? { kind: "any" };
|
|
302
|
-
if (text.trimStart().startsWith("[")) {
|
|
303
|
-
const parsed = jsonOrText(text);
|
|
304
|
-
if (Array.isArray(parsed)) {
|
|
305
|
-
return { ok: true, value: parsed };
|
|
306
|
-
}
|
|
307
|
-
}
|
|
308
|
-
const converted = convertValue(text, item, label);
|
|
309
|
-
return converted.ok ? { ok: true, value: [converted.value] } : converted;
|
|
310
|
-
}
|
|
311
|
-
case "record": {
|
|
312
|
-
if (text.trimStart().startsWith("{")) {
|
|
313
|
-
const parsed = jsonOrText(text);
|
|
314
|
-
if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
|
|
315
|
-
return { ok: true, value: parsed };
|
|
316
|
-
}
|
|
317
|
-
return { ok: false, error: `${label} needs key=value or a JSON object` };
|
|
318
|
-
}
|
|
319
|
-
const eq = text.indexOf("=");
|
|
320
|
-
if (eq <= 0) {
|
|
321
|
-
return { ok: false, error: `${label} needs key=value, not "${text}"` };
|
|
322
|
-
}
|
|
323
|
-
const converted = convertValue(text.slice(eq + 1), type.value ?? { kind: "any" }, label);
|
|
324
|
-
return converted.ok ? { ok: true, value: { [text.slice(0, eq)]: converted.value } } : converted;
|
|
325
|
-
}
|
|
326
|
-
case "object": {
|
|
327
|
-
const parsed = jsonOrText(text);
|
|
328
|
-
if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
|
|
329
|
-
return { ok: true, value: parsed };
|
|
330
|
-
}
|
|
331
|
-
return { ok: false, error: `${label} needs a JSON object, not "${text}"` };
|
|
332
|
-
}
|
|
333
|
-
case "union": {
|
|
334
|
-
const options = type.options ?? [];
|
|
335
|
-
// Zod tries the members in order: a member that takes text takes the text as it is
|
|
336
|
-
for (const option of options) {
|
|
337
|
-
if (option.kind === "string" || option.kind === "date") return { ok: true, value: text };
|
|
338
|
-
if (option.kind === "enum" && option.values?.includes(text)) return { ok: true, value: text };
|
|
339
|
-
if (option.kind === "literal" && String(option.literal) === text) {
|
|
340
|
-
return { ok: true, value: option.literal };
|
|
341
|
-
}
|
|
342
|
-
}
|
|
343
|
-
for (const option of options) {
|
|
344
|
-
if (option.kind === "enum" || option.kind === "literal") continue;
|
|
345
|
-
const converted = convertValue(text, option, label);
|
|
346
|
-
if (converted.ok) return converted;
|
|
347
|
-
}
|
|
348
|
-
return { ok: true, value: jsonOrText(text) };
|
|
349
|
-
}
|
|
350
|
-
case "any":
|
|
351
|
-
default:
|
|
352
|
-
return { ok: true, value: jsonOrText(text) };
|
|
353
|
-
}
|
|
354
|
-
}
|
|
355
|
-
|
|
356
|
-
/**
|
|
357
|
-
* Add a converted value to a field that already has one. Arrays collect and records merge,
|
|
358
|
-
* so a repeated flag adds to the field. Other fields take the last value.
|
|
359
|
-
*/
|
|
360
|
-
export function mergeValue(previous: unknown, next: unknown, type: FieldType): unknown {
|
|
361
|
-
if (previous === undefined) {
|
|
362
|
-
return next;
|
|
363
|
-
}
|
|
364
|
-
if (type.kind === "array" && Array.isArray(previous) && Array.isArray(next)) {
|
|
365
|
-
return [...previous, ...next];
|
|
366
|
-
}
|
|
367
|
-
if (
|
|
368
|
-
type.kind === "record" &&
|
|
369
|
-
previous && typeof previous === "object" && !Array.isArray(previous) &&
|
|
370
|
-
next && typeof next === "object" && !Array.isArray(next)
|
|
371
|
-
) {
|
|
372
|
-
return { ...previous, ...next };
|
|
373
|
-
}
|
|
374
|
-
return next;
|
|
375
|
-
}
|
|
9
|
+
import {
|
|
10
|
+
convertValue,
|
|
11
|
+
extractSchemaFields,
|
|
12
|
+
generateHelp as kitGenerateHelp,
|
|
13
|
+
toCamel,
|
|
14
|
+
toKebab,
|
|
15
|
+
type CLIMeta,
|
|
16
|
+
type FieldType,
|
|
17
|
+
type SchemaFieldInfo,
|
|
18
|
+
} from "@procedures/cli-kit";
|
|
19
|
+
|
|
20
|
+
export {
|
|
21
|
+
convertValue,
|
|
22
|
+
extractSchemaFields,
|
|
23
|
+
fieldTypeOf,
|
|
24
|
+
fieldsOf,
|
|
25
|
+
mergeValue,
|
|
26
|
+
resultFieldsOf,
|
|
27
|
+
resultFieldsOfSchema,
|
|
28
|
+
toCamel,
|
|
29
|
+
toKebab,
|
|
30
|
+
type CLIMeta,
|
|
31
|
+
type CommandLike,
|
|
32
|
+
type Converted,
|
|
33
|
+
type FieldKind,
|
|
34
|
+
type FieldType,
|
|
35
|
+
type SchemaFieldInfo,
|
|
36
|
+
} from "@procedures/cli-kit";
|
|
376
37
|
|
|
377
38
|
// =============================================================================
|
|
378
39
|
// The old parameter interface
|
|
@@ -391,20 +52,6 @@ export interface Parameters {
|
|
|
391
52
|
string?: string;
|
|
392
53
|
}
|
|
393
54
|
|
|
394
|
-
/**
|
|
395
|
-
* Convert camelCase to kebab-case
|
|
396
|
-
*/
|
|
397
|
-
export function toKebab(str: string): string {
|
|
398
|
-
return str.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
|
|
399
|
-
}
|
|
400
|
-
|
|
401
|
-
/**
|
|
402
|
-
* Convert kebab-case to camelCase
|
|
403
|
-
*/
|
|
404
|
-
export function toCamel(str: string): string {
|
|
405
|
-
return str.replace(/-([a-zA-Z0-9])/g, (_, c: string) => c.toUpperCase());
|
|
406
|
-
}
|
|
407
|
-
|
|
408
55
|
/**
|
|
409
56
|
* Convert one parameter by the type of its field. A value that is not text (true for a flag
|
|
410
57
|
* with no value) is not changed.
|
|
@@ -469,80 +116,8 @@ export function parseFromSchema(
|
|
|
469
116
|
// Help
|
|
470
117
|
// =============================================================================
|
|
471
118
|
|
|
472
|
-
/**
|
|
473
|
-
|
|
474
|
-
*/
|
|
475
|
-
function valueHint(field: SchemaFieldInfo): string {
|
|
476
|
-
const type = field.fieldType;
|
|
477
|
-
switch (type.kind) {
|
|
478
|
-
case "boolean":
|
|
479
|
-
return "";
|
|
480
|
-
case "array":
|
|
481
|
-
return ` <${typeName(type.item ?? { kind: "any" })}>... (repeat the flag, or give a JSON array)`;
|
|
482
|
-
case "record":
|
|
483
|
-
return " <key=value>... (repeat the flag, or give a JSON object)";
|
|
484
|
-
case "object":
|
|
485
|
-
case "any":
|
|
486
|
-
return " <json>";
|
|
487
|
-
case "enum":
|
|
488
|
-
return ` <${(field.enumValues ?? []).join("|")}>`;
|
|
489
|
-
default:
|
|
490
|
-
return ` <${typeName(type)}>`;
|
|
491
|
-
}
|
|
492
|
-
}
|
|
493
|
-
|
|
494
|
-
/**
|
|
495
|
-
* A command as mark sees it: a procedure of the registry (with its input schema), or a command
|
|
496
|
-
* of the manifest (with the fields of its input). See manifest.ts.
|
|
497
|
-
*/
|
|
498
|
-
export interface CommandLike {
|
|
499
|
-
path: readonly string[];
|
|
500
|
-
metadata?: unknown;
|
|
501
|
-
/** The input schema of a procedure of the registry */
|
|
502
|
-
input?: unknown;
|
|
503
|
-
/** The output schema of a procedure of the registry */
|
|
504
|
-
output?: unknown;
|
|
505
|
-
/** The fields of the input of a command of the manifest */
|
|
506
|
-
fields?: readonly SchemaFieldInfo[];
|
|
507
|
-
/** The fields of the result of a command of the manifest */
|
|
508
|
-
resultFields?: readonly SchemaFieldInfo[];
|
|
509
|
-
}
|
|
510
|
-
|
|
511
|
-
/** The fields of the input of a command: from the manifest, or read from the schema */
|
|
512
|
-
export function fieldsOf(command: CommandLike): SchemaFieldInfo[] {
|
|
513
|
-
return command.fields ? [...command.fields] : extractSchemaFields(command.input);
|
|
514
|
-
}
|
|
515
|
-
|
|
516
|
-
/**
|
|
517
|
-
* The fields of the result of a procedure, from its output schema: only for a result that is an
|
|
518
|
-
* object (a union, a stream item or a pass-through schema gives none).
|
|
519
|
-
*/
|
|
520
|
-
export function resultFieldsOfSchema(output: unknown): SchemaFieldInfo[] {
|
|
521
|
-
const json = output ? (jsonSchemaOf(output as ProcedureSchema, { io: "output" }) as JsonNode | undefined) : undefined;
|
|
522
|
-
if (!json) return [];
|
|
523
|
-
if (json.type === "object") return extractSchemaFields(json);
|
|
524
|
-
// A number, a string, a boolean or an array: the help shows the one value (`mark client add`)
|
|
525
|
-
if (typeof json.type === "string" && ["number", "integer", "string", "boolean", "array"].includes(json.type)) {
|
|
526
|
-
const fieldType = fieldTypeOfJson(json);
|
|
527
|
-
return [
|
|
528
|
-
{
|
|
529
|
-
name: "value",
|
|
530
|
-
type: typeName(fieldType),
|
|
531
|
-
fieldType,
|
|
532
|
-
required: true,
|
|
533
|
-
description: json.description,
|
|
534
|
-
defaultValue: undefined,
|
|
535
|
-
enumValues: undefined,
|
|
536
|
-
},
|
|
537
|
-
];
|
|
538
|
-
}
|
|
539
|
-
return [];
|
|
540
|
-
}
|
|
541
|
-
|
|
542
|
-
/** The fields of the result of a command: from the manifest, or read from the output schema */
|
|
543
|
-
export function resultFieldsOf(command: CommandLike): SchemaFieldInfo[] {
|
|
544
|
-
return command.resultFields ? [...command.resultFields] : resultFieldsOfSchema(command.output);
|
|
545
|
-
}
|
|
119
|
+
/** The global flags that the help of a command lists: not the modes, the options of --server or --version. */
|
|
120
|
+
const HELP_GLOBALS = CLI_GLOBAL_FLAGS.filter((flag) => !flag.mode && !flag.serverOption && flag.long !== "version");
|
|
546
121
|
|
|
547
122
|
/**
|
|
548
123
|
* Generate help text for a procedure based on its metadata and schema. `schema` is the input
|
|
@@ -555,117 +130,5 @@ export function generateHelp(
|
|
|
555
130
|
schema?: unknown,
|
|
556
131
|
result: readonly SchemaFieldInfo[] = []
|
|
557
132
|
): string {
|
|
558
|
-
|
|
559
|
-
const shorts = meta.shorts ?? {};
|
|
560
|
-
|
|
561
|
-
const lines: string[] = [];
|
|
562
|
-
|
|
563
|
-
// Extract schema fields for enhanced help
|
|
564
|
-
const schemaFields: SchemaFieldInfo[] = Array.isArray(schema)
|
|
565
|
-
? (schema as SchemaFieldInfo[])
|
|
566
|
-
: schema
|
|
567
|
-
? extractSchemaFields(schema)
|
|
568
|
-
: [];
|
|
569
|
-
const schemaFieldMap = new Map(schemaFields.map((f) => [f.name, f]));
|
|
570
|
-
|
|
571
|
-
// Command signature: the last positional array takes the rest of the arguments
|
|
572
|
-
const cmdName = `mark ${path.join(" ")}`;
|
|
573
|
-
const posStr = positionalArgs
|
|
574
|
-
.map((a, i) => {
|
|
575
|
-
const many = i === positionalArgs.length - 1 && schemaFieldMap.get(a)?.fieldType.kind === "array";
|
|
576
|
-
return many ? `<${a}...>` : `<${a}>`;
|
|
577
|
-
})
|
|
578
|
-
.join(" ");
|
|
579
|
-
lines.push(`Usage: ${cmdName}${posStr ? " " + posStr : ""} [options]`);
|
|
580
|
-
lines.push("");
|
|
581
|
-
|
|
582
|
-
if (meta.description) {
|
|
583
|
-
lines.push(meta.description);
|
|
584
|
-
lines.push("");
|
|
585
|
-
}
|
|
586
|
-
|
|
587
|
-
// Positional args with schema info
|
|
588
|
-
if (positionalArgs.length > 0) {
|
|
589
|
-
lines.push("Arguments:");
|
|
590
|
-
for (const arg of positionalArgs) {
|
|
591
|
-
const fieldInfo = schemaFieldMap.get(arg);
|
|
592
|
-
const typeStr = fieldInfo ? ` (${fieldInfo.type})` : "";
|
|
593
|
-
const reqStr = fieldInfo?.required ? " [required]" : "";
|
|
594
|
-
const descStr = fieldInfo?.description ? ` ${fieldInfo.description}` : "";
|
|
595
|
-
lines.push(` ${arg}${typeStr}${reqStr}`);
|
|
596
|
-
if (descStr) {
|
|
597
|
-
lines.push(` ${descStr}`);
|
|
598
|
-
}
|
|
599
|
-
}
|
|
600
|
-
lines.push("");
|
|
601
|
-
}
|
|
602
|
-
|
|
603
|
-
// Options: each schema field that is not positional, with its short flag if it has one
|
|
604
|
-
const optionLines: string[] = [];
|
|
605
|
-
const positionalSet = new Set(positionalArgs);
|
|
606
|
-
const listed = new Set<string>();
|
|
607
|
-
const optionFields = [
|
|
608
|
-
...Object.keys(shorts).map((name) => schemaFieldMap.get(name) ?? fieldWithoutSchema(name)),
|
|
609
|
-
...schemaFields.filter((field) => !(field.name in shorts) && !positionalSet.has(field.name)),
|
|
610
|
-
];
|
|
611
|
-
for (const field of optionFields) {
|
|
612
|
-
if (listed.has(field.name)) {
|
|
613
|
-
continue;
|
|
614
|
-
}
|
|
615
|
-
listed.add(field.name);
|
|
616
|
-
const short = shorts[field.name];
|
|
617
|
-
const kebab = toKebab(field.name);
|
|
618
|
-
const flag = short ? ` -${short}, --${kebab}` : ` --${kebab}`;
|
|
619
|
-
const negation = field.fieldType.kind === "boolean" ? ` (or --no-${kebab})` : "";
|
|
620
|
-
const reqStr = field.required ? " [required]" : "";
|
|
621
|
-
const defaultStr = field.defaultValue !== undefined ? ` (default: ${JSON.stringify(field.defaultValue)})` : "";
|
|
622
|
-
optionLines.push(`${flag}${valueHint(field)}${negation}${reqStr}${defaultStr}`);
|
|
623
|
-
if (field.description) {
|
|
624
|
-
optionLines.push(` ${field.description}`);
|
|
625
|
-
}
|
|
626
|
-
}
|
|
627
|
-
|
|
628
|
-
if (optionLines.length > 0) {
|
|
629
|
-
lines.push("Options:");
|
|
630
|
-
lines.push(...optionLines);
|
|
631
|
-
}
|
|
632
|
-
|
|
633
|
-
// The fields of the result (roadmap 2.1: the output schemas describe them)
|
|
634
|
-
if (result.length > 0) {
|
|
635
|
-
lines.push("");
|
|
636
|
-
lines.push("Result:");
|
|
637
|
-
for (const field of result) {
|
|
638
|
-
const optional = field.required ? "" : ", optional";
|
|
639
|
-
lines.push(` ${field.name} (${field.type}${optional})`);
|
|
640
|
-
if (field.description) {
|
|
641
|
-
lines.push(` ${field.description}`);
|
|
642
|
-
}
|
|
643
|
-
}
|
|
644
|
-
}
|
|
645
|
-
|
|
646
|
-
// Standard options
|
|
647
|
-
lines.push("");
|
|
648
|
-
lines.push("Global Options (before the command, or after it when the command has no flag of that name):");
|
|
649
|
-
for (const flag of CLI_GLOBAL_FLAGS) {
|
|
650
|
-
if (flag.mode || flag.serverOption || flag.long === "version") {
|
|
651
|
-
continue;
|
|
652
|
-
}
|
|
653
|
-
const name = flag.short ? `-${flag.short}, --${flag.long}` : ` --${flag.long}`;
|
|
654
|
-
lines.push(` ${name.padEnd(18)} ${flag.description}`);
|
|
655
|
-
}
|
|
656
|
-
|
|
657
|
-
return lines.join("\n");
|
|
658
|
-
}
|
|
659
|
-
|
|
660
|
-
/** A field that only the metadata names (the schema has no readable shape) */
|
|
661
|
-
function fieldWithoutSchema(name: string): SchemaFieldInfo {
|
|
662
|
-
return {
|
|
663
|
-
name,
|
|
664
|
-
type: "json",
|
|
665
|
-
fieldType: { kind: "any" },
|
|
666
|
-
required: false,
|
|
667
|
-
description: undefined,
|
|
668
|
-
defaultValue: undefined,
|
|
669
|
-
enumValues: undefined,
|
|
670
|
-
};
|
|
133
|
+
return kitGenerateHelp(path, meta, schema, result, { name: "mark", globals: HELP_GLOBALS });
|
|
671
134
|
}
|
package/dist/prompts.d.ts
DELETED
|
@@ -1,58 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Interactive Prompts
|
|
3
|
-
*
|
|
4
|
-
* Wraps @clack/prompts for beautiful, modern CLI prompts.
|
|
5
|
-
* Used by Vite, Astro, and other modern tools.
|
|
6
|
-
*/
|
|
7
|
-
import * as p from "@clack/prompts";
|
|
8
|
-
type TextResult = Promise<string | symbol>;
|
|
9
|
-
type ConfirmResult = Promise<boolean | symbol>;
|
|
10
|
-
type SelectResult<T> = Promise<T | symbol>;
|
|
11
|
-
type MultiselectResult<T> = Promise<T[] | symbol>;
|
|
12
|
-
type PasswordResult = Promise<string | symbol>;
|
|
13
|
-
type SpinnerInstance = ReturnType<typeof p.spinner>;
|
|
14
|
-
/** Prompts interface for type annotation */
|
|
15
|
-
export interface Prompts {
|
|
16
|
-
text: (message: string, options?: {
|
|
17
|
-
placeholder?: string;
|
|
18
|
-
defaultValue?: string;
|
|
19
|
-
}) => TextResult;
|
|
20
|
-
confirm: (message: string, options?: {
|
|
21
|
-
initialValue?: boolean;
|
|
22
|
-
}) => ConfirmResult;
|
|
23
|
-
select: <T extends string>(message: string, options: Array<{
|
|
24
|
-
value: T;
|
|
25
|
-
label: string;
|
|
26
|
-
hint?: string;
|
|
27
|
-
}>) => SelectResult<T>;
|
|
28
|
-
multiselect: <T extends string>(message: string, options: Array<{
|
|
29
|
-
value: T;
|
|
30
|
-
label: string;
|
|
31
|
-
hint?: string;
|
|
32
|
-
}>) => MultiselectResult<T>;
|
|
33
|
-
password: (message: string) => PasswordResult;
|
|
34
|
-
group: typeof p.group;
|
|
35
|
-
intro: (msg: string) => void;
|
|
36
|
-
outro: (msg: string) => void;
|
|
37
|
-
spinner: () => SpinnerInstance;
|
|
38
|
-
log: {
|
|
39
|
-
info: (msg: string) => void;
|
|
40
|
-
success: (msg: string) => void;
|
|
41
|
-
warn: (msg: string) => void;
|
|
42
|
-
error: (msg: string) => void;
|
|
43
|
-
message: (msg: string) => void;
|
|
44
|
-
step: (msg: string) => void;
|
|
45
|
-
};
|
|
46
|
-
isCancel: typeof p.isCancel;
|
|
47
|
-
cancel: (msg?: string) => void;
|
|
48
|
-
note: (message: string, title?: string) => void;
|
|
49
|
-
}
|
|
50
|
-
/**
|
|
51
|
-
* Prompt utilities
|
|
52
|
-
*/
|
|
53
|
-
export declare const prompts: Prompts;
|
|
54
|
-
/**
|
|
55
|
-
* Re-export for direct access
|
|
56
|
-
*/
|
|
57
|
-
export { p as clack };
|
|
58
|
-
//# sourceMappingURL=prompts.d.ts.map
|
package/dist/prompts.d.ts.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,CAAC,MAAM,gBAAgB,CAAC;AAIpC,KAAK,UAAU,GAAG,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;AAC3C,KAAK,aAAa,GAAG,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,CAAC;AAC/C,KAAK,YAAY,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC;AAC3C,KAAK,iBAAiB,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,CAAC;AAClD,KAAK,cAAc,GAAG,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;AAC/C,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC;AAEpD,4CAA4C;AAC5C,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,UAAU,CAAC;IACjG,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,aAAa,CAAC;IAClF,MAAM,EAAE,CAAC,CAAC,SAAS,MAAM,EACvB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,CAAC,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,KACvD,YAAY,CAAC,CAAC,CAAC,CAAC;IACrB,WAAW,EAAE,CAAC,CAAC,SAAS,MAAM,EAC5B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,CAAC,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,KACvD,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAC1B,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,cAAc,CAAC;IAC9C,KAAK,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC;IACtB,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,OAAO,EAAE,MAAM,eAAe,CAAC;IAC/B,GAAG,EAAE;QACH,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAC5B,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAC/B,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAC5B,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAC7B,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAC/B,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;KAC7B,CAAC;IACF,QAAQ,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC;IAC5B,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CACjD;AAgHD;;GAEG;AACH,eAAO,MAAM,OAAO,EAAE,OAcrB,CAAC;AAEF;;GAEG;AACH,OAAO,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC"}
|