@stacksjs/cli 0.64.6 → 0.65.0

package/README.md

@@ -20,7 +20,7 @@ Now, you can use it in your project:
 ```js
 // command.ts
 // you may create create a relatively complex CLI UI/UX via the following:
-import { ExitCode, command, italic, prompts, spawn, spinner } from '@stacksjs/cli'
+import { command, ExitCode, italic, prompts, spawn, spinner } from '@stacksjs/cli'
 
 const stacks = command('stacks')
 
@@ -79,11 +79,11 @@ bun command.ts
 The `intro` and `outro` functions will print a message to begin or end a prompt session, respectively.
 
 ```js
-import { intro, outro } from '@stacksjs/cli';
+import { intro, outro } from '@stacksjs/cli'
 
-intro(`create-my-app`);
+intro(`create-my-app`)
 // Do stuff
-outro(`You're all set!`);
+outro(`You're all set!`)
 ```
 
 ### Cancellation
@@ -91,13 +91,13 @@ outro(`You're all set!`);
 The `isCancel` function is a guard that detects when a user cancels a question with `CTRL + C`. You should handle this situation for each prompt, optionally providing a nice cancellation message with the `cancel` utility.
 
 ```js
-import { isCancel, cancel, text } from '@stacksjs/cli';
+import { cancel, isCancel, text } from '@stacksjs/cli'
 
-const value = await text(/* TODO */);
+const value = await text(/* TODO */)
 
 if (isCancel(value)) {
-  cancel('Operation cancelled.');
-  process.exit(0);
+  cancel('Operation cancelled.')
+  process.exit(0)
 }
 ```
 
@@ -108,16 +108,17 @@ if (isCancel(value)) {
 The text component accepts a single line of text.
 
 ```js
-import { text } from '@stacksjs/cli';
+import { text } from '@stacksjs/cli'
 
 const meaning = await text({
   message: 'What is the meaning of life?',
   placeholder: 'Not sure',
   initialValue: '42',
   validate(value) {
-    if (value.length === 0) return `Value is required!`;
+    if (value.length === 0)
+      return `Value is required!`
   },
-});
+})
 ```
 
 ### Confirm
@@ -125,11 +126,11 @@ const meaning = await text({
 The confirm component accepts a yes or no answer. The result is a boolean value of `true` or `false`.
 
 ```js
-import { confirm } from '@stacksjs/cli';
+import { confirm } from '@stacksjs/cli'
 
 const shouldContinue = await confirm({
   message: 'Do you want to continue?',
-});
+})
 ```
 
 ### Select
@@ -137,7 +138,7 @@ const shouldContinue = await confirm({
 The select component allows a user to choose one value from a list of options. The result is the `value` prop of a given option.
 
 ```js
-import { select } from '@stacksjs/cli';
+import { select } from '@stacksjs/cli'
 
 const projectType = await select({
   message: 'Pick a project type.',
@@ -146,7 +147,7 @@ const projectType = await select({
     { value: 'js', label: 'JavaScript' },
     { value: 'coffee', label: 'CoffeeScript', hint: 'oh no' },
   ],
-});
+})
 ```
 
 ### Multi-Select
@@ -154,7 +155,7 @@ const projectType = await select({
 The `multiselect` component allows a user to choose many values from a list of options. The result is an array with all selected `value` props.
 
 ```js
-import { multiselect } from '@stacksjs/cli';
+import { multiselect } from '@stacksjs/cli'
 
 const additionalTools = await multiselect({
   message: 'Select additional tools.',
@@ -164,7 +165,7 @@ const additionalTools = await multiselect({
     { value: 'gh-action', label: 'GitHub Action' },
   ],
   required: false,
-});
+})
 ```
 
 ### Spinner
@@ -172,12 +173,12 @@ const additionalTools = await multiselect({
 The spinner component surfaces a pending action, such as a long-running download or dependency installation.
 
 ```js
-import { spinner } from '@stacksjs/cli';
+import { spinner } from '@stacksjs/cli'
 
-const s = spinner();
-s.start('Installing via npm');
+const s = spinner()
+s.start('Installing via npm')
 // Do installation here
-s.stop('Installed via npm');
+s.stop('Installed via npm')
 ```
 
 ## Utilities
@@ -187,7 +188,7 @@ s.stop('Installed via npm');
 Grouping prompts together is a great way to keep your code organized. This accepts a JSON object with a name that can be used to reference the group later. The second argument is an optional but has a `onCancel` callback that will be called if the user cancels one of the prompts in the group.
 
 ```js
-import * as p from '@stacksjs/cli';
+import * as p from '@stacksjs/cli'
 
 const group = await p.group(
   {
@@ -207,13 +208,13 @@ const group = await p.group(
     // On Cancel callback that wraps the group
     // So if the user cancels one of the prompts in the group this function will be called
     onCancel: ({ results }) => {
-      p.cancel('Operation cancelled.');
-      process.exit(0);
+      p.cancel('Operation cancelled.')
+      process.exit(0)
     },
   }
-);
+)
 
-console.log(group.name, group.age, group.color);
+console.log(group.name, group.age, group.color)
 ```
 
 ### Tasks
@@ -226,10 +227,10 @@ await p.tasks([
     title: 'Installing via npm',
     task: async (message) => {
       // Do installation here
-      return 'Installed via npm';
+      return 'Installed via npm'
     },
   },
-]);
+])
 ```
 
 To view a more detailed example, check out [Buddy](../../buddy/).

package/dist/actions/index.d.ts

@@ -0,0 +1 @@
+export * from "./install";

package/dist/actions/install.d.ts

@@ -0,0 +1,26 @@
+interface InstallPackageOptions {
+	cwd?: string;
+	dev?: boolean;
+	silent?: boolean;
+	packageManager?: string;
+	packageManagerVersion?: string;
+	preferOffline?: boolean;
+	additionalArgs?: string[];
+}
+/**
+* Install an npm package.
+*
+* @param name - The package name to install.
+* @param options - The options to pass to the install.The options to pass to the install.
+* @returns The result of the install.
+*/
+export declare function installPackage(name: string, options?: InstallPackageOptions): Promise<any>;
+/**
+* Install a Stack into your project.
+*
+* @param name - The Stack name to install.
+* @param options - The options to pass to the install.
+* @returns The result of the install.
+*/
+export declare function installStack(name: string, options?: InstallPackageOptions): Promise<any>;
+export {};

package/dist/app.d.ts

@@ -0,0 +1,100 @@
+export { isCancel } from "@clack/core";
+export interface TextOptions {
+	message: string;
+	placeholder?: string;
+	defaultValue?: string;
+	initialValue?: string;
+	validate?: (value: string) => string | void;
+}
+export declare function text(opts: TextOptions): Promise<string | symbol>;
+export interface PasswordOptions {
+	message: string;
+	mask?: string;
+	validate?: (value: string) => string | void;
+}
+export declare function password(opts: PasswordOptions): Promise<string | symbol>;
+export interface ConfirmOptions {
+	message: string;
+	active?: string;
+	inactive?: string;
+	initialValue?: boolean;
+}
+export declare function confirm(opts: ConfirmOptions): Promise<boolean | symbol>;
+type Primitive = Readonly<string | boolean | number>;
+type Option<Value> = Value extends Primitive ? {
+	value: Value;
+	label?: string;
+	hint?: string;
+} : {
+	value: Value;
+	label: string;
+	hint?: string;
+};
+export interface SelectOptions<Value> {
+	message: string;
+	options: Option<Value>[];
+	initialValue?: Value;
+	maxItems?: number;
+}
+export declare function select<Value>(opts: SelectOptions<Value>): Promise<Value | symbol>;
+export declare function selectKey<Value extends string>(opts: SelectOptions<Value>): Promise<Value | symbol>;
+export interface MultiSelectOptions<Value> {
+	message: string;
+	options: Option<Value>[];
+	initialValues?: Value[];
+	maxItems?: number;
+	required?: boolean;
+	cursorAt?: Value;
+}
+export declare function multiselect<Value>(opts: MultiSelectOptions<Value>): Promise<Value[] | symbol>;
+export interface GroupMultiSelectOptions<Value> {
+	message: string;
+	options: Record<string, Option<Value>[]>;
+	initialValues?: Value[];
+	required?: boolean;
+	cursorAt?: Value;
+}
+export declare function groupMultiselect<Value>(opts: GroupMultiSelectOptions<Value>): Promise<Value[] | symbol>;
+export declare function note(message?: string, title?: string): void;
+export declare function cancel(message?: string): void;
+export declare function intro(title?: string): void;
+export declare function outro(message?: string): void;
+interface Spinner {
+	start: (msg: string) => void;
+	stop: (msg: string, code: number) => void;
+	message: (msg: string) => void;
+}
+export declare function spinner(): Spinner;
+export type PromptGroupAwaitedReturn<T> = { [P in keyof T] : Exclude<Awaited<T[P]>, symbol> };
+export interface PromptGroupOptions<T> {
+	/**
+	* Control how the group can be canceled
+	* if one of the prompts is canceled.
+	*/
+	onCancel?: (opts: { results: Prettify<Partial<PromptGroupAwaitedReturn<T>>> }) => void;
+}
+type Prettify<T> = { [P in keyof T] : T[P] } & {};
+export type PromptGroup<T> = { [P in keyof T] : (opts: { results: Prettify<Partial<PromptGroupAwaitedReturn<Omit<T, P>>>> }) => void | Promise<T[P] | void> };
+/**
+* Define a group of prompts to be displayed
+* and return a results of objects within the group
+*/
+export declare function group<T>(prompts: PromptGroup<T>, opts?: PromptGroupOptions<T>): Promise<Prettify<PromptGroupAwaitedReturn<T>>>;
+export interface Task {
+	/**
+	* Task title
+	*/
+	title: string;
+	/**
+	* Task function
+	*/
+	task: (message: (string: string) => void) => string | Promise<string> | void | Promise<void>;
+	/**
+	* If enabled === false the task will be skipped
+	*/
+	enabled?: boolean;
+}
+/**
+* Define a group of tasks to be executed
+*/
+export declare function tasks(tasks: Task[]): Promise<void>;

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+import { CAC } from "cac";
+export interface ParsedArgv {
+	args: ReadonlyArray<string>;
+	options: { [k: string]: any };
+}
+interface CliOptions {
+	name?: string;
+}
+export declare function cli(name?: string | CliOptions, options?: CliOptions): CAC;
+export { CAC };

package/dist/command.d.ts

@@ -0,0 +1,32 @@
+import type { Result } from "@stacksjs/error-handling";
+import type { CliOptions, Readable, Subprocess, Writable } from "@stacksjs/types";
+type CommandOptionTuple = [string, string, { default: boolean }];
+interface CommandOptionObject {
+	name: string;
+	description: string;
+	default: boolean | string;
+}
+type CommandOptions = CommandOptionTuple | CommandOptionObject[];
+interface Options {
+	name: string;
+	description: string;
+	active: boolean;
+	options: CommandOptions;
+	run: (options?: CliOptions) => Promise<any>;
+	onFail: (error: Error) => void;
+	onSuccess: () => void;
+}
+export declare class Command {
+	name: Options["name"];
+	description: Options["description"];
+	options: Options["options"];
+	run: Options["run"];
+	onFail: Options["onFail"];
+	onSuccess: Options["onSuccess"];
+	constructor({ name, description, options, run, onFail, onSuccess }: Options);
+}
+export declare const command: {
+	run: (command: string, options?: CliOptions) => Promise<Result<Subprocess<Writable, Readable, Readable>, Error>>;
+	runSync: (command: string, options?: CliOptions) => Promise<Result<Subprocess<Writable, Readable, Readable>, Error>>;
+};
+export {};

package/dist/console.d.ts

@@ -0,0 +1,3 @@
+import { log } from "@stacksjs/logging";
+import prompts from "prompts";
+export { log, prompts };

package/dist/exec.d.ts

@@ -0,0 +1,40 @@
+import type { CliOptions, Subprocess } from "@stacksjs/types";
+import { type Result } from "@stacksjs/error-handling";
+/**
+* Execute a command.
+*
+* @param command The command to execute.
+* @param options The options to pass to the command.
+* @returns The result of the command.
+* @example
+* ```ts
+* const result = await exec('ls')
+*
+* if (result.isErr())
+*   console.error(result.error)
+* else
+*   console.log(result)
+* ```
+* @example
+* ```ts
+* const result = await exec('ls', { cwd: '/home' })
+* ```
+*/
+export declare function exec(command: string | string[], options?: CliOptions): Promise<Result<Subprocess, Error>>;
+/**
+* Execute a command and return result.
+*
+* @param command The command to execute.
+* @returns The result of the command.
+* @example
+* ```ts
+* const output = execSync('ls')
+*
+* console.log(output)
+* ```
+* @example
+* ```ts
+* const output = execSync('ls', { cwd: '/home' })
+* ```
+*/
+export declare function execSync(command: string | string[], options?: CliOptions): Promise<string>;

package/dist/helpers.d.ts

@@ -0,0 +1,9 @@
+import type { IntroOptions, OutroOptions } from "@stacksjs/types";
+/**
+* Prints the intro message.
+*/
+export declare function intro(command: string, options?: IntroOptions): Promise<number>;
+/**
+* Prints the outro message.
+*/
+export declare function outro(text: string, options?: OutroOptions, error?: Error | string): Promise<number>;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./actions";
+export * from "./cli";
+export * from "./command";
+export * from "./console";
+export * from "./exec";
+export * from "./helpers";
+export * from "./parse";
+export * from "./run";
+export * from "./spinner";
+export * from "./utils";