@powerhousedao/ph-cli 0.41.3 → 2.5.0-dev.0

package/README.md

@@ -1,18 +1,72 @@
 # Powerhouse CLI (ph-cli)
 
-A command-line interface tool for Powerhouse DAO that helps you manage and interact with Powerhouse packages and services.
+[![npm version](https://img.shields.io/npm/v/ph-cli.svg)](https://www.npmjs.com/package/ph-cli)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+
+A powerful command-line interface tool for Powerhouse DAO that streamlines the development and management of Powerhouse packages and services. The CLI provides a unified interface for common development tasks, package management, and service operations.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Commands](#commands)
+  - [Connect](#ph-connect)
+  - [Generate](#ph-generate)
+  - [Install](#ph-install)
+  - [Uninstall](#ph-uninstall)
+  - [List](#ph-list)
+  - [Inspect](#ph-inspect)
+  - [Service](#ph-service)
+  - [Version](#ph-version)
+  - [Help](#ph-help)
+- [Configuration](#configuration)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+- 🚀 Fast and efficient package management
+- 🔧 Powerful code generation capabilities
+- 🌐 Connect Studio development environment
+- 📦 Workspace-aware package operations
+- 🔍 Package inspection and dependency management
+- 🛠 Service management and monitoring
+- 📝 Comprehensive documentation and help system
 
 ## Installation
 
 ```bash
-npm install ph-cli
+# Install globally
+npm install -g ph-cli
+
+# Install as a dev dependency
+npm install --save-dev ph-cli
+```
+
+## Quick Start
+
+```bash
+# Initialize a new Powerhouse project
+ph init
+
+# Start the development environment
+ph connect
+
+# Install required dependencies
+ph install @powerhousedao/core
+
+# Generate code from models
+ph generate --interactive
 ```
 
-## Available Commands
+## Commands
 
 ### `ph connect`
 
-Starts Connect Studio, a development environment for Powerhouse.
+Starts Connect Studio, a development environment for Powerhouse. This command launches a local development server with hot-reloading and debugging capabilities.
 
 #### Options:
 - `-p, --port <port>`: Port to run the server on (default: 3000)
@@ -21,6 +75,7 @@ Starts Connect Studio, a development environment for Powerhouse.
 - `--open`: Open the browser automatically
 - `--config-file <configFile>`: Path to the powerhouse.config.js file
 
+#### Examples:
 ```bash
 # Start Connect Studio on default port (3000)
 ph connect
@@ -40,7 +95,7 @@ ph connect --config-file ./my-config.js
 
 ### `ph generate`
 
-Generate code from document models with various options.
+Generate code from document models with various options. This command supports multiple generation types including editors, processors, subgraphs, and import scripts.
 
 #### Options:
 - `-i, --interactive`: Run the command in interactive mode
@@ -58,6 +113,7 @@ Generate code from document models with various options.
 - `-w, --watch`: Watch the generated code
 - `-d, --drive-editor <name>`: Generate a drive editor with the specified name
 
+#### Examples:
 ```bash
 # Generate code from a specific file
 ph generate path/to/model.json
@@ -86,7 +142,7 @@ ph generate --watch
 
 ### `ph install` (or `ph add`, `ph i`)
 
-Install Powerhouse dependencies.
+Install Powerhouse dependencies with support for global and workspace-specific installations.
 
 #### Options:
 - `-g, --global`: Install the dependency globally
@@ -94,6 +150,7 @@ Install Powerhouse dependencies.
 - `-w, --workspace`: Install the dependency in the workspace (use this option for monorepos)
 - `--package-manager <packageManager>`: Force package manager to use
 
+#### Examples:
 ```bash
 # Install a package
 ph install @powerhousedao/package-name
@@ -110,7 +167,7 @@ ph install @powerhousedao/package1 @powerhousedao/package2
 
 ### `ph uninstall` (or `ph remove`)
 
-Remove Powerhouse dependencies.
+Remove Powerhouse dependencies from your project.
 
 #### Options:
 - `-g, --global`: Remove the dependency globally
@@ -118,6 +175,7 @@ Remove Powerhouse dependencies.
 - `-w, --workspace`: Remove the dependency in the workspace (use this option for monorepos)
 - `--package-manager <packageManager>`: Force package manager to use
 
+#### Examples:
 ```bash
 # Remove a package
 ph uninstall @powerhousedao/package-name
@@ -131,11 +189,12 @@ ph uninstall -w @powerhousedao/package-name
 
 ### `ph list` (or `ph l`)
 
-List all installed Powerhouse packages in your project.
+List all installed Powerhouse packages in your project with detailed information.
 
 #### Options:
 - `--debug`: Show additional logs
 
+#### Examples:
 ```bash
 # List packages
 ph list
@@ -146,11 +205,12 @@ ph list --debug
 
 ### `ph inspect` (or `ph is`)
 
-Inspect a specific package.
+Inspect a specific package for detailed information about its dependencies, configuration, and usage.
 
 #### Options:
 - `--debug`: Show additional logs
 
+#### Examples:
 ```bash
 # Inspect a package
 ph inspect @powerhousedao/package-name
@@ -161,12 +221,13 @@ ph inspect --debug @powerhousedao/package-name
 
 ### `ph service`
 
-Manage Powerhouse services.
+Manage Powerhouse services with various operations.
 
 #### Options:
 - `action`: The action to perform (default: "list")
 - `service`: The service to manage (default: "all")
 
+#### Examples:
 ```bash
 # List all services
 ph service list
@@ -177,19 +238,21 @@ ph service list service-name
 
 ### `ph version` (or `ph v`)
 
-Display the current version of the PH CLI.
+Display the current version of the PH CLI and related information.
 
 #### Options:
 - `--debug`: Show additional logs
 
+#### Examples:
 ```bash
 ph version
 ```
 
 ### `ph help`
 
-Display help information about the CLI and its commands.
+Display comprehensive help information about the CLI and its commands.
 
+#### Examples:
 ```bash
 # Show general help
 ph help
@@ -198,17 +261,58 @@ ph help
 ph help <command>
 ```
 
-## Global Options
+## Configuration
+
+The CLI can be configured using a `powerhouse.config.js` file in your project root. Here's an example configuration:
+
+```javascript
+module.exports = {
+  port: 3000,
+  host: false,
+  https: false,
+  packageManager: 'npm',
+  workspace: {
+    enabled: true,
+    root: './packages'
+  }
+};
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Command not found**
+   - Ensure ph-cli is installed globally or locally
+   - Check your PATH environment variable
+
+2. **Permission errors**
+   - Use sudo for global installations
+   - Check directory permissions
 
-Most commands support the following global options:
+3. **Package installation failures**
+   - Clear npm cache: `npm cache clean --force`
+   - Check network connectivity
+   - Verify package name and version
 
-- `--debug`: Show additional debug logs
-- `--package-manager <manager>`: Force the use of a specific package manager
+### Debug Mode
+
+Most commands support a `--debug` flag for additional logging:
+
+```bash
+ph install --debug @powerhousedao/package-name
+```
 
 ## Contributing
 
-Please refer to the project's contribution guidelines for details on our code of conduct and the process for submitting pull requests.
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
+
+- Code of Conduct
+- Development Process
+- Pull Request Process
+- Style Guide
+- Testing Requirements
 
 ## License
 
-This project is licensed under the terms specified in the LICENSE file.
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/dist/package.json

@@ -1,9 +1,13 @@
 {
     "name": "@powerhousedao/ph-cli",
-    "version": "0.41.3",
+    "version": "2.5.0-dev.0",
     "description": "",
     "license": "AGPL-3.0-only",
     "type": "module",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/powerhouse-inc/powerhouse"
+    },
     "publishConfig": {
         "access": "public"
     },
@@ -14,6 +18,11 @@
         "dist"
     ],
     "scripts": {
+        "generate-commands-md": "tsx scripts/generate-commands-md.ts",
+        "generate-version": "tsx scripts/generate-version.ts",
+        "prebuild": "npm run clean && npm run generate-commands-md && npm run generate-version",
+        "postbuild": "npm run copy-scripts",
+        "copy-scripts": "copyfiles scripts/* dist/",
         "build": "tsc --build",
         "dev": "concurrently -P 'pnpm -w run build:tsc --watch' 'nodemon --watch \"../..\" -e ts,tsx,js,json dist/src/cli.js -- {@}' --",
         "prepublishOnly": "npm run build",
@@ -27,7 +36,9 @@
     "keywords": [],
     "author": "",
     "devDependencies": {
+        "@types/node": "^22.15.17",
         "concurrently": "^9.1.2",
+        "copyfiles": "^2.4.1",
         "nodemon": "^3.1.9",
         "vitest": "^3.1.2"
     },
@@ -37,6 +48,7 @@
         "@powerhousedao/config": "workspace:*",
         "@powerhousedao/connect": "workspace:*",
         "@powerhousedao/reactor-local": "workspace:*",
+        "@powerhousedao/switchboard": "workspace:*",
         "colorette": "^2.0.20",
         "commander": "^12.1.0",
         "document-drive": "workspace:*",

package/dist/scripts/generate-commands-md.ts

@@ -0,0 +1,84 @@
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+
+/**
+ * Generate COMMANDS.md file from the help texts in help.ts
+ */
+async function generateCommandsMd() {
+  try {
+    // Define paths for ES modules
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = path.dirname(__filename);
+    const rootDir = path.resolve(__dirname, "..");
+    const helpFilePath = path.join(rootDir, "src", "help.ts");
+    const outputPath = path.join(rootDir, "COMMANDS.md");
+
+    // Read the help.ts file
+    const helpFileContent = fs.readFileSync(helpFilePath, "utf8");
+
+    // Extract all help text constants using regex
+    const helpTextRegex = /export const (\w+)Help = `([\s\S]+?)`;/g;
+    const commands: { name: string; content: string }[] = [];
+
+    let match;
+    while ((match = helpTextRegex.exec(helpFileContent)) !== null) {
+      const commandName = match[1];
+      const helpContent = match[2];
+      commands.push({ name: commandName, content: helpContent });
+    }
+
+    // Sort commands alphabetically
+    commands.sort((a, b) => a.name.localeCompare(b.name));
+
+    // Generate the markdown content
+    let markdown = "# Powerhouse CLI Commands\n\n";
+    markdown +=
+      "This document provides detailed information about the available commands in the Powerhouse CLI.\n\n";
+    markdown += "## Table of Contents\n\n";
+
+    // Add table of contents
+    commands.forEach((command) => {
+      const displayName = formatCommandName(command.name);
+      const anchor = displayName.toLowerCase().replace(/\s+/g, "-");
+      markdown += `- [${displayName}](#${anchor})\n`;
+    });
+
+    markdown += "\n";
+
+    // Add command details
+    commands.forEach((command) => {
+      const displayName = formatCommandName(command.name);
+      markdown += `## ${displayName}\n\n`;
+      markdown += "```\n";
+      markdown += command.content.trim();
+      markdown += "\n```\n\n";
+    });
+
+    // Add footer
+    markdown += "---\n\n";
+    markdown +=
+      "*This document was automatically generated from the help text in the codebase.*\n";
+
+    // Write to COMMANDS.md
+    fs.writeFileSync(outputPath, markdown);
+
+    console.log(`✅ COMMANDS.md has been generated at ${outputPath}`);
+  } catch (error) {
+    console.error("Failed to generate COMMANDS.md:", error);
+    process.exit(1);
+  }
+}
+
+/**
+ * Format command name for display (e.g., "setupGlobals" -> "Setup Globals")
+ */
+function formatCommandName(commandName: string): string {
+  // Convert camelCase to separate words with spaces
+  const name = commandName.replace(/([A-Z])/g, " $1").trim();
+  // Capitalize first letter and convert the rest to lowercase
+  return name.charAt(0).toUpperCase() + name.slice(1);
+}
+
+// Run the script
+generateCommandsMd();

package/dist/scripts/generate-version.ts

@@ -0,0 +1,22 @@
+import { readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import { fileURLToPath } from "url";
+
+interface PackageJson {
+  version: string;
+}
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+
+// Read package.json
+const packageJson = JSON.parse(
+  readFileSync(join(__dirname, "../package.json"), "utf-8"),
+) as PackageJson;
+
+// Generate version.ts content
+const versionFileContent = `// This file is auto-generated. DO NOT EDIT.
+export const version = "${packageJson.version}";
+`;
+
+// Write version.ts
+writeFileSync(join(__dirname, "../src/version.ts"), versionFileContent);

package/dist/scripts/manage-environment

@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+
+# =============================================================================
+# Configuration
+# =============================================================================
+PROJECT_NAME=${1:-"global"}
+ACTION=${2:-"status"}
+
+# =============================================================================
+# OS Detection and Windows Handling
+# =============================================================================
+if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then
+    if [ -f "$0.ps1" ]; then
+        powershell -ExecutionPolicy Bypass -File "$0.ps1" -PROJECT_NAME "$PROJECT_NAME" -ACTION "$ACTION"
+    else
+        echo "Error: Windows management script (manage-environment.ps1) not found"
+        exit 1
+    fi
+else
+    # =============================================================================
+    # Service Management
+    # =============================================================================
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "  Managing project: $PROJECT_NAME"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+    # Function to check if service is properly set up
+    check_setup() {
+        local project_name=$1
+        local error=0
+
+        # Check if .env file exists
+        if [ ! -f ".env" ]; then
+            echo "Error: .env file not found in project directory"
+            error=1
+        fi
+
+        # Check if Nginx configuration exists
+        if [ ! -f "/etc/nginx/sites-available/$project_name" ]; then
+            echo "Error: Nginx configuration not found"
+            error=1
+        fi
+
+        # Check if database is configured
+        if ! grep -q "DATABASE_URL" ".env"; then
+            echo "Error: Database configuration not found in .env file"
+            error=1
+        fi
+
+        if [ $error -eq 1 ]; then
+            echo "Please run 'ph setup-environment' first to set up the service"
+            exit 1
+        fi
+    }
+
+    # Function to enable/disable Nginx site
+    manage_nginx_site() {
+        local action=$1
+        local site_path="/etc/nginx/sites-available/$PROJECT_NAME"
+        local enabled_path="/etc/nginx/sites-enabled/$PROJECT_NAME"
+        
+        if [ ! -f "$site_path" ]; then
+            echo "Error: Nginx site configuration for $PROJECT_NAME not found"
+            return 1
+        fi
+        
+        case "$action" in
+            "enable")
+                if [ ! -L "$enabled_path" ]; then
+                    sudo ln -sf "$site_path" "$enabled_path"
+                    sudo nginx -t && sudo nginx -s reload
+                fi
+                ;;
+            "disable")
+                if [ -L "$enabled_path" ]; then
+                    sudo rm -f "$enabled_path"
+                    sudo nginx -t && sudo nginx -s reload
+                fi
+                ;;
+        esac
+    }
+
+    case "$ACTION" in
+        "start")
+            check_setup "$PROJECT_NAME"
+            echo "Starting services..."
+            # Build Connect
+            echo "Building Connect..."
+            ph connect build
+            sudo cp -r .ph/connect-build/dist /var/www/html/${PROJECT_NAME}
+            
+            # Enable Nginx site
+            manage_nginx_site "enable"
+            
+            # Start Switchboard via PM2
+            if ! pm2 list | grep -q "switchboard_${PROJECT_NAME}"; then
+                cd $PROJECT_NAME
+                pm2 start "pnpm switchboard" --name "switchboard_${PROJECT_NAME}"
+                pm2 save
+            else
+                pm2 start "switchboard_${PROJECT_NAME}"
+            fi
+            ;;
+            
+        "stop")
+            check_setup "$PROJECT_NAME"
+            echo "Stopping services..."
+            # Stop Switchboard via PM2
+            if pm2 list | grep -q "switchboard_${PROJECT_NAME}"; then
+                pm2 stop "switchboard_${PROJECT_NAME}"
+            fi
+            
+            # Disable Nginx site
+            manage_nginx_site "disable"
+            ;;
+            
+        "restart")
+            check_setup "$PROJECT_NAME"
+            echo "Restarting services..."
+            # Build Connect
+            echo "Building Connect..."
+            ph connect build
+            sudo cp -r .ph/connect-build/dist /var/www/html/${PROJECT_NAME}
+            
+            # Restart Nginx site
+            manage_nginx_site "disable"
+            manage_nginx_site "enable"
+            
+            # Restart Switchboard via PM2
+            if pm2 list | grep -q "switchboard_${PROJECT_NAME}"; then
+                pm2 restart "switchboard_${PROJECT_NAME}"
+            else
+                cd $PROJECT_NAME
+                pm2 start "pnpm switchboard" --name "switchboard_${PROJECT_NAME}"
+                pm2 save
+            fi
+            ;;
+            
+        "status")
+            check_setup "$PROJECT_NAME"
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            echo "  Service Status for $PROJECT_NAME"
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            
+            # Create table header
+            printf "%-15s %-10s %-15s %-10s %-10s\n" "Service" "Status" "Memory" "Uptime" "Health"
+            echo "────────────────────────────────────────────────────────────────────"
+            
+            # Check Connect status
+            connect_status="Disabled"
+            connect_health="❌"
+            connect_memory="N/A"
+            connect_uptime="N/A"
+            if [ -L "/etc/nginx/sites-enabled/$PROJECT_NAME" ]; then
+                connect_status="Enabled"
+                # Check if Connect is reachable
+                if curl -s -f "http://localhost/$PROJECT_NAME" > /dev/null; then
+                    connect_health="✅"
+                fi
+                # Get Nginx memory usage for the site
+                nginx_pid=$(pgrep -f "nginx.*$PROJECT_NAME" | head -n 1)
+                if [ -n "$nginx_pid" ]; then
+                    connect_memory=$(ps -o rss= -p "$nginx_pid" 2>/dev/null | awk '{printf "%.1fmb", $1/1024}')
+                    connect_uptime=$(ps -o etime= -p "$nginx_pid" 2>/dev/null)
+                fi
+            fi
+            printf "%-15s %-10s %-15s %-10s %-10s\n" "Connect" "$connect_status" "$connect_memory" "$connect_uptime" "$connect_health"
+            
+            # Check Switchboard status
+            switchboard_info=$(pm2 list | grep "switchboard_${PROJECT_NAME}")
+            if [ -n "$switchboard_info" ]; then
+                switchboard_status="Enabled"
+                switchboard_memory=$(echo "$switchboard_info" | awk '{print $12}')
+                switchboard_uptime=$(echo "$switchboard_info" | awk '{print $7}')
+                switchboard_health="✅"
+                printf "%-15s %-10s %-15s %-10s %-10s\n" "Switchboard" "$switchboard_status" "$switchboard_memory" "$switchboard_uptime" "$switchboard_health"
+            else
+                printf "%-15s %-10s %-15s %-10s %-10s\n" "Switchboard" "Disabled" "N/A" "N/A" "❌"
+            fi
+            echo "────────────────────────────────────────────────────────────────────"
+            ;;
+            
+        *)
+            echo "Usage: $0 [project_name] {start|stop|restart|status}"
+            echo "Default project_name: global"
+            echo "Default action: status"
+            exit 1
+            ;;
+    esac
+fi