Feature: Consistent CLI output (#1597)

Author: jackw

libs/README.md

@@ -0,0 +1,14 @@
+This directory contains internal libraries that share functionality across the packages. They are not npm workspaces, their inclusion in the published packages is due to:
+
+- TSconfig [paths](../tsconfig.base.json).
+- Vitest [aliases](../vitest.config.base.ts) - which are built from the TSconfig paths.
+- Using a bundler to bundle the internal library code into the consuming package.
+
+  ```json
+  {
+    "scripts": {
+      "build": "tsup --config ../../tsup.config.ts",
+      "dev": "tsup --watch ./src --watch '../../libs'"
+    }
+  }
+  ```

libs/output/README.md

@@ -0,0 +1,55 @@
+# Libs/Output
+
+A utility library providing consistent terminal output formatting with support for colors, status icons, and branded prefixes.
+
+## Usage
+
+Instantiate the Output class with the cli name and optionally a version.
+
+### Constructor
+
+```typescript
+import { Output } from '@libs/output';
+
+const output = new Output('MyApp', '1.0.0');
+```
+
+### Methods
+
+#### Message Output
+
+- `success({ title: string, body?: string[], withPrefix?: boolean })` - Displays a success message in green
+- `error({ title: string, body?: string[], link?: string, withPrefix?: boolean })` - Displays an error message in red with optional help link
+- `warning({ title: string, body?: string[],link?: string, withPrefix?: boolean })` - Displays a warning message in yellow
+- `log({ title: string, body?: string[], color?: Colors, withPrefix?: boolean })` - Displays a message with optional color
+
+#### Formatting
+
+- `addHorizontalLine(color: Colors)` - Adds a horizontal separator line in specified color
+- `addNewLine()` - Adds a line break
+- `bulletList(list: string[])` - Formats an array of strings as bullet points
+- `statusList(status: TaskStatus, list: string[])` - Formats an array of strings with status icons (e.g. ✔️ for success)
+
+#### Types
+
+```typescript
+type Colors = 'red' | 'cyan' | 'green' | 'yellow' | 'gray';
+type TaskStatus = 'success' | 'failure' | 'skipped';
+```
+
+### Example Usage
+
+```typescript
+const output = new Output('MyApp', '1.0.0');
+
+output.success({
+  title: 'Build completed',
+  body: output.statusList('success', ['dist folder created', 'types generated']),
+});
+
+output.error({
+  title: 'Build failed',
+  body: ['Unable to resolve dependencies'],
+  link: 'https://example.com/troubleshooting',
+});
+```

libs/output/src/index.mts

@@ -0,0 +1,167 @@
+import chalk from 'chalk';
+import { EOL } from 'os';
+
+type Colors = 'red' | 'cyan' | 'green' | 'yellow' | 'gray';
+
+type TaskStatus = 'success' | 'failure' | 'skipped';
+
+function isCI() {
+  return (
+    (process.env.CI && process.env.CI !== 'false') || // Drone CI plus others
+    process.env.GITHUB_ACTIONS === 'true' // GitHub Actions
+  );
+}
+
+if (isCI()) {
+  // Disable coloring when running in CI environments.
+  chalk.level = 0;
+}
+
+export class Output {
+  private appName: string;
+  private appVersion?: string;
+
+  constructor(name: string, version?: string) {
+    this.appName = name;
+    this.appVersion = version;
+  }
+
+  private write(str: string) {
+    process.stdout.write(str);
+  }
+
+  private get separator() {
+    let separator = '';
+    for (let i = 0; i < process.stdout.columns - 1; i++) {
+      separator += '\u2014';
+    }
+    return separator;
+  }
+
+  addHorizontalLine(color: Colors) {
+    const separator = chalk.dim[color](this.separator);
+    this.write(`${separator}${EOL}`);
+  }
+
+  addNewLine() {
+    this.write(EOL);
+  }
+
+  private writeTitle(color: Colors, title: string, withPrefix = true) {
+    if (withPrefix) {
+      this.write(`${this.addPrefix(color, title)}${EOL}`);
+    } else {
+      this.write(`${title}${EOL}`);
+    }
+  }
+
+  private getStatusIcon(taskStatus: TaskStatus) {
+    switch (taskStatus) {
+      case 'success':
+        return chalk.green('✓');
+      case 'failure':
+        return chalk.red('⨯');
+      case 'skipped':
+        return chalk.yellow('−');
+    }
+  }
+
+  private addPrefix(color: Colors, text: string) {
+    const namePrefix = chalk.reset.inverse.bold[color](` ${this.appName} `);
+    if (!this.appVersion) {
+      return `${namePrefix} ${text}`;
+    }
+    const nameAndVersionPrefix = chalk.reset.inverse.bold[color](` ${this.appName}@${this.appVersion} `);
+    return `${nameAndVersionPrefix} ${text}`;
+  }
+
+  private writeBody(body?: string[]) {
+    if (!body) {
+      return;
+    }
+    this.addNewLine();
+    body.forEach((line) => {
+      this.write(`${line}${EOL}`);
+    });
+  }
+
+  error({
+    title,
+    body,
+    link,
+    withPrefix = true,
+  }: {
+    title: string;
+    body?: string[];
+    link?: string;
+    withPrefix?: boolean;
+  }) {
+    this.addNewLine();
+    this.writeTitle('red', chalk.red.bold(title), withPrefix);
+    this.writeBody(body);
+
+    if (link) {
+      this.addNewLine();
+      this.write(`${chalk.gray('Learn more about this error: ')}
+  ${chalk.cyan(link)}`);
+    }
+    this.addNewLine();
+  }
+
+  warning({
+    title,
+    body,
+    link,
+    withPrefix = true,
+  }: {
+    title: string;
+    body?: string[];
+    link?: string;
+    withPrefix?: boolean;
+  }) {
+    this.addNewLine();
+    this.writeTitle('yellow', chalk.yellow.bold(title), withPrefix);
+    this.writeBody(body);
+
+    if (link) {
+      this.addNewLine();
+      this.write(`${chalk.gray('Learn more about this warning: ')}
+  ${this.formatUrl(link)}`);
+    }
+    this.addNewLine();
+  }
+
+  success({ title, body, withPrefix = true }: { title: string; body?: string[]; withPrefix?: boolean }) {
+    this.addNewLine();
+    this.writeTitle('green', chalk.green.bold(title), withPrefix);
+    this.writeBody(body);
+    this.addNewLine();
+  }
+
+  log({ title, body, withPrefix = true }: { title: string; body?: string[]; withPrefix?: boolean }) {
+    this.addNewLine();
+    this.writeTitle('cyan', chalk.cyan.bold(title), withPrefix);
+    this.writeBody(body);
+    this.addNewLine();
+  }
+
+  bulletList(list: string[]) {
+    return list.map((item) => {
+      return ` • ${item}`;
+    });
+  }
+
+  formatCode(code: string) {
+    return chalk.italic.cyan(code);
+  }
+
+  formatUrl(url: string) {
+    return chalk.reset.blue.underline(url);
+  }
+
+  statusList(status: TaskStatus, list: string[]) {
+    return list.map((item) => {
+      return ` ${this.getStatusIcon(status)} ${item}`;
+    });
+  }
+}

libs/version/README.md

@@ -0,0 +1,14 @@
+# Libs/Version
+
+A utility library that provides a simple way to retrieve the version of your application from its package.json file.
+
+## Usage
+
+```ts
+import { getVersion } from '@libs/version';
+
+const version = getVersion();
+console.log(version); // e.g. "1.0.0"
+```
+
+If no package.json file was found or the package.json file does not have a version property it will throw an error.

libs/version/src/index.mts

@@ -0,0 +1,18 @@
+import { findUpSync } from 'find-up';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+export function getVersion(): string {
+  const packageJsonPath = findUpSync('package.json', { cwd: __dirname });
+  if (!packageJsonPath) {
+    throw `Could not find package.json`;
+  }
+  const pkg = readFileSync(packageJsonPath, 'utf8');
+  const { version } = JSON.parse(pkg);
+  if (!version) {
+    throw `Could not find the version of create-plugin`;
+  }
+  return version;
+}