convoker 0.1.0

package/dist/index.js

@@ -0,0 +1,13 @@
+import { Command as m, l as e } from "./command.js";
+import { e as a } from "./chunks/error-Cj2qDfOl.js";
+import { i as f } from "./chunks/input-COjWPD53.js";
+import { a as s } from "./chunks/color-CiruG_zQ.js";
+import { i } from "./chunks/index-G2nVXKup.js";
+export {
+  m as Command,
+  s as color,
+  a as error,
+  f as i,
+  e as log,
+  i as prompt
+};

package/dist/input.d.ts

@@ -0,0 +1,248 @@
+/**
+ * Creates a new positional argument.
+ * @param kind The kind of positional argument.
+ * @returns A new positional argument.
+ */
+export declare function argument<T extends Kind>(kind: T): Positional<T>;
+
+/**
+ * A basic input type.
+ */
+export declare type BasicKind = "boolean" | "string" | "number" | "bigint";
+
+/**
+ * Converts a value from a Kind to a TypeScript type.
+ * @param kind The kind to convert to.
+ * @param value The value to convert.
+ * @returns The converted value.
+ */
+export declare function convert<TKind extends Kind>(kind: TKind, value: string): Promise<TypeOf<TKind>>;
+
+/**
+ * Infers a TypeScript type from an option or positional.
+ */
+export declare type InferEntry<T> = T extends {
+    $kind: infer TKind extends Kind;
+    $required: infer Required;
+    $list: infer List;
+} ? List extends true ? Required extends true ? TypeOf<TKind>[] : TypeOf<TKind>[] | undefined : Required extends true ? TypeOf<TKind> : TypeOf<TKind> | undefined : never;
+
+/**
+ * Infers TypeScript types from an input object.
+ */
+export declare type InferInput<T extends Input> = {
+    [K in keyof T]: InferEntry<T[K]>;
+};
+
+/**
+ * An input object.
+ */
+export declare interface Input {
+    [x: string]: Option_2<any, any, any> | Positional<any, any, any>;
+}
+
+/**
+ * An input type.
+ */
+export declare type Kind = BasicKind | StandardSchemaV1<any, any>;
+
+/**
+ * Creates a new option.
+ * @param kind The kind of option.
+ * @param names The names of the option.
+ * @returns A new option.
+ */
+export declare function option<T extends Kind>(kind: T, ...names: string[]): Option_2<T>;
+
+/**
+ * An option.
+ */
+declare class Option_2<TKind extends Kind, TRequired extends boolean = true, TList extends boolean = false> {
+    /**
+     * The kind of this option.
+     */
+    $kind: TKind;
+    /**
+     * The aliases of this option.
+     */
+    $names: string[];
+    /**
+     * The description of this option.
+     */
+    $description: string | undefined;
+    /**
+     * The default value of this option.
+     */
+    $default: TypeOf<TKind> | undefined;
+    /**
+     * If this option is required.
+     */
+    $required: TRequired;
+    /**
+     * If this option is a list.
+     */
+    $list: TList;
+    /**
+     * Creates a new option.
+     * @param kind The type of this option.
+     * @param names The names of this option.
+     */
+    constructor(kind: TKind, names: string[]);
+    /**
+     * Makes this option a list.
+     * @returns this
+     */
+    list(): Option_2<TKind, TRequired, true>;
+    /**
+     * Makes this option required.
+     * @returns this
+     */
+    required(): Option_2<TKind, true, TList>;
+    /**
+     * Makes this option optional.
+     * @returns this
+     */
+    optional(): Option_2<TKind, false, TList>;
+    /**
+     * Sets a default value.
+     * @param value The default value.
+     * @returns this
+     */
+    default(value: TypeOf<TKind>): this;
+    /**
+     * Sets a description.
+     * @param desc The description.
+     * @returns this
+     */
+    description(desc: string): this;
+}
+export { Option_2 as Option }
+
+/**
+ * A positional argument.
+ */
+export declare class Positional<TKind extends Kind, TRequired extends boolean = true, TList extends boolean = false> {
+    /**
+     * The type of this argument.
+     */
+    $kind: TKind;
+    /**
+     * The default value of this argument.
+     */
+    $default: TypeOf<TKind> | undefined;
+    /**
+     * The description of this argument.
+     */
+    $description: string | undefined;
+    /**
+     * If this argument is required.
+     */
+    $required: TRequired;
+    /**
+     * If this argument is a list.
+     */
+    $list: TList;
+    /**
+     * Creates a new positional argument.
+     * @param kind The positional argument.
+     */
+    constructor(kind: TKind);
+    /**
+     * Makes this argument a list.
+     * @returns this
+     */
+    list(): Positional<TKind, TRequired, true>;
+    /**
+     * Makes this argument required.
+     * @returns this
+     */
+    required(): Positional<TKind, true, TList>;
+    /**
+     * Makes this argument optional.
+     * @returns this
+     */
+    optional(): Positional<TKind, false, TList>;
+    /**
+     * Sets a default value.
+     * @param value The default value.
+     * @returns this
+     */
+    default(value: TypeOf<TKind>): this;
+    /**
+     * Sets a description.
+     * @param desc The description.
+     * @returns this
+     */
+    description(desc: string): this;
+}
+
+/**
+ * Creates a new positional argument.
+ * @param kind The kind of positional argument.
+ * @returns A new positional argument.
+ */
+export declare function positional<T extends Kind>(kind: T): Positional<T>;
+
+/** The Standard Schema interface. */
+declare interface StandardSchemaV1<Input = unknown, Output = Input> {
+    /** The Standard Schema properties. */
+    readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+
+declare namespace StandardSchemaV1 {
+    /** The Standard Schema properties interface. */
+    interface Props<Input = unknown, Output = Input> {
+        /** The version number of the standard. */
+        readonly version: 1;
+        /** The vendor name of the schema library. */
+        readonly vendor: string;
+        /** Validates unknown input values. */
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        /** Inferred types associated with the schema. */
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    /** The result interface of the validate function. */
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    /** The result interface if validation succeeds. */
+    interface SuccessResult<Output> {
+        /** The typed output value. */
+        readonly value: Output;
+        /** The non-existent issues. */
+        readonly issues?: undefined;
+    }
+    /** The result interface if validation fails. */
+    interface FailureResult {
+        /** The issues of failed validation. */
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    /** The issue interface of the failure output. */
+    interface Issue {
+        /** The error message of the issue. */
+        readonly message: string;
+        /** The path of the issue, if any. */
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    /** The path segment interface of the issue. */
+    interface PathSegment {
+        /** The key representing a path segment. */
+        readonly key: PropertyKey;
+    }
+    /** The Standard Schema types interface. */
+    interface Types<Input = unknown, Output = Input> {
+        /** The input type of the schema. */
+        readonly input: Input;
+        /** The output type of the schema. */
+        readonly output: Output;
+    }
+    /** Infers the input type of a Standard Schema. */
+    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+    /** Infers the output type of a Standard Schema. */
+    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+
+/**
+ * Converts a Kind to a TypeScript type.
+ */
+export declare type TypeOf<T extends Kind> = T extends StandardSchemaV1<any, infer Out> ? Out : T extends "boolean" ? boolean : T extends "string" ? string : T extends "number" ? number : T extends "bigint" ? bigint : never;
+
+export { }

package/dist/input.js

@@ -0,0 +1,10 @@
+import "./chunks/standard-schema-Dn3nwAxU.js";
+import { O as t, P as i, a as n, c as p, o as r, p as e } from "./chunks/input-COjWPD53.js";
+export {
+  t as Option,
+  i as Positional,
+  n as argument,
+  p as convert,
+  r as option,
+  e as positional
+};

package/dist/prompt/raw.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Reads a line from standard input.
+ * @param message The message.
+ * @param def Default value.
+ * @param opts Options for reading a line.
+ * @returns The line that was read.
+ */
+export declare function readLine(message?: string, def?: string, opts?: {
+    masked?: boolean;
+    maskChar?: string;
+    multiline?: boolean;
+}): Promise<string>;
+/**
+ * Reads a single key from stdin.
+ * @returns The key that was read.
+ */
+export declare function readKey(): Promise<string>;
+/**
+ * Clears `lines` amount of lines.
+ * @param lines Amount of lines to clear.
+ */
+export declare function clearLines(lines?: number): void;
+/**
+ * Moves the cursor up `n` times.
+ * @param n The amount of steps to move.
+ */
+export declare function cursorUp(n?: number): void;
+/**
+ * Moves the cursor down `n` times.
+ * @param n The amount of steps to move.
+ */
+export declare function cursorDown(n?: number): void;

package/dist/prompt/raw.js

@@ -0,0 +1,9 @@
+import "../chunks/utils-DdmSEjLc.js";
+import { c as s, e as o, b as c, a as i, r as n } from "../chunks/__vite-browser-external-DQYBmsno.js";
+export {
+  s as clearLines,
+  o as cursorDown,
+  c as cursorUp,
+  i as readKey,
+  n as readLine
+};

package/dist/prompt.d.ts

@@ -0,0 +1,258 @@
+import { StandardSchemaV1 } from '../../../../../../../../../../src/standard-schema';
+import { Theme } from '../../../../../../../../../../src/color';
+
+/**
+ * Base options for prompts.
+ */
+export declare interface BaseOpts<T> {
+    /**
+     * The message of the prompt.
+     */
+    message: string;
+    /**
+     * An `AbortSignal` to cancel the prompt.
+     */
+    signal?: AbortSignal;
+    /**
+     * The default value.
+     */
+    default?: T;
+    /**
+     * The theme of the prompt.
+     */
+    theme?: Theme;
+    /**
+     * A validator function, or a Standard Schema validator.
+     */
+    validate?: StandardSchemaV1<any, T> | ((value: T) => boolean | T);
+}
+
+/**
+ * Clears `lines` amount of lines.
+ * @param lines Amount of lines to clear.
+ */
+declare function clearLines(lines?: number): void;
+
+/**
+ * Prompts the user to confirm an action.
+ * @param opts Options for confirm input.
+ * @returns If the user picked Yes.
+ */
+declare function confirm_2(opts: ConfirmOpts): Promise<boolean>;
+export { confirm_2 as confirm }
+
+/**
+ * Options for confirm input.
+ */
+export declare interface ConfirmOpts extends BaseOpts<boolean> {
+    /**
+     * What gets displayed for the Yes option.
+     */
+    yesLabel?: string;
+    /**
+     * What gets displayed for the No option.
+     */
+    noLabel?: string;
+}
+
+/**
+ * Moves the cursor down `n` times.
+ * @param n The amount of steps to move.
+ */
+declare function cursorDown(n?: number): void;
+
+/**
+ * Moves the cursor up `n` times.
+ * @param n The amount of steps to move.
+ */
+declare function cursorUp(n?: number): void;
+
+/**
+ * Opens the system editor, or asks for input in the terminal as fallback.
+ * @param opts Options for opening the system editor.
+ * @returns The result of the system editor.
+ */
+export declare function editor(opts: EditorOpts): Promise<string>;
+
+/**
+ * Options for opening the system editor.
+ */
+export declare interface EditorOpts extends BaseOpts<string> {
+    /**
+     * The initial value.
+     */
+    initial?: string;
+    /**
+     * The language of the value.
+     */
+    language?: string;
+    /**
+     * If the input is required for continuing or not.
+     */
+    required?: boolean;
+}
+
+/**
+ * Prompts the user to select multiple options.
+ * @param opts Options for select input.
+ * @returns The selected options.
+ */
+export declare function multiselect<T>(opts: SelectOpts<T>): Promise<T[]>;
+
+/**
+ * Prompts the user for a password.
+ * @param opts Options for password input.
+ * @returns The password.
+ */
+export declare function password(opts: PasswordOpts): Promise<string>;
+
+/**
+ * Options for password input.
+ */
+export declare interface PasswordOpts extends TextOpts {
+    /**
+     * The mask for the password input.
+     */
+    mask?: string;
+    /**
+     * If the user should be asked to confirm the password, by typing it again.
+     */
+    confirm?: boolean;
+}
+
+declare namespace raw {
+    export {
+        readLine,
+        readKey,
+        clearLines,
+        cursorUp,
+        cursorDown
+    }
+}
+export { raw }
+
+/**
+ * Reads a single key from stdin.
+ * @returns The key that was read.
+ */
+declare function readKey(): Promise<string>;
+
+/**
+ * Reads a line from standard input.
+ * @param message The message.
+ * @param def Default value.
+ * @param opts Options for reading a line.
+ * @returns The line that was read.
+ */
+declare function readLine(message?: string, def?: string, opts?: {
+    masked?: boolean;
+    maskChar?: string;
+    multiline?: boolean;
+}): Promise<string>;
+
+/**
+ * Prompts the user to search through a list of options.
+ * @param opts Options for search input.
+ * @returns The selected option.
+ */
+export declare function search<T>(opts: SearchOpts<T>): Promise<T>;
+
+/**
+ * Options for search input.
+ */
+export declare interface SearchOpts<T> extends BaseOpts<T> {
+    /**
+     * Every option the user can search through.
+     */
+    options: SelectOption<T>[];
+    /**
+     * Placeholder for the search input.
+     */
+    placeholder?: string;
+    /**
+     * Minimum length for a query string.
+     */
+    minQueryLength?: number;
+    /**
+     * Filters a single option.
+     * @param query The search query.
+     * @param option The option to filter.
+     */
+    filter?(query: string, option: SelectOption<T>): boolean;
+}
+
+/**
+ * Prompts the user to select a single option.
+ * @param opts Options for select input.
+ * @returns The selected option's value.
+ */
+export declare function select<T>(opts: SelectOpts<T>): Promise<T>;
+
+/**
+ * An option for select input.
+ */
+export declare interface SelectOption<T> {
+    /**
+     * The label (what gets displayed) of the select option.
+     */
+    label: string;
+    /**
+     * The value (what gets returned) of the select option.
+     */
+    value: T;
+    /**
+     * A description of the option.
+     */
+    hint?: string;
+    /**
+     * If this option is disabled.
+     */
+    disabled?: boolean;
+}
+
+/**
+ * Options for select input.
+ */
+export declare interface SelectOpts<T> extends BaseOpts<T> {
+    /**
+     * Every option the user can pick from.
+     */
+    options: SelectOption<T>[];
+    /**
+     * The initial option selected.
+     */
+    initialIndex?: number;
+}
+
+/**
+ * Sets the theme of the prompts.
+ * @param t The new theme.
+ */
+export declare function setTheme(t: Theme): void;
+
+/**
+ * Prompts the user for text input.
+ * @param opts Options for text input.
+ * @returns The text the user typed in, or the default.
+ */
+export declare function text(opts: TextOpts): Promise<string>;
+
+/**
+ * Options for text input.
+ */
+export declare interface TextOpts extends BaseOpts<string> {
+    /**
+     * A placeholder, displayed when the user hasn't typed anything yet.
+     */
+    placeholder?: string;
+    /**
+     * Minimum length of the input.
+     */
+    minLength?: number;
+    /**
+     * Maximum length of the input.
+     */
+    maxLength?: number;
+}
+
+export { }

package/dist/prompt.js

@@ -0,0 +1,17 @@
+import "./chunks/color-CiruG_zQ.js";
+import "./chunks/standard-schema-Dn3nwAxU.js";
+import "./chunks/error-Cj2qDfOl.js";
+import "./chunks/utils-DdmSEjLc.js";
+import { d as m } from "./chunks/__vite-browser-external-DQYBmsno.js";
+import { c as i, e as c, m as d, p as f, b as l, a as x, s as h, t as w } from "./chunks/index-G2nVXKup.js";
+export {
+  i as confirm,
+  c as editor,
+  d as multiselect,
+  f as password,
+  m as raw,
+  l as search,
+  x as select,
+  h as setTheme,
+  w as text
+};

package/dist/raw.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Clears `lines` amount of lines.
+ * @param lines Amount of lines to clear.
+ */
+export declare function clearLines(lines?: number): void;
+
+/**
+ * Moves the cursor down `n` times.
+ * @param n The amount of steps to move.
+ */
+export declare function cursorDown(n?: number): void;
+
+/**
+ * Moves the cursor up `n` times.
+ * @param n The amount of steps to move.
+ */
+export declare function cursorUp(n?: number): void;
+
+/**
+ * Reads a single key from stdin.
+ * @returns The key that was read.
+ */
+export declare function readKey(): Promise<string>;
+
+/**
+ * Reads a line from standard input.
+ * @param message The message.
+ * @param def Default value.
+ * @param opts Options for reading a line.
+ * @returns The line that was read.
+ */
+export declare function readLine(message?: string, def?: string, opts?: {
+    masked?: boolean;
+    maskChar?: string;
+    multiline?: boolean;
+}): Promise<string>;
+
+export { }

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "convoker",
+  "version": "0.1.0",
+  "description": "A simple, type safe CLI framework for TypeScript.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./command": {
+      "types": "./dist/command.d.ts",
+      "default": "./dist/command.js"
+    },
+    "./input": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/input.js"
+    },
+    "./color": {
+      "types": "./dist/color.d.ts",
+      "default": "./dist/color.js"
+    },
+    "./prompt": {
+      "types": "./dist/prompt.js",
+      "default": "./dist/prompt/index.js"
+    },
+    "./prompt/raw": {
+      "types": "./dist/prompt/raw.d.ts",
+      "default": "./dist/prompt/raw.js"
+    },
+    "./error": {
+      "types": "./dist/error.d.ts",
+      "default": "./dist/error.js"
+    }
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "cli",
+    "command",
+    "args",
+    "argv",
+    "option"
+  ],
+  "author": "trailfrost",
+  "license": "MIT",
+  "devDependencies": {
+    "@eslint/js": "^9.36.0",
+    "eslint": "^9.36.0",
+    "globals": "^16.4.0",
+    "prettier": "^3.6.2",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.45.0",
+    "valibot": "^1.1.0",
+    "vite": "^7.1.12",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "test": "vitest tests",
+    "build": "tsc -b && vite build",
+    "format": "prettier --check .",
+    "format!": "prettier --write .",
+    "lint": "eslint .",
+    "lint!": "eslint --fix ."
+  }
+}