@stacksjs/cli 0.38.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2022 Open Web Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# Stacks CLI
+
+The simple way to build beautiful CLIs.
+
+## ☘️ Features
+
+- [x] Easily create beautiful CLI apps
+- [x] Lightweight, beautiful and user-friendly interactive prompts
+- [x] Elegant terminal spinners
+- [x] Helper methods to run commands
+
+## 🤖 Usage
+
+```bash
+pnpm i -D @stacksjs/cli
+```
+
+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 { command, log, prompts, spawn, spinner, ExitCode, italic } from '@stacksjs/cli'
+
+const stacks = command('stacks')
+
+stacks
+  .command('example', 'A dummy command') // pnpm stacks example
+  .option('-i, --install', 'The install option', { default: true })
+  .action(async (options) => {
+    if (options.install)
+      await install()
+
+    const answer = await prompts.select({
+      type: 'select',
+      message: 'Are you trying to run this command?',
+      choices: [
+        { title: 'Run the command', value: 'run' },
+        { title: 'Do not run the command', value: 'do-not-run' },
+      ],
+    })
+
+    if (answer === 'run')
+      install()
+    else if (answer === 'do-not-run')
+      log.info('Not running the command')
+    else process.exit(ExitCode.InvalidArgument)
+  })
+
+async function install() {
+  try {
+    const spin = spinner('Running...').start()
+    setTimeout(() => {
+      spin.text = italic('This may take a little while...')
+    }, 5000)
+    await spawn('pnpm install')
+    spin.stop()
+  } catch (error) {
+    log.error(error)
+  }
+}
+
+command.help() // automatically expose a -h and --help flag
+command.version(version) // automatically expose a -v and --version flag
+command.parse() // parse the command
+```
+
+You may now run the command via:
+
+```bash
+esno command.ts
+```
+
+To view a more detailed example, check out the [Stacks Runtime](../runtime/).
+
+_You may also use any of the following CLI utilities:_
+
+```js
+import {
+  log,
+  ansi256Bg, bold, dim, hidden, inverse, italic, link, reset, strikethrough, underline,
+  bgBlack, bgBlue, bgCyan, bgGray, bgGreen, bgLightBlue, bgLightCyan, bgLightGray, bgLightGreen, bgLightMagenta, bgLightRed, bgLightYellow, bgMagenta, bgRed, bgWhite, bgYellow,
+  black, blue, cyan, gray, green, lightBlue, lightCyan, lightGray, lightGreen, lightMagenta, lightRed, lightYellow, magenta, red, white, yellow,
+} from '@stacksjs/cli'
+
+log.info(`hello ${bold(italic('world'))`)
+```
+
+To view the full documentation, please visit [https://stacksjs.dev/cli](https://stacksjs.dev/cli).
+
+## 🧪 Testing
+
+```bash
+pnpm test
+```
+
+## 📈 Changelog
+
+Please see our [releases](https://github.com/stacksjs/stacks/releases) page for more information on what has changed recently.
+
+## 💪🏼 Contributing
+
+Please see [CONTRIBUTING](../../.github/CONTRIBUTING.md) for details.
+
+## 🏝 Community
+
+For help, discussion about best practices, or any other conversation that would benefit from being searchable:
+
+[Discussions on GitHub](https://github.com/stacksjs/stacks/discussions)
+
+For casual chit-chat with others using this package:
+
+[Join the Open Web Discord Server](https://discord.ow3.org)
+
+## 🙏🏼 Credits
+
+Many thanks to the following core technologies & people who have contributed to this package:
+
+- [CAC](https://github.com/cacjs/cac)
+- [Ora](https://github.com/sindresorhus/ora)
+- [Consola](https://github.com/unjs/consola)
+- [Chris Breuer](https://github.com/chrisbbreuer)
+- [All Contributors](../../contributors)
+
+## 📄 License
+
+The MIT License (MIT). Please see [LICENSE](https://github.com/stacksjs/stacks/tree/main/LICENSE.md) for more information.
+
+Made with ❤️

package/dist/actions/index.d.ts

@@ -0,0 +1,2 @@
+export * from './install';
+export * from './run';

package/dist/actions/index.mjs

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

package/dist/actions/install.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Install an npm package.
+ *
+ * @param pkg - The package name to install.
+ * @returns The result of the install.
+ */
+export declare function installPackage(pkg: string): Promise<execa.ExecaReturnValue<string>>;
+/**
+ * Install a Stack into your project.
+ *
+ * @param pkg - The Stack name to install.
+ * @returns The result of the install.
+ */
+export declare function installStack(name: string): Promise<execa.ExecaReturnValue<string>>;

package/dist/actions/install.mjs

@@ -0,0 +1,7 @@
+import { installPackage as installPkg } from "@antfu/install-pkg";
+export async function installPackage(pkg) {
+  return await installPkg(pkg, { silent: true });
+}
+export async function installStack(name) {
+  return await installPkg(`@stacksjs/${name}`, { silent: true });
+}

package/dist/actions/run.d.ts

@@ -0,0 +1,26 @@
+import type { CliOptions, CommandResult, Result } from '@stacksjs/types';
+/**
+ * Execute a command.
+ *
+ * @param command The command to execute.
+ * @param options The options to pass to the command.
+ * @param errorMsg The name of the error to throw if the command fails.
+ * @returns The result of the command.
+ */
+export declare function exec(command: string, options?: CliOptions): any;
+/**
+ * Run a command the Stacks way.
+ *
+ * @param command The command to run.
+ * @param options The options to pass to the command.
+ * @returns The result of the command.
+ */
+export declare function runCommand(command: string, options?: CliOptions): Promise<any>;
+/**
+ * Run many commands—the Stacks way.
+ *
+ * @param commands The command to run.
+ * @param options The options to pass to the command.
+ * @returns The result of the command.
+ */
+export declare function runCommands(commands: string[], options?: CliOptions): Promise<Result<CommandResult<string>, Error>[]>;

package/dist/actions/run.mjs

@@ -0,0 +1,37 @@
+import { italic } from "@stacksjs/cli";
+import { determineDebugMode } from "@stacksjs/config";
+import { ResultAsync } from "@stacksjs/errors";
+import { projectPath } from "@stacksjs/path";
+import { spawn } from "../command.mjs";
+import { startAnimation } from "../helpers.mjs";
+export function exec(command, options) {
+  const cwd = options?.cwd || projectPath();
+  const stdio = determineDebugMode(options) ? "inherit" : "ignore";
+  return ResultAsync.fromPromise(
+    spawn(command, { stdio, cwd }),
+    () => new Error(`Failed to execute command: ${italic(command)}`)
+  );
+}
+export async function runCommand(command, options) {
+  return await exec(command, options);
+}
+export async function runCommands(commands, options) {
+  let spinner;
+  if (!determineDebugMode(options))
+    spinner = startAnimation();
+  const results = [];
+  for (const command of commands) {
+    const result = await runCommand(command, options);
+    if (result.isOk())
+      results.push(result);
+    if (result.isErr()) {
+      if (spinner)
+        spinner.fail(`Failed to run command "${command}" with message: ${result.error.message}`);
+      results.push(result);
+      break;
+    }
+  }
+  if (spinner)
+    spinner.stop();
+  return results;
+}

package/dist/command.d.ts

@@ -0,0 +1,4 @@
+import { execaCommand } from 'execa';
+declare const spawn: typeof execaCommand;
+declare const command: (name?: string | undefined) => import("cac").CAC;
+export { spawn, command };

package/dist/command.mjs

@@ -0,0 +1,5 @@
+import cac from "cac";
+import { execaCommand } from "execa";
+const spawn = execaCommand;
+const command = cac;
+export { spawn, command };

package/dist/console.d.ts

@@ -0,0 +1,3 @@
+import { log } from '@stacksjs/logging';
+declare const prompts: any;
+export { log, prompts };

package/dist/console.mjs

@@ -0,0 +1,4 @@
+import { log } from "@stacksjs/logging";
+import Prompts from "prompts";
+const { prompts } = Prompts;
+export { log, prompts };

package/dist/helpers.d.ts

@@ -0,0 +1,10 @@
+import type { IntroOptions, OutroOptions } from '@stacksjs/types';
+/**
+ * Prints the intro message.
+ */
+export declare function intro(command: string, options?: IntroOptions): number | undefined;
+/**
+ * Prints the outro message.
+ */
+export declare function outro(text: string, options: OutroOptions, error?: Error): void;
+export declare function startAnimation(): import("ora").Ora;

package/dist/helpers.mjs

@@ -0,0 +1,42 @@
+import { ExitCode } from "@stacksjs/types";
+import { version } from "../package.json";
+import { log } from "./console.mjs";
+import { spinner } from "./spinner.mjs";
+import { bgCyan, bold, cyan, dim, green, italic, red } from "./utilities.mjs";
+export function intro(command, options) {
+  console.log();
+  console.log(cyan(bold("Stacks CLI")) + dim(` v${version}`));
+  console.log();
+  log.info(`Preparing to run the  ${bgCyan(italic(bold(` ${command} `)))}  command.`);
+  if (options?.showPerformance === false)
+    return;
+  return performance.now();
+}
+export function outro(text, options, error) {
+  if (options.isError)
+    log.error(error);
+  else
+    log.success(text);
+  if (options.startTime) {
+    let time = performance.now() - options.startTime;
+    if (options.useSeconds) {
+      time = time / 1e3;
+      time = Math.round(time * 100) / 100;
+    }
+    if (options.isError) {
+      log.error(red(`in ${time}${options.useSeconds ? "s" : "ms"}`));
+      process.exit(ExitCode.FatalError);
+    } else {
+      log.success(green(`Done in ${time}${options.useSeconds ? "s" : "ms"}`));
+      process.exit(ExitCode.Success);
+    }
+  }
+}
+export function startAnimation() {
+  const spin = spinner("Running...").start();
+  const pleaseWait = "This may take a little while...";
+  setTimeout(() => {
+    spin.text = italic(pleaseWait);
+  }, 5e3);
+  return spin;
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './actions';
+export * from './command';
+export * from './console';
+export * from './helpers';
+export * from './spinner';
+export * from './utilities';
+export { ExitCode } from '@stacksjs/types';

package/dist/index.mjs

@@ -0,0 +1,7 @@
+export * from "./actions/index.mjs";
+export * from "./command.mjs";
+export * from "./console.mjs";
+export * from "./helpers.mjs";
+export * from "./spinner.mjs";
+export * from "./utilities.mjs";
+export { ExitCode } from "@stacksjs/types";

package/dist/spinner.d.ts

@@ -0,0 +1,2 @@
+import ora from 'ora';
+export declare const spinner: typeof ora;

package/dist/spinner.mjs

@@ -0,0 +1,2 @@
+import ora from "ora";
+export const spinner = ora;

package/dist/utilities.d.ts

@@ -0,0 +1 @@
+export { ansi256Bg, bgBlack, bgBlue, bgCyan, bgGray, bgGreen, bgLightBlue, bgLightCyan, bgLightGray, bgLightGreen, bgLightMagenta, bgLightRed, bgLightYellow, bgMagenta, bgRed, bgWhite, bgYellow, black, blue, bold, cyan, dim, gray, green, hidden, inverse, italic, lightBlue, lightCyan, lightGray, lightGreen, lightMagenta, lightRed, lightYellow, link, magenta, red, reset, strikethrough, underline, white, yellow } from 'kolorist';

package/dist/utilities.mjs

@@ -0,0 +1 @@
+export { ansi256Bg, bgBlack, bgBlue, bgCyan, bgGray, bgGreen, bgLightBlue, bgLightCyan, bgLightGray, bgLightGreen, bgLightMagenta, bgLightRed, bgLightYellow, bgMagenta, bgRed, bgWhite, bgYellow, black, blue, bold, cyan, dim, gray, green, hidden, inverse, italic, lightBlue, lightCyan, lightGray, lightGreen, lightMagenta, lightRed, lightYellow, link, magenta, red, reset, strikethrough, underline, white, yellow } from "kolorist";

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@stacksjs/cli",
+  "type": "module",
+  "version": "0.38.1",
+  "packageManager": "pnpm@7.15.0",
+  "description": "The simple way to create beautiful CLIs.",
+  "author": "Chris Breuer",
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/chrisbbreuer",
+  "homepage": "https://github.com/stacksjs/stacks/tree/main/.stacks/core/cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stacksjs/stacks.git",
+    "directory": "./.stacks/core/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/stacksjs/stacks/issues"
+  },
+  "keywords": [
+    "cli",
+    "commands",
+    "command line interface",
+    "spinners",
+    "utilities",
+    "helpers",
+    "cac",
+    "ora",
+    "consola",
+    "ez-spawn",
+    "stacks"
+  ],
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "contributors": [
+    "Chris Breuer <chris@ow3.org>"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=v18.12.1",
+    "pnpm": ">=7.15.0"
+  },
+  "peerDependencies": {
+    "@antfu/install-pkg": "^0.1.1",
+    "@stacksjs/config": "0.38.1",
+    "@stacksjs/logging": "0.38.1",
+    "@stacksjs/path": "0.38.1",
+    "@stacksjs/types": "0.38.1",
+    "cac": "^6.7.14",
+    "execa": "^6.1.0",
+    "ora": "^6.1.2",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "esno": "^0.16.3",
+    "mkdist": "^0.4.0"
+  },
+  "scripts": {
+    "build": "mkdist -d",
+    "dev": "mkdist -d",
+    "typecheck": "tsc --noEmit"
+  }
+}