@procedures/cli-kit 0.0.0-bootstrap.0 → 0.35.1

package/dist/cli.d.ts

@@ -0,0 +1,117 @@
+/**
+ * A command line for a procedure registry.
+ *
+ * `createProcedureCli()` makes a program from the procedures: the flags come from the input
+ * schemas, and the help comes from the metadata. A missing argument is a question in a
+ * terminal. A value `@<file>` is the text of the file. A format hook of a procedure writes its
+ * human output.
+ */
+import { type Method } from "@procedures/client";
+import { type GlobalFlag, type Globals } from "./args.js";
+import { type Asker, type Terminal } from "./ask.js";
+import { type CommandLike } from "./fields.js";
+import { type OutputFormat, type Print } from "./format.js";
+/** The global flags of each program of `createProcedureCli()`. The option `globals` adds more. */
+export declare const STANDARD_GLOBAL_FLAGS: readonly GlobalFlag[];
+/** The commands of a program: a list of procedures or descriptions, or a registry. */
+export type CommandSource = readonly CommandLike[] | {
+    getAll(): readonly CommandLike[];
+};
+/** The options of a call of a `CliClient`. */
+export interface CliCallOptions {
+    /** The signal that aborts the call. */
+    signal?: AbortSignal | undefined;
+}
+/**
+ * The client that runs the commands, for example a `Client` of `@procedures/client` over HTTP.
+ * The command line uses `stream()` when the client has it, and else `call()`.
+ */
+export interface CliClient {
+    /** This function gives each item of the result of a procedure. */
+    stream?(method: Method, payload: unknown, options?: CliCallOptions): AsyncIterable<unknown>;
+    /** This function gives the result of a procedure. */
+    call?(method: Method, payload: unknown, options?: CliCallOptions): Promise<unknown>;
+}
+/** The data that a format hook gets. */
+export interface FormatContext {
+    /** The path of the command. */
+    path: readonly string[];
+    /** The input of the command. */
+    input: unknown;
+    /** The output format: `text` or `streaming`. */
+    format: OutputFormat;
+    /** The print functions of the program. */
+    print: Print;
+}
+/**
+ * A format hook writes the human output of one procedure. It gives a text or lines, and the
+ * program prints them. Or it prints with `context.print` and gives nothing. The program uses a
+ * hook only for the formats `text` and `streaming`. `--json` and `--format table` do not use it.
+ */
+export type FormatHook = (result: unknown, context: FormatContext) => string | readonly string[] | undefined | void;
+/** The options of `createProcedureCli()`. */
+export interface ProcedureCliOptions {
+    /** The name of the program, as a person types it. */
+    name: string;
+    /** The version that `--version` shows. Without it, `--version` shows the help. */
+    version?: string | undefined;
+    /** The text after the name in the first line of the help. */
+    description?: string | undefined;
+    /**
+     * The commands: procedures, descriptions of procedures, or a registry. A function gives them
+     * when the program starts, for example from a lazy import.
+     */
+    procedures: CommandSource | (() => CommandSource | Promise<CommandSource>);
+    /**
+     * The client that runs the commands. A function makes the client from the global flags, for
+     * example from `--port`. Without a client, the commands run in this process on the procedures.
+     */
+    client?: CliClient | ((globals: Globals) => CliClient | Promise<CliClient>) | undefined;
+    /** More global flags. A flag with the long name of a standard flag replaces it. */
+    globals?: readonly GlobalFlag[] | undefined;
+    /** The format hooks, by the path of the procedure with dots, for example `"job.status"`. */
+    format?: Readonly<Record<string, FormatHook>> | undefined;
+    /** The print functions. The default writes plain text to the console. */
+    print?: Print | undefined;
+    /** The lines of the help after the list of the commands. */
+    footer?: readonly string[] | undefined;
+    /** The terminal state that decides if the program asks. Tests give a fake. */
+    terminal?: Terminal | undefined;
+    /** The function that asks one question. Tests give a fake. */
+    ask?: Asker | undefined;
+    /**
+     * The function that reads a file for a value `@<file>`. The default reads the file as UTF-8.
+     * `false` turns `@<file>` off: a value that starts with `@` stays text.
+     */
+    readFile?: ((path: string) => string) | false | undefined;
+}
+/** The options of one run. */
+export interface ProcedureCliRunOptions {
+    /** The signal that aborts the call of the command. */
+    signal?: AbortSignal | undefined;
+}
+/** A program of `createProcedureCli()`. */
+export interface ProcedureCli {
+    /** The name of the program. */
+    readonly name: string;
+    /** The global flags of the program. */
+    readonly globals: readonly GlobalFlag[];
+    /**
+     * This function starts one command line (without the program name) and gives the exit code.
+     * The exit code is 1 for an unknown command, an invalid input, an error or a failed result.
+     * Else the exit code is 0.
+     */
+    run(argv: readonly string[], options?: ProcedureCliRunOptions): Promise<number>;
+}
+/**
+ * This function makes a command line for a procedure registry. The program gives help, `--json`,
+ * questions for missing arguments, `@<file>` input and short flags from `meta.shorts`.
+ *
+ * @example
+ * ```ts
+ * const cli = createProcedureCli({ name: "tool", version: "1.0.0", procedures: registry });
+ * process.exitCode = await cli.run(process.argv.slice(2));
+ * ```
+ */
+export declare function createProcedureCli(options: ProcedureCliOptions): ProcedureCli;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/cli.js

@@ -0,0 +1,253 @@
+/**
+ * A command line for a procedure registry.
+ *
+ * `createProcedureCli()` makes a program from the procedures: the flags come from the input
+ * schemas, and the help comes from the metadata. A missing argument is a question in a
+ * terminal. A value `@<file>` is the text of the file. A format hook of a procedure writes its
+ * human output.
+ */
+import { readFileSync } from "node:fs";
+import { Client, LocalTransport, ProcedureRegistry, pathToMethod, } from "@procedures/client";
+import { findChildren, parseCommandLine } from "./args.js";
+import { askMissing, canAsk, missingFields, processTerminal, terminalAsker } from "./ask.js";
+import { failureOf } from "./failure.js";
+import { fieldsOf, resultFieldsOf } from "./fields.js";
+import { formatOutput, plainPrint } from "./format.js";
+import { generateHelp, groupHelp, rootHelp, validationMessage } from "./help.js";
+/** The global flags of each program of `createProcedureCli()`. The option `globals` adds more. */
+export const STANDARD_GLOBAL_FLAGS = [
+    { long: "help", short: "h", takesValue: false, description: "Show the help" },
+    { long: "version", short: "v", takesValue: false, hidden: true, description: "Show the version" },
+    { long: "format", short: "f", takesValue: true, description: "The output format: text, json, table or streaming" },
+    { long: "json", takesValue: false, description: "Write the result as JSON (the same as --format json)" },
+    { long: "data", takesValue: true, description: "The input as a JSON object, or @<file> for a file with the JSON object" },
+    { long: "no-input", takesValue: false, description: "Never ask for a missing argument (also when CI is set)" },
+];
+const OUTPUT_FORMATS = ["text", "json", "table", "streaming"];
+/** This function gives the global flags: the standard flags, then the flags of the options. */
+function mergeGlobals(extra) {
+    const names = new Set(extra.map((flag) => flag.long));
+    return [...STANDARD_GLOBAL_FLAGS.filter((flag) => !names.has(flag.long)), ...extra];
+}
+/** This function gives the list of a command source. */
+function commandsOf(source) {
+    return "getAll" in source ? source.getAll() : source;
+}
+/** This function gives the text of an error. */
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** This function makes a client in this process over the procedures of a source. */
+function localClient(source) {
+    let registry;
+    if (source instanceof ProcedureRegistry) {
+        registry = source;
+    }
+    else {
+        registry = new ProcedureRegistry();
+        for (const procedure of commandsOf(source))
+            registry.register(procedure);
+    }
+    const client = new Client({ transport: new LocalTransport({ registry }) }).useRegistry(registry);
+    return {
+        stream: (method, payload, options) => client.stream(method, payload, options?.signal ? { signal: options.signal } : {}),
+    };
+}
+/** This function gives each item of the result of a call. */
+async function* itemsOf(client, method, payload, options) {
+    if (client.stream) {
+        yield* client.stream(method, payload, options);
+        return;
+    }
+    if (client.call) {
+        yield await client.call(method, payload, options);
+        return;
+    }
+    throw new Error("The client has no stream() and no call()");
+}
+/**
+ * This function makes a command line for a procedure registry. The program gives help, `--json`,
+ * questions for missing arguments, `@<file>` input and short flags from `meta.shorts`.
+ *
+ * @example
+ * ```ts
+ * const cli = createProcedureCli({ name: "tool", version: "1.0.0", procedures: registry });
+ * process.exitCode = await cli.run(process.argv.slice(2));
+ * ```
+ */
+export function createProcedureCli(options) {
+    const { name } = options;
+    const globalFlags = mergeGlobals(options.globals ?? []);
+    const readFile = options.readFile === false ? undefined : (options.readFile ?? ((path) => readFileSync(path, "utf8")));
+    const run = async (argv, runOptions = {}) => {
+        const print = options.print ?? plainPrint();
+        let code = 0;
+        const fail = (message, hint) => {
+            print.error(message);
+            if (hint)
+                print.info(hint);
+            code = 1;
+        };
+        try {
+            const source = typeof options.procedures === "function" ? await options.procedures() : options.procedures;
+            const commands = commandsOf(source);
+            const parsed = parseCommandLine(argv, commands, { name, globals: globalFlags, readFile });
+            const { path, procedure, globals } = parsed;
+            const command = `${name} ${path.join(" ")}`;
+            // An unknown command is the first problem to report
+            if (path.length > 0 && !procedure) {
+                const isGroup = findChildren(commands, path).length > 0;
+                if (!isGroup || parsed.extraArguments.length > 0) {
+                    const words = [...path, ...parsed.extraArguments.slice(0, 1)];
+                    fail(`Unknown command: ${name} ${words.join(" ")}`, `Run '${name} --help' for available commands.`);
+                    return code;
+                }
+            }
+            if (parsed.errors.length > 0) {
+                for (const error of parsed.errors)
+                    print.error(error);
+                print.info(`Run '${path.length > 0 ? `${command} --help` : `${name} --help`}' for the options.`);
+                return 1;
+            }
+            if (globals["version"] === true && options.version !== undefined) {
+                print.info(`${name} v${options.version}`);
+                return 0;
+            }
+            const formatOverride = globals["json"] === true ? "json" : globals["format"] === undefined ? undefined : String(globals["format"]);
+            if (formatOverride !== undefined && !OUTPUT_FORMATS.includes(formatOverride)) {
+                fail(`Invalid format: ${formatOverride}. Valid formats: ${OUTPUT_FORMATS.join(", ")}`);
+                return code;
+            }
+            // The help of the program, of a group or of a command
+            if (path.length === 0) {
+                const title = `${name}${options.version !== undefined ? ` v${options.version}` : ""}${options.description ? ` - ${options.description}` : ""}`;
+                for (const line of rootHelp(commands, { name, title, footer: options.footer }))
+                    print.info(line);
+                return 0;
+            }
+            if (globals["help"] === true || !procedure) {
+                if (procedure) {
+                    const meta = (procedure.metadata ?? {});
+                    print.info(generateHelp(path, meta, fieldsOf(procedure), resultFieldsOf(procedure), { name, globals: globalFlags }));
+                }
+                else {
+                    for (const line of groupHelp(name, commands, path) ?? [])
+                        print.info(line);
+                }
+                return 0;
+            }
+            const meta = (procedure.metadata ?? {});
+            const outputFormat = (formatOverride ?? meta.output ?? "text");
+            // --data: the input as one JSON object. The flags and the arguments go over its fields.
+            let input = parsed.input;
+            if (globals["data"] !== undefined) {
+                let text = String(globals["data"]);
+                if (text.startsWith("@") && !text.startsWith("@@") && text.length > 1) {
+                    if (!readFile) {
+                        fail(`--data ${text}: this program reads no files`);
+                        return code;
+                    }
+                    text = readFile(text.slice(1));
+                }
+                else if (text.startsWith("@@")) {
+                    text = text.slice(1);
+                }
+                let data;
+                try {
+                    data = JSON.parse(text);
+                }
+                catch (error) {
+                    fail(`--data needs a JSON object: ${messageOf(error)}`);
+                    return code;
+                }
+                if (!data || typeof data !== "object" || Array.isArray(data)) {
+                    fail("--data needs a JSON object");
+                    return code;
+                }
+                input = { ...data, ...input };
+            }
+            // A required argument that is missing: in a terminal, the program asks for it
+            const missing = missingFields(fieldsOf(procedure), input);
+            if (missing.length > 0 && canAsk(globals["no-input"] === true, meta, options.terminal ?? processTerminal())) {
+                const asked = await askMissing(missing, input, options.ask ?? terminalAsker);
+                if (!asked.ok) {
+                    fail(asked.cancelled ? "Cancelled" : `Invalid input for ${command}:\n  ${asked.error}`);
+                    return code;
+                }
+                input = asked.input;
+            }
+            // A procedure with a schema validates the input here. A description without a schema
+            // leaves the validation to the client.
+            let validated = input;
+            const schema = procedure.input;
+            if (typeof schema?.parse === "function") {
+                try {
+                    validated = schema.parse(input);
+                }
+                catch (error) {
+                    fail(`Invalid input for ${command}:\n  ${validationMessage(error)}`, `Run '${command} --help' for the options.`);
+                    return code;
+                }
+            }
+            else {
+                const stillMissing = missingFields(fieldsOf(procedure), input);
+                if (stillMissing.length > 0) {
+                    const names = stillMissing.map((field) => `${field.name}: Required`).join("\n  ");
+                    fail(`Invalid input for ${command}:\n  ${names}`, `Run '${command} --help' for the options.`);
+                    return code;
+                }
+            }
+            const client = options.client === undefined
+                ? localClient(source)
+                : typeof options.client === "function"
+                    ? await options.client(globals)
+                    : options.client;
+            // Each item prints when it arrives. A failed item makes the command fail.
+            const hook = outputFormat === "text" || outputFormat === "streaming" ? options.format?.[path.join(".")] : undefined;
+            let failure;
+            const printItem = (item) => {
+                const text = hook ? hook(item, { path, input: validated, format: outputFormat, print }) : undefined;
+                if (typeof text === "string") {
+                    print.info(text);
+                }
+                else if (Array.isArray(text)) {
+                    for (const line of text)
+                        print.info(line);
+                }
+                else if (!hook) {
+                    formatOutput(print, item, outputFormat);
+                }
+                failure ??= failureOf(item);
+            };
+            const spinner = outputFormat === "streaming" ? print.spin(`Running ${path.join(" ")}...`) : undefined;
+            try {
+                let items = 0;
+                for await (const item of itemsOf(client, pathToMethod(path), validated, { signal: runOptions.signal })) {
+                    if (spinner && items === 0)
+                        spinner.stop();
+                    items++;
+                    printItem(item);
+                }
+                if (spinner) {
+                    if (failure === undefined)
+                        spinner.succeed(`${path.join(" ")} complete`);
+                    else
+                        spinner.fail(`${path.join(" ")} failed`);
+                }
+            }
+            catch (error) {
+                spinner?.stop();
+                throw error;
+            }
+            if (failure !== undefined) {
+                fail(`${command} failed: ${failure}`);
+            }
+        }
+        catch (error) {
+            fail(`Error: ${messageOf(error)}`);
+        }
+        return code;
+    };
+    return { name, globals: globalFlags, run };
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/failure.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Procedure-level failure
+ *
+ * A procedure reports a failure in one of three ways, and the command line exits with code 1 for each:
+ *
+ * 1. It throws an error. This is the usual way.
+ * 2. It returns an object with `success: false`. Use this when the result has more to show,
+ *    for example the list of problems of `lib audit`.
+ * 3. It returns an object with a numeric `exitCode` that is not 0. Use this for a procedure that
+ *    runs an external command (`vitest run`, `shell run`), so the caller sees the command's result.
+ *
+ * For a streaming procedure, each item is examined: one failed item makes the command fail.
+ */
+/** A short description of the failure that a result reports, or undefined when it reports none */
+export declare function failureOf(result: unknown): string | undefined;
+//# sourceMappingURL=failure.d.ts.map

package/dist/failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure.d.ts","sourceRoot":"","sources":["../src/failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,kGAAkG;AAClG,wBAAgB,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAa7D"}

package/dist/failure.js

@@ -0,0 +1,47 @@
+/**
+ * Procedure-level failure
+ *
+ * A procedure reports a failure in one of three ways, and the command line exits with code 1 for each:
+ *
+ * 1. It throws an error. This is the usual way.
+ * 2. It returns an object with `success: false`. Use this when the result has more to show,
+ *    for example the list of problems of `lib audit`.
+ * 3. It returns an object with a numeric `exitCode` that is not 0. Use this for a procedure that
+ *    runs an external command (`vitest run`, `shell run`), so the caller sees the command's result.
+ *
+ * For a streaming procedure, each item is examined: one failed item makes the command fail.
+ */
+/** A short description of the failure that a result reports, or undefined when it reports none */
+export function failureOf(result) {
+    if (!result || typeof result !== "object" || Array.isArray(result)) {
+        return undefined;
+    }
+    const record = result;
+    const exitCode = record["exitCode"];
+    if (typeof exitCode === "number" && exitCode !== 0) {
+        return `exit code ${exitCode}`;
+    }
+    if (record["success"] === false) {
+        return firstText(record["error"]) ?? firstText(record["errors"]) ?? firstText(record["message"]) ?? "success: false";
+    }
+    return undefined;
+}
+/** The first text of a value: a string, the message of an error object, or the first of a list */
+function firstText(value) {
+    if (typeof value === "string" && value.length > 0) {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const text = firstText(item);
+            if (text)
+                return text;
+        }
+        return undefined;
+    }
+    if (value && typeof value === "object" && typeof value.message === "string") {
+        return value.message;
+    }
+    return undefined;
+}
+//# sourceMappingURL=failure.js.map

package/dist/failure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure.js","sourceRoot":"","sources":["../src/failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,kGAAkG;AAClG,MAAM,UAAU,SAAS,CAAC,MAAe;IACvC,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnE,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,MAAM,GAAG,MAAiC,CAAC;IACjD,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IACpC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;QACnD,OAAO,aAAa,QAAQ,EAAE,CAAC;IACjC,CAAC;IACD,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,KAAK,EAAE,CAAC;QAChC,OAAO,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,gBAAgB,CAAC;IACvH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,kGAAkG;AAClG,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;YAC7B,IAAI,IAAI;gBAAE,OAAO,IAAI,CAAC;QACxB,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAQ,KAA+B,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACvG,OAAQ,KAA6B,CAAC,OAAO,CAAC;IAChD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/fields.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The fields of a procedure input, as a command line sees them.
+ *
+ * This module reads the field types of an input schema from its JSON Schema, converts the text of
+ * the command line to those types, and merges repeated values. The schema validates the result.
+ */
+/**
+ * CLI metadata that can be attached to procedures via .meta()
+ */
+export interface CLIMeta {
+    /** Description for help text */
+    description?: string;
+    /** Field names that are positional args (in order). An array field that is last takes the rest. */
+    args?: string[];
+    /** Short flag mappings: { fieldName: "f" } */
+    shorts?: Record<string, string>;
+    /** Output format hint */
+    output?: "text" | "json" | "table" | "streaming";
+    /** Whether to prompt for missing required fields */
+    interactive?: boolean;
+}
+/**
+ * The kinds of field the CLI can convert to. "any" is a field with no usable type: its value is
+ * JSON when it parses as JSON, and text otherwise.
+ */
+export type FieldKind = "string" | "number" | "bigint" | "boolean" | "enum" | "literal" | "date" | "array" | "record" | "object" | "union" | "any";
+/**
+ * The type of a schema field, as the CLI sees it
+ */
+export interface FieldType {
+    kind: FieldKind;
+    /** The item type of an array */
+    item?: FieldType;
+    /** The value type of a record */
+    value?: FieldType;
+    /** The member types of a union */
+    options?: FieldType[];
+    /** The values of an enum */
+    values?: readonly string[];
+    /** The value of a literal */
+    literal?: unknown;
+}
+/**
+ * Extracted schema field info for help generation
+ */
+export interface SchemaFieldInfo {
+    name: string;
+    /** The display name of the type, for the help text */
+    type: string;
+    /** The type the CLI converts values to */
+    fieldType: FieldType;
+    required: boolean;
+    description: string | undefined;
+    defaultValue: unknown;
+    enumValues: readonly string[] | undefined;
+}
+/**
+ * The CLI type of a schema: a procedure schema (a Standard Schema such as zod 4) or its JSON
+ * Schema. The type comes from the JSON Schema, so every schema library works. (Before, the
+ * parser read the private fields of zod 3.)
+ */
+export declare function fieldTypeOf(schema: unknown): FieldType;
+/**
+ * The display name of a type, for the help text
+ */
+export declare function typeName(type: FieldType): string;
+/**
+ * Extract field information from a schema: a procedure schema or its JSON Schema. A schema that
+ * is not an object (or that has no JSON Schema) gives no fields: the CLI then passes its flags
+ * through.
+ */
+export declare function extractSchemaFields(schema: unknown): SchemaFieldInfo[];
+/** The result of a conversion: the value, or a message for the user */
+export type Converted = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Convert the CLI text of one value to a field type
+ */
+export declare function convertValue(text: string, type: FieldType, label: string): Converted;
+/**
+ * Add a converted value to a field that already has one. Arrays collect and records merge,
+ * so a repeated flag adds to the field. Other fields take the last value.
+ */
+export declare function mergeValue(previous: unknown, next: unknown, type: FieldType): unknown;
+/**
+ * Convert camelCase to kebab-case
+ */
+export declare function toKebab(str: string): string;
+/**
+ * Convert kebab-case to camelCase
+ */
+export declare function toCamel(str: string): string;
+/**
+ * A command as the command line sees it: a procedure of a registry (with its input schema), or a
+ * description of a procedure (with the fields of its input), for example the manifest of `mark`.
+ */
+export interface CommandLike {
+    path: readonly string[];
+    metadata?: unknown;
+    /** The input schema of a procedure of the registry */
+    input?: unknown;
+    /** The output schema of a procedure of the registry */
+    output?: unknown;
+    /** The fields of the input of a description */
+    fields?: readonly SchemaFieldInfo[];
+    /** The fields of the result of a description */
+    resultFields?: readonly SchemaFieldInfo[];
+}
+/** This function gives the fields of the input of a command: from its description, or read from its schema. */
+export declare function fieldsOf(command: CommandLike): SchemaFieldInfo[];
+/**
+ * The fields of the result of a procedure, from its output schema: only for a result that is an
+ * object (a union, a stream item or a pass-through schema gives none).
+ */
+export declare function resultFieldsOfSchema(output: unknown): SchemaFieldInfo[];
+/** This function gives the fields of the result of a command: from its description, or read from its output schema. */
+export declare function resultFieldsOf(command: CommandLike): SchemaFieldInfo[];
+/** A field that only the metadata names (the schema has no readable shape) */
+export declare function fieldWithoutSchema(name: string): SchemaFieldInfo;
+//# sourceMappingURL=fields.d.ts.map

package/dist/fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../src/fields.ts"],"names":[],"mappings":"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"}