Houston-cli NPM

Houston CLI - README

Overview

Houston CLI is a command-line tool built to streamline the creation of Vue components and associated files within the UXE Studio project. The purpose of Houston is to make development smoother and more standardized by generating the required boilerplate files and organizing them properly within the project structure. It is specifically tailored for the UXE Studio project and provides a seamless experience by knowing exactly where and how to place each generated file.

Houston is built with Node.js, using tools such as Commander for command-line interface options and Inquirer for interactive prompts. This tool must be run from the root of the UXE Studio project, ensuring consistent project structure.

Features

Create Vue Component Files: Generates .vue files in the correct project structure.
Create Meta Files: Creates .meta.js files alongside Vue components with relevant project information.
Generate Settings for Components: Adds settings logic and a state.js file for components requiring a settings button.
Generate Placeholder Images: Automatically creates light and dark placeholder images for components.
Search for Projects: Locate existing projects by name using the find command.
Revert Changes: Use the clean command to revert all changes made by Houston.
Sync Dialtone Components: Fetches the latest Dialtone UI components and categorizes them for easy integration.
Create Prototypes: Allows users to insert pre-built UI components into existing Vue files.
Testing Mode: Allows for testing Houston's functionality in a local environment without affecting UXE Studio, providing a safe space for development.

Prerequisites

Node.js and npm installed on your system.

Installation Steps

To install Houston globally and make it available as a command across your system, follow these steps:

Clone the Repository

git clone git@github.com:dialpad/houston-cli.git
cd houston-cli

Install Dependencies
```
npm install
```
Make the Script Executable
```
chmod +x bin/houston.js
```
Install Houston Globally
```
npm install -g houston-cli
```

Usage

Once installed, you can use the houston command to generate components directly in the UXE Studio project. Houston knows the correct directory structure and where files need to go, so you just need to run the command from the root of the UXE Studio project.

Commands

1. Launch a New Project

houston launch

Houston will guide you through the following steps:

Ask for the name of the component file (e.g., NewProject).
Ask for the project name (e.g., New Project).
Ask for the status of the project (Complete, In Progress, Experiment).
Confirm if the component has a settings button (yes or no).
If the settings button is enabled, Houston will generate the state.js file and include settings logic.
Ask if the project requires an environment. If yes, choose one of the following:
- Reference App
- Web App
- Meetings App
Collect optional information such as team members, descriptions, and links (e.g., Figma, prototype).

2. Create a Prototype

houston launch

Select Prototype instead of Project.
Choose whether you want to add components to an existing project or create a new one.
If selecting an existing project, Houston will locate the corresponding Vue file.
Select a component category (e.g., Layout Components, Buttons, Forms, etc.).
Select a specific component to add.
Houston will insert the component inside the <template> section of the Vue file and ensure the proper import statement is added to the <script> section.
You can add multiple components before finalizing the changes.

3. Sync Dialtone Components

houston dialtone sync

This command fetches the latest component definitions from @dialpad/dialtone.
Components are categorized into groups such as Layout, Buttons, Forms, etc.
The output is saved to src/data/dialtone-components.json for reference by Houston when inserting components into Vue files.

4. Enable/Disable Testing Mode

Houston provides a testing mode to create a local environment without affecting the main UXE Studio files. The testing mode creates a testing/ directory inside Houston, mirroring the UXE Studio structure, allowing you to safely test component creation, prototype integration, and other Houston features without modifying the actual UXE Studio project.

Enable Testing Mode:
```
houston testing-mode -on
```
- This command sets up a testing environment by creating the necessary folder structure within Houston.
Disable Testing Mode:
```
houston testing-mode -off
```
- This command removes the testing environment if it is no longer needed.

To use the testing mode, simply navigate into the testing/ folder. Houston will automatically detect that it's inside a test environment and function accordingly.

5. Find Existing Projects

houston find --p <searchTerm>

6. Revert Changes

houston clean

File Generation Details

Vue Component File (.vue): Houston will create a Vue component file in src/components/library/ with the specified name.
Meta File (.meta.js): Houston will also create a meta information file alongside the component.
Settings File (state.js): If you specify that the component has a settings button, Houston will create an additional folder for settings, including a state.js file for reactive data.
Styles File (.less): A .less file is created in src/styles/components/ and automatically added to components.less.
Placeholder Images: Light and dark placeholder images are generated and saved in public/components/light/ and public/components/dark/.

Uninstallation

npm uninstall -g houston-cli

Future Improvements

Additional Command Types: Expand beyond just Project and Prototype to support other types of components or utilities.
Error Handling Enhancements: Improve feedback if files or directories cannot be created for some reason.
Environment Detection: Detect IDE terminals (e.g., WebStorm, VS Code) and open files in the corresponding editor.