@jinshuju/cli 0.1.1

package/dist/commands.d.ts

@@ -0,0 +1,84 @@
+import { JSON_OPTION, type OptionSpec } from './options.js';
+import type { HttpClient } from './http.js';
+/**
+ * Every command the CLI has, as data.
+ *
+ * The shape is `jinshuju <resource> <verb> [args] [flags]`: resources kept at
+ * one level, the parent given by a flag —
+ * `entry list --form <token>`, not `form entry list <token>`. Help, argument
+ * checking and dispatch all read this table, so a command cannot be reachable
+ * without its help, nor accept a flag it never described.
+ */
+export interface ArgSpec {
+    readonly name: string;
+    readonly required: boolean;
+    /** Takes the rest of the words; only the last argument may. */
+    readonly variadic?: boolean;
+    readonly description: string;
+}
+/** A repeated parameter arrives as a list; everything else is one value. */
+export type QueryValues = Record<string, string | readonly string[] | undefined>;
+export interface HttpRequest {
+    readonly method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    readonly path: string;
+    readonly query?: QueryValues;
+    readonly body?: unknown;
+    /** A multipart body, for the endpoints that take a file. */
+    readonly form?: FormData;
+}
+/** How a listing returns its next page, which is what `--all` follows. */
+export interface Pagination {
+    readonly items: string;
+    readonly cursor: string;
+}
+export interface CommandInput {
+    readonly args: Record<string, string>;
+    /** The values of a variadic argument, in the order given. */
+    readonly rest: readonly string[];
+    readonly options: Record<string, unknown>;
+}
+export interface Command {
+    /** The words that select it: `['entry', 'list']`. */
+    readonly path: readonly string[];
+    /** One line, shown under its resource in the root help. */
+    readonly summary: string;
+    readonly description?: string;
+    readonly args?: readonly ArgSpec[];
+    readonly options?: readonly OptionSpec[];
+    /**
+     * What `--json` expects, shown in help. A flag named `<json>` says nothing
+     * about what goes in the file, and a caller with nothing to copy from cannot
+     * guess it — so the commands that take a payload show one.
+     */
+    readonly payload?: readonly string[];
+    readonly examples?: readonly string[];
+    readonly request?: (input: CommandInput) => HttpRequest;
+    /**
+     * For the commands a single request cannot express: uploading a file and then
+     * acting on it. It gets the client and returns whatever should be printed.
+     */
+    readonly run?: (input: CommandInput, client: HttpClient) => Promise<unknown>;
+    readonly paginate?: Pagination;
+    /**
+     * Narrows the response to what the command is about. `field list` asks for a
+     * form because that is where fields live, but a caller asked for the fields.
+     */
+    readonly select?: (body: unknown) => unknown;
+    /**
+     * Reshapes the response for reading, and only for reading: `--output json`
+     * answers what the API answered. A command needs this when its payload is
+     * built for indexing rather than for looking at, and no generic renderer
+     * could know how to put it back together.
+     */
+    readonly render?: (body: unknown) => unknown;
+}
+export interface Resource {
+    readonly name: string;
+    readonly summary: string;
+}
+/** Resource order in the root help, and the one-liner each gets. */
+export declare const RESOURCES: readonly Resource[];
+export declare const COMMANDS: readonly Command[];
+/** The command whose path the words begin with, longest match first. */
+export declare function findCommand(words: readonly string[], commands?: readonly Command[]): Command | undefined;
+export { JSON_OPTION };