@ayonli/jsext/types/cli.d.ts

A JavaScript extension package for building strong and modern applications.

export * from "./cli/common.ts";
/**
 * @deprecated use `runtime().tsSupport` from `@ayonli/jsext/runtime` module instead.
 */
export declare const isTsRuntime: () => boolean;
/**
 * @deprecated import `platform` from `@ayonli/jsext/runtime` module instead.
 */
export declare const platform: () => string;
/**
 * The result of command execution functions such as the {@link run},
 * {@link powershell} and {@link sudo}.
 */
export interface CommandResult {
    /**
     * The exit code of the command. A non-zero value indicates an error.
     */
    code: number;
    /**
     * The standard output of the command, may end with a newline character.
     */
    stdout: string;
    /**
     * The standard error of the command, may end with a newline character.
     */
    stderr: string;
}
/**
 * Executes a command in the terminal and returns the exit code and outputs.
 *
 * In Windows, this function will use PowerShell to execute the command when
 * possible, which has a lot UNIX-like aliases/commands available, such as `ls`,
 * `cat`, `rm`, etc.
 *
 * @example
 * ```ts
 * import { run } from "@ayonli/jsext/cli";
 *
 * const { code, stdout, stderr } = await run("echo", ["Hello, World!"]);
 *
 * console.log(code); // 0
 * console.log(JSON.stringify(stdout)); // "Hello, World!\n"
 * console.log(JSON.stringify(stderr)); // ""
 * ```
 */
export declare function run(cmd: string, args: string[]): Promise<CommandResult>;
/**
 * Executes the script inside PowerShell as if they were typed at the PowerShell
 * command prompt.
 *
 * This function can also be called within Windows Subsystem for Linux to
 * directly interact with PowerShell.
 *
 * NOTE: This function is only available in Windows and Windows Subsystem for
 * Linux.
 *
 * @example
 * ```ts
 * import { powershell } from "@ayonli/jsext/cli";
 *
 * const cmd = "ls";
 * const {
 *     code,
 *     stdout,
 *     stderr,
 * } = await powershell(`Get-Command -Name ${cmd} | Select-Object -ExpandProperty Source`);
 * ```
 */
export declare function powershell(script: string): Promise<CommandResult>;
/**
 * Options for the {@link sudo} function.
 */
export interface SudoOptions {
    /**
     * By default, the {@link sudo} function will use the `sudo` command when
     * available and running in text mode. Set this option to `true` to force
     * using the GUI prompt instead.
     *
     * NOTE: This option is not available and will be ignored in Windows
     * Subsystem for Linux.
     */
    gui?: boolean;
    /**
     * Customize the dialog's title when `gui` option is set.
     */
    title?: string;
}
/**
 * Executes a command with elevated privileges using `sudo` (or UAC in Windows).
 *
 * @example
 * ```ts
 * import { sudo } from "@ayonli/jsext/cli";
 *
 * await sudo("apt", ["install", "build-essential"]);
 * ```
 */
export declare function sudo(cmd: string, args: string[], options?: SudoOptions): Promise<CommandResult>;
/**
 * Returns the path of the given command if it exists in the system,
 * otherwise returns `null`.
 *
 * This function is available in Windows as well.
 *
 * @example
 * ```ts
 * import { which } from "@ayonli/jsext/cli";
 *
 * const path = await which("node");
 *
 * console.log(path);
 * // e.g. "/usr/bin/node" in UNIX/Linux or "C:\\Program Files\\nodejs\\node.exe" in Windows
 * ```
 */
export declare function which(cmd: string): Promise<string | null>;
/**
 * Opens the given file in a text editor.
 *
 * The `filename` can include a line number by appending `:<number>` or `#L<number>`,
 * however, this feature is not supported by all editors.
 *
 * This function will try to open VS Code if available, otherwise it will try to
 * open the default editor or a preferred one, such as `vim` or `nano` when available.
 *
 * Some editor may hold the terminal until the editor is closed, while others may
 * return immediately. Anyway, the operation is asynchronous and the function will
 * not block the thread.
 *
 * In the browser, this function will always try to open the file in VS Code,
 * regardless of whether it's available or not.
 *
 * @example
 * ```ts
 * import { edit } from "@ayonli/jsext/cli";
 *
 * await edit("path/to/file.txt");
 *
 * await edit("path/to/file.txt:10"); // open the file at line 10
 * ```
 */
export declare function edit(filename: string): Promise<void>;