@xyd-js/opencli 0.1.0-build.0

package/dist/index.d.cts

@@ -0,0 +1,522 @@
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+/**
+ * The OpenCLI description
+ */
+interface OpencliSpecJson {
+    /**
+     * The OpenCLI version number
+     */
+    opencli: string;
+    info: CliInfo;
+    conventions?: Conventions;
+    /**
+     * Root command arguments
+     */
+    arguments?: Argument[];
+    /**
+     * Root command options
+     */
+    options?: Option[];
+    /**
+     * Root command sub commands
+     */
+    commands?: Command[];
+    /**
+     * Root command exit codes
+     */
+    exitCodes?: ExitCode[];
+    /**
+     * Examples of how to use the CLI
+     */
+    examples?: string[];
+    /**
+     * Indicates whether or not the command requires interactive input
+     */
+    interactive?: boolean;
+    /**
+     * Custom metadata
+     */
+    metadata?: Metadata[];
+    "x-openapi"?: XOpenApiRoot;
+    [k: string]: unknown;
+}
+/**
+ * Information about the CLI
+ */
+interface CliInfo {
+    /**
+     * The application title
+     */
+    title: string;
+    /**
+     * A short summary of the application
+     */
+    summary?: string;
+    /**
+     * A description of the application
+     */
+    description?: string;
+    contact?: Contact;
+    license?: License;
+    /**
+     * The application version
+     */
+    version: string;
+    [k: string]: unknown;
+}
+/**
+ * The contact information
+ */
+interface Contact {
+    /**
+     * The identifying name of the contact person/organization
+     */
+    name?: string;
+    /**
+     * The URI for the contact information. This MUST be in the form of a URI.
+     */
+    url?: string;
+    /**
+     * The email address of the contact person/organization. This MUST be in the form of an email address.
+     */
+    email?: string;
+    [k: string]: unknown;
+}
+/**
+ * The application license
+ */
+interface License {
+    /**
+     * The license name
+     */
+    name?: string;
+    /**
+     * The SPDX license identifier
+     */
+    identifier?: string;
+    /**
+     * The URI for the license. This MUST be in the form of a URI
+     */
+    url?: string;
+    [k: string]: unknown;
+}
+/**
+ * The conventions used by the CLI
+ */
+interface Conventions {
+    /**
+     * Whether or not grouping of short options are allowed
+     */
+    groupOptions?: boolean;
+    /**
+     * The option argument separator
+     */
+    optionSeparator?: string;
+    [k: string]: unknown;
+}
+interface Argument {
+    /**
+     * The argument name
+     */
+    name: string;
+    /**
+     * Whether or not the argument is required
+     */
+    required?: boolean;
+    arity?: Arity;
+    /**
+     * A list of accepted values
+     */
+    acceptedValues?: string[];
+    /**
+     * The argument group
+     */
+    group?: string;
+    /**
+     * The argument description
+     */
+    description?: string;
+    /**
+     * Whether or not the argument is hidden
+     */
+    hidden?: boolean;
+    /**
+     * Custom metadata
+     */
+    metadata?: Metadata[];
+    [k: string]: unknown;
+}
+/**
+ * The argument arity. Arity defines the minimum and maximum number of argument values
+ */
+interface Arity {
+    /**
+     * The minimum number of values allowed
+     */
+    minimum?: number;
+    /**
+     * The maximum number of values allowed
+     */
+    maximum?: number;
+    [k: string]: unknown;
+}
+interface Metadata {
+    name: string;
+    value?: unknown;
+    [k: string]: unknown;
+}
+interface Option {
+    /**
+     * The option name
+     */
+    name: string;
+    /**
+     * Whether or not the option is required
+     */
+    required?: boolean;
+    /**
+     * The option's aliases
+     */
+    aliases?: string[];
+    /**
+     * The option's arguments
+     */
+    arguments?: Argument[];
+    /**
+     * The option group
+     */
+    group?: string;
+    /**
+     * The option description
+     */
+    description?: string;
+    /**
+     * Specifies whether the option is accessible from the immediate parent command and, recursively, from its subcommands
+     */
+    recursive?: boolean;
+    /**
+     * Whether or not the option is hidden
+     */
+    hidden?: boolean;
+    /**
+     * Custom metadata
+     */
+    metadata?: Metadata[];
+    [k: string]: unknown;
+}
+interface Command {
+    /**
+     * The command name
+     */
+    name: string;
+    /**
+     * The command aliases
+     */
+    aliases?: string[];
+    /**
+     * The command options
+     */
+    options?: Option[];
+    /**
+     * The command arguments
+     */
+    arguments?: Argument[];
+    /**
+     * The command's sub commands
+     */
+    commands?: Command[];
+    /**
+     * The command's exit codes
+     */
+    exitCodes?: ExitCode[];
+    /**
+     * The command description
+     */
+    description?: string;
+    /**
+     * Whether or not the command is hidden
+     */
+    hidden?: boolean;
+    /**
+     * Examples of how to use the command
+     */
+    examples?: string[];
+    /**
+     * Indicate whether or not the command requires interactive input
+     */
+    interactive?: boolean;
+    /**
+     * Custom metadata
+     */
+    metadata?: Metadata[];
+    "x-openapi"?: XOpenApiCommand;
+    [k: string]: unknown;
+}
+interface ExitCode {
+    /**
+     * The exit code
+     */
+    code: number;
+    /**
+     * The exit code description
+     */
+    description?: string;
+    [k: string]: unknown;
+}
+/**
+ * xyd extension: OpenAPI/HTTP binding for this command's operation (method, path, params, body). Consumed by the opencli2* code generators to build real API requests.
+ */
+interface XOpenApiCommand {
+    /**
+     * The source OpenAPI operationId, when present
+     */
+    operationId?: string;
+    /**
+     * HTTP method (lowercase)
+     */
+    method: string;
+    /**
+     * HTTP path template (e.g. /chat/completions/{completion_id})
+     */
+    path: string;
+    /**
+     * Override base URL for this operation, if any
+     */
+    server?: string;
+    /**
+     * Request body content type
+     */
+    contentType?: string;
+    /**
+     * Per-operation security requirements (overrides root)
+     */
+    security?: XOpenApiSecurity[];
+    /**
+     * How CLI arguments/options map to HTTP parameters
+     */
+    params?: XOpenApiParam[];
+    body?: XOpenApiBody;
+    [k: string]: unknown;
+}
+/**
+ * A single security scheme mapped from the OpenAPI securitySchemes.
+ */
+interface XOpenApiSecurity {
+    /**
+     * Normalized scheme a generator branches on: bearer | apiKey-header | apiKey-query | apiKey-cookie | basic | other
+     */
+    kind?: string;
+    /**
+     * The OpenAPI security scheme type (e.g. http, apiKey, oauth2)
+     */
+    type: string;
+    /**
+     * The HTTP auth scheme (e.g. bearer, basic) when type is http
+     */
+    scheme?: string;
+    /**
+     * Location for an apiKey scheme (header, query or cookie)
+     */
+    in?: string;
+    /**
+     * Header/query/cookie name for an apiKey scheme
+     */
+    name?: string;
+    /**
+     * The bearer token format hint (e.g. JWT)
+     */
+    bearerFormat?: string;
+    /**
+     * Environment variable a generated CLI reads the credential from (e.g. OPENAI_API_KEY)
+     */
+    envVar?: string;
+    [k: string]: unknown;
+}
+/**
+ * Maps one CLI argument/option onto an HTTP parameter.
+ */
+interface XOpenApiParam {
+    /**
+     * Parameter location (path, query, header or cookie)
+     */
+    in: string;
+    /**
+     * The wire name of the HTTP parameter
+     */
+    name: string;
+    /**
+     * Source CLI token: 'argument:<name>' or 'option:<name>'
+     */
+    from: string;
+    /**
+     * Whether the HTTP parameter is required
+     */
+    required?: boolean;
+    /**
+     * OpenAPI explode flag for array/object serialization
+     */
+    explode?: boolean;
+    /**
+     * OpenAPI serialization style
+     */
+    style?: string;
+    [k: string]: unknown;
+}
+/**
+ * How CLI options map to the request body
+ */
+interface XOpenApiBody {
+    /**
+     * How the body is assembled: 'flatten' (per-property flags), 'json' (single JSON flag) or 'multipart'
+     */
+    style: string;
+    /**
+     * Body content type
+     */
+    contentType?: string;
+    /**
+     * Source CLI token when the whole body comes from one option (style=json)
+     */
+    from?: string;
+    /**
+     * Per-property body field mappings (style=flatten/multipart)
+     */
+    properties?: XOpenApiBodyProp[];
+    [k: string]: unknown;
+}
+/**
+ * Maps one CLI option onto a request body field.
+ */
+interface XOpenApiBodyProp {
+    /**
+     * The wire name of the body field
+     */
+    name: string;
+    /**
+     * Source CLI token: 'option:<name>'
+     */
+    from: string;
+    /**
+     * Dot path of the field within the JSON body
+     */
+    jsonPath?: string;
+    /**
+     * How the CLI value is encoded into the field: 'string', 'number', 'integer', 'boolean', 'json' (parse as JSON), 'array' or 'file'
+     */
+    encoding?: string;
+    /**
+     * Whether the body field is required
+     */
+    required?: boolean;
+    [k: string]: unknown;
+}
+/**
+ * xyd extension: OpenAPI/HTTP binding for the CLI as a whole (servers + security). Emitted by @xyd-js/openapi2opencli and consumed by the opencli2* code generators to build real API requests.
+ */
+interface XOpenApiRoot {
+    /**
+     * Available API base URLs (from the OpenAPI servers list)
+     */
+    servers?: string[];
+    /**
+     * Default security requirements for the CLI
+     */
+    security?: XOpenApiSecurity[];
+    [k: string]: unknown;
+}
+
+interface LoadOpencliSpecOptions {
+    /**
+     * Base directory used to resolve a relative file `source`.
+     * Defaults to `process.cwd()`. (The remark plugin passes the markdown file's dirname.)
+     */
+    cwd?: string;
+}
+/**
+ * Load an OpenCLI spec from a file path or an HTTP(S) URL.
+ *
+ * Returns `null` (and logs) on any failure so callers can leave placeholders
+ * untouched rather than throwing.
+ */
+declare function loadOpencliSpec(source: string, opts?: LoadOpencliSpecOptions): Promise<OpencliSpecJson | null>;
+/**
+ * Find a command in the spec by path (e.g., "spice install").
+ * If the path is empty, returns a synthetic root command built from the spec root.
+ */
+declare function findCommand(spec: OpencliSpecJson, commandPath: string): Command | null;
+
+type IndentStyle = 'code' | 'list';
+/**
+ * Generate usage line for a command (like: "shadcn init [options] [components...]")
+ */
+declare function generateUsage(_spec: OpencliSpecJson, command: Command, commandPath: string): string;
+/**
+ * Generate description for a command
+ */
+declare function generateDescription(command: Command): string;
+/**
+ * Generate arguments documentation
+ * @param indentStyle - 'code' for tab-indented CLI style, 'list' for markdown list style
+ */
+declare function generateArguments(command: Command, indentStyle?: IndentStyle): string;
+/**
+ * Generate options documentation
+ * @param indentStyle - 'code' for tab-indented CLI style, 'list' for markdown list style
+ */
+declare function generateOptions(command: Command, indentStyle?: IndentStyle): string;
+/**
+ * TODO: OPTIONS DO ALMOST THE SAME
+ * Generate flags/options documentation
+ */
+declare function generateFlags(command: Command): string;
+/**
+ * Generate subcommands documentation
+ */
+declare function generateCommands(command: Command): string;
+
+interface OpencliRefProperty {
+    name: string;
+    type: string;
+    description: string;
+    meta?: {
+        name: string;
+        value: unknown;
+    }[];
+}
+interface OpencliRefDefinition {
+    title: string;
+    properties: OpencliRefProperty[];
+}
+interface OpencliReference {
+    title: string;
+    canonical: string;
+    description: string;
+    context: {
+        path: string;
+        fullPath: string;
+        group: string[];
+    };
+    examples: {
+        groups: never[];
+    };
+    definitions: OpencliRefDefinition[];
+}
+interface OpencliToReferencesOptions {
+    /**
+     * Restrict output to specific commands. Each region is a command path,
+     * space-joined from the CLI root (e.g. `"install"`, `"remote add"`).
+     */
+    regions?: string[];
+}
+/**
+ * Convert an OpenCLI document to uniform `Reference[]` — one Reference per
+ * command — so the docs engine can render CLI reference pages the same way it
+ * renders OpenAPI/GraphQL (`api.cli`). Mirrors `oapSchemaToReferences`.
+ */
+declare function opencliToReferences(spec: OpencliSpecJson | null | undefined, options?: OpencliToReferencesOptions): OpencliReference[];
+
+export { type Argument, type Arity, type CliInfo, type Command, type Contact, type Conventions, type ExitCode, type IndentStyle, type License, type LoadOpencliSpecOptions, type Metadata, type OpencliReference, type OpencliSpecJson, type OpencliToReferencesOptions, type Option, type XOpenApiBody, type XOpenApiBodyProp, type XOpenApiCommand, type XOpenApiParam, type XOpenApiRoot, type XOpenApiSecurity, findCommand, generateArguments, generateCommands, generateDescription, generateFlags, generateOptions, generateUsage, loadOpencliSpec, opencliToReferences };