@procedures/mark 0.0.0-stage → 0.2.0

package/dist/parse.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Schema-based CLI Argument Parser
+ *
+ * Reads the field types of a procedure's input schema, converts CLI text to those types, and
+ * makes the help text. Validation is delegated to the procedure's schema.
+ */
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * Gluegun parameters shape
+ */
+export interface Parameters {
+    first?: string;
+    second?: string;
+    third?: string;
+    array?: string[];
+    options?: Record<string, unknown>;
+    raw?: string[];
+    string?: string;
+}
+/**
+ * Convert camelCase to kebab-case
+ */
+export declare function toKebab(str: string): string;
+/**
+ * Convert kebab-case to camelCase
+ */
+export declare function toCamel(str: string): string;
+/**
+ * Parse CLI parameters into procedure input based on metadata. With the schema, each value is
+ * converted by the type of its field: a string field keeps its text. Without the schema, a value
+ * is JSON when it parses as JSON, and text otherwise.
+ */
+export declare function parseFromSchema(params: Parameters, meta: CLIMeta, schema?: unknown): Record<string, unknown>;
+/**
+ * A command as mark sees it: a procedure of the registry (with its input schema), or a command
+ * of the manifest (with the fields of its input). See manifest.ts.
+ */
+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 command of the manifest */
+    fields?: readonly SchemaFieldInfo[];
+    /** The fields of the result of a command of the manifest */
+    resultFields?: readonly SchemaFieldInfo[];
+}
+/** The fields of the input of a command: from the manifest, or read from the 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[];
+/** The fields of the result of a command: from the manifest, or read from the output schema */
+export declare function resultFieldsOf(command: CommandLike): SchemaFieldInfo[];
+/**
+ * Generate help text for a procedure based on its metadata and schema. `schema` is the input
+ * schema, or the fields of the input (a command of the manifest). `result` gives the fields of
+ * the result, which the help lists after the options.
+ */
+export declare function generateHelp(path: string[], meta: CLIMeta, schema?: unknown, result?: readonly SchemaFieldInfo[]): string;
+//# sourceMappingURL=parse.d.ts.map

package/dist/parse.d.ts.map

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

package/dist/parse.js

@@ -0,0 +1,509 @@
+/**
+ * Schema-based CLI Argument Parser
+ *
+ * Reads the field types of a procedure's input schema, converts CLI text to those types, and
+ * makes the help text. Validation is delegated to the procedure's schema.
+ */
+import { CLI_GLOBAL_FLAGS } from "@procedures/lib/cli-flags";
+import { jsonSchemaOf } from "@procedures/client";
+/** True for the JSON Schema of `null` (a nullable field is `anyOf: [T, null]`). */
+function isNull(node) {
+    return node.type === "null" || (node.const === null && node.type === undefined);
+}
+/** The members of a union, without `null` (a nullable value is the type itself on the CLI). */
+function unionMembers(node) {
+    const members = node.anyOf ?? node.oneOf;
+    return members?.filter((member) => !isNull(member));
+}
+/**
+ * The CLI type of a JSON Schema node.
+ */
+function fieldTypeOfJson(node) {
+    if (!node || typeof node !== "object") {
+        return { kind: "any" };
+    }
+    const members = unionMembers(node);
+    if (members) {
+        if (members.length === 1)
+            return fieldTypeOfJson(members[0]);
+        // A union of string constants is an enum on the CLI
+        if (members.length > 1 && members.every((member) => typeof member.const === "string")) {
+            return { kind: "enum", values: members.map((member) => member.const) };
+        }
+        return { kind: "union", options: members.map((member) => fieldTypeOfJson(member)) };
+    }
+    if (node.allOf?.length === 1) {
+        return fieldTypeOfJson(node.allOf[0]);
+    }
+    if (Array.isArray(node.enum)) {
+        return node.enum.every((value) => typeof value === "string")
+            ? { kind: "enum", values: node.enum }
+            : { kind: "any" };
+    }
+    if ("const" in node && node.const !== undefined) {
+        return { kind: "literal", literal: node.const };
+    }
+    const types = Array.isArray(node.type) ? node.type.filter((type) => type !== "null") : node.type ? [node.type] : [];
+    if (types.length > 1) {
+        return { kind: "union", options: types.map((type) => fieldTypeOfJson({ ...node, type })) };
+    }
+    switch (types[0]) {
+        case "string":
+            return node.format === "date-time" || node.format === "date" ? { kind: "date" } : { kind: "string" };
+        case "number":
+        case "integer":
+            return { kind: "number" };
+        case "boolean":
+            return { kind: "boolean" };
+        case "array":
+            return { kind: "array", item: fieldTypeOfJson(Array.isArray(node.items) ? undefined : node.items) };
+        case "object": {
+            const extra = node.additionalProperties;
+            const hasFields = node.properties && Object.keys(node.properties).length > 0;
+            if (!hasFields && extra && typeof extra === "object") {
+                return { kind: "record", value: fieldTypeOfJson(extra) };
+            }
+            return { kind: "object" };
+        }
+        default:
+            return { kind: "any" };
+    }
+}
+/**
+ * The JSON Schema of a procedure schema (or a JSON Schema itself, as the manifest stores it).
+ */
+function asJsonSchema(schema) {
+    if (!schema || typeof schema !== "object") {
+        return undefined;
+    }
+    // A JSON Schema already (from the manifest): it has no validator
+    const props = schema;
+    if (!("~standard" in props) && typeof props["safeParse"] !== "function" && typeof props["parse"] !== "function") {
+        return schema;
+    }
+    return jsonSchemaOf(schema);
+}
+/**
+ * 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 function fieldTypeOf(schema) {
+    return fieldTypeOfJson(asJsonSchema(schema));
+}
+/**
+ * The display name of a type, for the help text
+ */
+function typeName(type) {
+    switch (type.kind) {
+        case "array":
+            return `${typeName(type.item ?? { kind: "any" })}[]`;
+        case "record":
+            return "key=value";
+        case "object":
+        case "any":
+            return "json";
+        case "union":
+            return (type.options ?? []).map(typeName).join("|");
+        case "literal":
+            return JSON.stringify(type.literal);
+        default:
+            return type.kind;
+    }
+}
+/**
+ * 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 function extractSchemaFields(schema) {
+    const json = asJsonSchema(schema);
+    const object = json && !json.properties ? unionMembers(json)?.find((member) => member.properties) : json;
+    if (!object?.properties) {
+        return [];
+    }
+    const required = new Set(object.required ?? []);
+    const fields = [];
+    for (const [name, field] of Object.entries(object.properties)) {
+        if (!field || typeof field !== "object") {
+            continue;
+        }
+        const fieldType = fieldTypeOfJson(field);
+        const description = field.description ?? unionMembers(field)?.find((member) => member.description)?.description;
+        fields.push({
+            name,
+            type: fieldType.kind === "enum" ? "enum" : typeName(fieldType),
+            fieldType,
+            required: required.has(name) && field.default === undefined,
+            description,
+            defaultValue: field.default,
+            enumValues: fieldType.kind === "enum" ? fieldType.values : undefined,
+        });
+    }
+    return fields;
+}
+const NUMBER_TEXT = /^[-+]?(\d+\.?\d*|\.\d+)([eE][-+]?\d+)?$|^0[xX][0-9a-fA-F]+$/;
+const SAFE_INTEGER_LIMIT = BigInt(Number.MAX_SAFE_INTEGER);
+/**
+ * Text as a JSON value, when it is JSON. A whole number that a JavaScript number cannot hold
+ * exactly stays text. Anything that is not JSON stays text.
+ */
+function jsonOrText(text) {
+    const trimmed = text.trim();
+    if (/^-?\d+$/.test(trimmed)) {
+        const big = BigInt(trimmed);
+        if (big > SAFE_INTEGER_LIMIT || big < -SAFE_INTEGER_LIMIT) {
+            return text;
+        }
+    }
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return text;
+    }
+}
+/**
+ * Convert the CLI text of one value to a field type
+ */
+export function convertValue(text, type, label) {
+    switch (type.kind) {
+        case "string":
+        case "date":
+            return { ok: true, value: text };
+        case "enum":
+            return { ok: true, value: text };
+        case "number": {
+            if (!NUMBER_TEXT.test(text.trim())) {
+                return { ok: false, error: `${label} needs a number, not "${text}"` };
+            }
+            return { ok: true, value: Number(text) };
+        }
+        case "bigint":
+            try {
+                return { ok: true, value: BigInt(text) };
+            }
+            catch {
+                return { ok: false, error: `${label} needs a whole number, not "${text}"` };
+            }
+        case "boolean":
+            if (text === "true")
+                return { ok: true, value: true };
+            if (text === "false")
+                return { ok: true, value: false };
+            return { ok: false, error: `${label} needs true or false, not "${text}"` };
+        case "literal": {
+            const literal = type.literal;
+            if (typeof literal === "number")
+                return convertValue(text, { kind: "number" }, label);
+            if (typeof literal === "boolean")
+                return convertValue(text, { kind: "boolean" }, label);
+            return { ok: true, value: text };
+        }
+        case "array": {
+            const item = type.item ?? { kind: "any" };
+            if (text.trimStart().startsWith("[")) {
+                const parsed = jsonOrText(text);
+                if (Array.isArray(parsed)) {
+                    return { ok: true, value: parsed };
+                }
+            }
+            const converted = convertValue(text, item, label);
+            return converted.ok ? { ok: true, value: [converted.value] } : converted;
+        }
+        case "record": {
+            if (text.trimStart().startsWith("{")) {
+                const parsed = jsonOrText(text);
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                    return { ok: true, value: parsed };
+                }
+                return { ok: false, error: `${label} needs key=value or a JSON object` };
+            }
+            const eq = text.indexOf("=");
+            if (eq <= 0) {
+                return { ok: false, error: `${label} needs key=value, not "${text}"` };
+            }
+            const converted = convertValue(text.slice(eq + 1), type.value ?? { kind: "any" }, label);
+            return converted.ok ? { ok: true, value: { [text.slice(0, eq)]: converted.value } } : converted;
+        }
+        case "object": {
+            const parsed = jsonOrText(text);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                return { ok: true, value: parsed };
+            }
+            return { ok: false, error: `${label} needs a JSON object, not "${text}"` };
+        }
+        case "union": {
+            const options = type.options ?? [];
+            // Zod tries the members in order: a member that takes text takes the text as it is
+            for (const option of options) {
+                if (option.kind === "string" || option.kind === "date")
+                    return { ok: true, value: text };
+                if (option.kind === "enum" && option.values?.includes(text))
+                    return { ok: true, value: text };
+                if (option.kind === "literal" && String(option.literal) === text) {
+                    return { ok: true, value: option.literal };
+                }
+            }
+            for (const option of options) {
+                if (option.kind === "enum" || option.kind === "literal")
+                    continue;
+                const converted = convertValue(text, option, label);
+                if (converted.ok)
+                    return converted;
+            }
+            return { ok: true, value: jsonOrText(text) };
+        }
+        case "any":
+        default:
+            return { ok: true, value: jsonOrText(text) };
+    }
+}
+/**
+ * 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 function mergeValue(previous, next, type) {
+    if (previous === undefined) {
+        return next;
+    }
+    if (type.kind === "array" && Array.isArray(previous) && Array.isArray(next)) {
+        return [...previous, ...next];
+    }
+    if (type.kind === "record" &&
+        previous && typeof previous === "object" && !Array.isArray(previous) &&
+        next && typeof next === "object" && !Array.isArray(next)) {
+        return { ...previous, ...next };
+    }
+    return next;
+}
+/**
+ * Convert camelCase to kebab-case
+ */
+export function toKebab(str) {
+    return str.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+/**
+ * Convert kebab-case to camelCase
+ */
+export function toCamel(str) {
+    return str.replace(/-([a-zA-Z0-9])/g, (_, c) => c.toUpperCase());
+}
+/**
+ * Convert one parameter by the type of its field. A value that is not text (true for a flag
+ * with no value) is not changed.
+ */
+function convertParameter(value, type, label) {
+    if (typeof value !== "string") {
+        return value;
+    }
+    const converted = convertValue(value, type, label);
+    if (!converted.ok) {
+        throw new Error(converted.error);
+    }
+    return converted.value;
+}
+/**
+ * Parse CLI parameters into procedure input based on metadata. With the schema, each value is
+ * converted by the type of its field: a string field keeps its text. Without the schema, a value
+ * is JSON when it parses as JSON, and text otherwise.
+ */
+export function parseFromSchema(params, meta, schema) {
+    const positionalArgs = meta.args ?? [];
+    const shorts = meta.shorts ?? {};
+    const fields = new Map(extractSchemaFields(schema).map((field) => [field.name, field.fieldType]));
+    const typeOfField = (field) => fields.get(field) ?? { kind: "any" };
+    const input = {};
+    // 1. Parse positional args
+    const positionalValues = params.array ?? [];
+    positionalArgs.forEach((field, i) => {
+        if (positionalValues[i] !== undefined) {
+            input[field] = convertParameter(positionalValues[i], typeOfField(field), field);
+        }
+    });
+    // 2. Parse options from CLI flags
+    const options = params.options ?? {};
+    // Build reverse lookup for short flags
+    const shortToField = {};
+    for (const [field, short] of Object.entries(shorts)) {
+        shortToField[short] = field;
+    }
+    for (const [key, value] of Object.entries(options)) {
+        // Skip if it's a positional arg already set
+        if (positionalArgs.includes(key) && input[key] !== undefined) {
+            continue;
+        }
+        const field = shortToField[key] ?? (key.includes("-") ? toCamel(key) : key);
+        input[field] = convertParameter(value, typeOfField(field), `--${toKebab(field)}`);
+    }
+    return input;
+}
+// =============================================================================
+// Help
+// =============================================================================
+/**
+ * How to give a field on the command line, for the help text
+ */
+function valueHint(field) {
+    const type = field.fieldType;
+    switch (type.kind) {
+        case "boolean":
+            return "";
+        case "array":
+            return ` <${typeName(type.item ?? { kind: "any" })}>... (repeat the flag, or give a JSON array)`;
+        case "record":
+            return " <key=value>... (repeat the flag, or give a JSON object)";
+        case "object":
+        case "any":
+            return " <json>";
+        case "enum":
+            return ` <${(field.enumValues ?? []).join("|")}>`;
+        default:
+            return ` <${typeName(type)}>`;
+    }
+}
+/** The fields of the input of a command: from the manifest, or read from the schema */
+export function fieldsOf(command) {
+    return command.fields ? [...command.fields] : extractSchemaFields(command.input);
+}
+/**
+ * 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 function resultFieldsOfSchema(output) {
+    const json = output ? jsonSchemaOf(output, { io: "output" }) : undefined;
+    if (!json)
+        return [];
+    if (json.type === "object")
+        return extractSchemaFields(json);
+    // A number, a string, a boolean or an array: the help shows the one value (`mark client add`)
+    if (typeof json.type === "string" && ["number", "integer", "string", "boolean", "array"].includes(json.type)) {
+        const fieldType = fieldTypeOfJson(json);
+        return [
+            {
+                name: "value",
+                type: typeName(fieldType),
+                fieldType,
+                required: true,
+                description: json.description,
+                defaultValue: undefined,
+                enumValues: undefined,
+            },
+        ];
+    }
+    return [];
+}
+/** The fields of the result of a command: from the manifest, or read from the output schema */
+export function resultFieldsOf(command) {
+    return command.resultFields ? [...command.resultFields] : resultFieldsOfSchema(command.output);
+}
+/**
+ * Generate help text for a procedure based on its metadata and schema. `schema` is the input
+ * schema, or the fields of the input (a command of the manifest). `result` gives the fields of
+ * the result, which the help lists after the options.
+ */
+export function generateHelp(path, meta, schema, result = []) {
+    const positionalArgs = meta.args ?? [];
+    const shorts = meta.shorts ?? {};
+    const lines = [];
+    // Extract schema fields for enhanced help
+    const schemaFields = Array.isArray(schema)
+        ? schema
+        : schema
+            ? extractSchemaFields(schema)
+            : [];
+    const schemaFieldMap = new Map(schemaFields.map((f) => [f.name, f]));
+    // Command signature: the last positional array takes the rest of the arguments
+    const cmdName = `mark ${path.join(" ")}`;
+    const posStr = positionalArgs
+        .map((a, i) => {
+        const many = i === positionalArgs.length - 1 && schemaFieldMap.get(a)?.fieldType.kind === "array";
+        return many ? `<${a}...>` : `<${a}>`;
+    })
+        .join(" ");
+    lines.push(`Usage: ${cmdName}${posStr ? " " + posStr : ""} [options]`);
+    lines.push("");
+    if (meta.description) {
+        lines.push(meta.description);
+        lines.push("");
+    }
+    // Positional args with schema info
+    if (positionalArgs.length > 0) {
+        lines.push("Arguments:");
+        for (const arg of positionalArgs) {
+            const fieldInfo = schemaFieldMap.get(arg);
+            const typeStr = fieldInfo ? ` (${fieldInfo.type})` : "";
+            const reqStr = fieldInfo?.required ? " [required]" : "";
+            const descStr = fieldInfo?.description ? `  ${fieldInfo.description}` : "";
+            lines.push(`  ${arg}${typeStr}${reqStr}`);
+            if (descStr) {
+                lines.push(`    ${descStr}`);
+            }
+        }
+        lines.push("");
+    }
+    // Options: each schema field that is not positional, with its short flag if it has one
+    const optionLines = [];
+    const positionalSet = new Set(positionalArgs);
+    const listed = new Set();
+    const optionFields = [
+        ...Object.keys(shorts).map((name) => schemaFieldMap.get(name) ?? fieldWithoutSchema(name)),
+        ...schemaFields.filter((field) => !(field.name in shorts) && !positionalSet.has(field.name)),
+    ];
+    for (const field of optionFields) {
+        if (listed.has(field.name)) {
+            continue;
+        }
+        listed.add(field.name);
+        const short = shorts[field.name];
+        const kebab = toKebab(field.name);
+        const flag = short ? `  -${short}, --${kebab}` : `      --${kebab}`;
+        const negation = field.fieldType.kind === "boolean" ? ` (or --no-${kebab})` : "";
+        const reqStr = field.required ? " [required]" : "";
+        const defaultStr = field.defaultValue !== undefined ? ` (default: ${JSON.stringify(field.defaultValue)})` : "";
+        optionLines.push(`${flag}${valueHint(field)}${negation}${reqStr}${defaultStr}`);
+        if (field.description) {
+            optionLines.push(`        ${field.description}`);
+        }
+    }
+    if (optionLines.length > 0) {
+        lines.push("Options:");
+        lines.push(...optionLines);
+    }
+    // The fields of the result (roadmap 2.1: the output schemas describe them)
+    if (result.length > 0) {
+        lines.push("");
+        lines.push("Result:");
+        for (const field of result) {
+            const optional = field.required ? "" : ", optional";
+            lines.push(`  ${field.name} (${field.type}${optional})`);
+            if (field.description) {
+                lines.push(`        ${field.description}`);
+            }
+        }
+    }
+    // Standard options
+    lines.push("");
+    lines.push("Global Options (before the command, or after it when the command has no flag of that name):");
+    for (const flag of CLI_GLOBAL_FLAGS) {
+        if (flag.mode || flag.serverOption || flag.long === "version") {
+            continue;
+        }
+        const name = flag.short ? `-${flag.short}, --${flag.long}` : `    --${flag.long}`;
+        lines.push(`  ${name.padEnd(18)} ${flag.description}`);
+    }
+    return lines.join("\n");
+}
+/** A field that only the metadata names (the schema has no readable shape) */
+function fieldWithoutSchema(name) {
+    return {
+        name,
+        type: "json",
+        fieldType: { kind: "any" },
+        required: false,
+        description: undefined,
+        defaultValue: undefined,
+        enumValues: undefined,
+    };
+}
+//# sourceMappingURL=parse.js.map