fa-mcp-sdk 0.2.38 → 0.2.76

package/cli-template/deploy/srv.sh

@@ -0,0 +1,359 @@
+#!/usr/bin/bash
+
+# srv.sh - Unified systemd service management script
+# Consolidates functionality from deploy/systemd-service/ scripts
+# Can be run from project root or from deploy/ directory
+
+# Colors for output
+c="\e[1;36m"; lc="\e[0;36m";
+g="\e[1;32m"; lg="\e[0;32m";
+m="\e[1;35m"; lm="\e[0;35m";
+r="\e[1;31m"; lr="\e[0;31m";
+y="\e[1;33m"; ly="\e[0;33m";
+c0='\033[0;0m'
+
+# Script configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"  # Parent directory (project root)
+SERVICE_NAME=""
+NODE_VERSION=""
+PORT=""
+COMMAND=""
+
+# Function to show usage
+show_usage() {
+    echo "Usage:"
+    echo "  $0 i|install [-n <service_name>] [-v <node_version>]"
+    echo "  $0 d|delete  [-n <service_name>] [-p <port>]"
+    echo "  $0 r|reinstall [-n <service_name>] [-p <port>] [-v <node_version>]"
+    echo ""
+    echo "Commands:"
+    echo "  i, install    - Install and start systemd service"
+    echo "  d, delete     - Stop and remove systemd service"
+    echo "  r, reinstall  - Reinstall service (delete + install)"
+    echo ""
+    echo "Options:"
+    echo "  -n <name>     - Alternative service name (default: from package.json)"
+    echo "  -v <version>  - Node.js version (default: auto-detected)"
+    echo "  -p <port>     - Port number for service cleanup (default: auto-detected)"
+    echo ""
+    echo "Working directories:"
+    echo "  Script location: $SCRIPT_DIR"
+    echo "  Project root: $PROJECT_ROOT"
+}
+
+# Function to check if service exists
+service_exists() {
+    local n=$1
+    if [[ $(systemctl list-units --all -t service --full --no-legend "$n.service" | sed 's/●//g' | sed 's/^\s*//g' | cut -f1 -d' ') == $n.service ]]; then
+        return 0
+    else
+        return 1
+    fi
+}
+
+# Function to detect Node.js version
+detect_node_version() {
+    local version=""
+
+    # 1. Use provided version parameter
+    if [ -n "$NODE_VERSION" ]; then
+        version="$NODE_VERSION"
+        echo -e "$c**** Using provided Node.js version: $g$version$c ****$c0" >&2
+    # 2. Try to find version in .envrc (in project root)
+    elif [ -f "$PROJECT_ROOT/.envrc" ]; then
+        version=$(grep -E "^\s*nvm\s+use\s+" "$PROJECT_ROOT/.envrc" | sed -E 's/^\s*nvm\s+use\s+([0-9]+\.[0-9]+\.[0-9]+).*/\1/' | head -n1)
+        if [ -n "$version" ]; then
+            echo -e "$c**** Found Node.js version in .envrc: $g$version$c ****$c0" >&2
+        fi
+    fi
+
+    # 3. Fallback to current node version
+    if [ -z "$version" ]; then
+        version=$(node -v 2>/dev/null | sed 's/^v//')
+        if [ -n "$version" ]; then
+            echo -e "$c**** Using current Node.js version: $g$version$c ****$c0" >&2
+        else
+            echo -e "$r**** Error: Could not detect Node.js version ****$c0" >&2
+            exit 1
+        fi
+    fi
+
+    echo "$version"
+}
+
+# Function to find Node.js binary path
+find_node_path() {
+    local version="$1"
+    local node_path=""
+
+    # Try NVM path first
+    local nvm_path="$HOME/.nvm/versions/node/v$version/bin/node"
+    if [ -f "$nvm_path" ]; then
+        node_path="$nvm_path"
+        echo -e "$c**** Found Node.js at NVM path: $g$node_path$c ****$c0" >&2
+    else
+        # Try system node
+        node_path=$(which node 2>/dev/null)
+        if [ -n "$node_path" ]; then
+            local current_version=$(node -v 2>/dev/null | sed 's/^v//')
+            if [ "$current_version" = "$version" ]; then
+                echo -e "$c**** Found Node.js at system path: $g$node_path$c ****$c0" >&2
+            else
+                echo -e "$y**** Warning: System Node.js version ($current_version) differs from target ($version) ****$c0" >&2
+                echo -e "$c**** Using system path anyway: $g$node_path$c ****$c0" >&2
+            fi
+        else
+            echo -e "$r**** Error: Could not find Node.js binary ****$c0" >&2
+            exit 1
+        fi
+    fi
+
+    echo "$node_path"
+}
+
+# Function to parse package.json
+parse_package_json() {
+    local field="$1"
+    local package_file="$PROJECT_ROOT/package.json"
+
+    if [ ! -f "$package_file" ]; then
+        echo -e "$r**** Error: package.json not found at $package_file ****$c0" >&2
+        exit 1
+    fi
+
+    # Simple JSON parsing using node (execute from project root for proper require resolution)
+    local value=$(cd "$PROJECT_ROOT" && node -e "
+        try {
+            const pkg = require('./package.json');
+            console.log(pkg.$field || '');
+        } catch(e) {
+            process.exit(1);
+        }
+    " 2>/dev/null)
+
+    if [ $? -ne 0 ] || [ -z "$value" ]; then
+        echo -e "$r**** Error: Could not parse $field from package.json ****$c0" >&2
+        exit 1
+    fi
+
+    echo "$value"
+}
+
+# Function to get service name
+get_service_name() {
+    if [ -n "$SERVICE_NAME" ]; then
+        echo "$SERVICE_NAME"
+    else
+        parse_package_json "name"
+    fi
+}
+
+# Function to detect port from config
+detect_port() {
+    local port=""
+
+    if [ -n "$PORT" ]; then
+        port="$PORT"
+    else
+        # Try to get port from config using node (execute from project root for proper require resolution)
+        port=$(cd "$PROJECT_ROOT" && node -e 'try{const c=require("config");console.log(c.webServer?.port);}catch(e){import("config").then(c=>console.log(c.webServer?.port)).catch(()=>{});}' 2>/dev/null | grep -oE "[0-9]{2,5}" | head -n1)
+
+        if [ -z "$port" ]; then
+            echo -e "$r**** Error: Could not detect port from config ****$c0" >&2
+            exit 1
+        fi
+    fi
+
+    echo "$port"
+}
+
+# Function to generate systemd unit file
+generate_unit_file() {
+    local service_name="$1"
+    local node_path="$2"
+    local main_file="$3"
+    local working_dir="$PROJECT_ROOT"  # Always use project root as working directory
+    local serviceFile="/etc/systemd/system/${service_name}.service"
+    cat > "$serviceFile" << EOF
+[Unit]
+Description=$service_name
+After=network.target
+# https://www.freedesktop.org/software/systemd/man/latest/systemd.unit.html#StartLimitIntervalSec=interval
+StartLimitIntervalSec=0
+
+[Service]
+User=root
+WorkingDirectory=$working_dir
+EnvironmentFile=$working_dir/.env
+ExecStart=$node_path $main_file
+Restart=always
+RestartSec=3
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+    echo -e "$c**** Generated unit file for $g$service_name$c ****$c0" >&2
+    echo -e "$lc   WorkingDirectory: $g$working_dir$c0" >&2
+    echo -e "$lc   ExecStart: $g$node_path $main_file$c0" >&2
+    echo -e "$lc   View Service file: ${g}cat $serviceFile$c0" >&2
+}
+
+# Function to install service
+install_service() {
+    echo -e "$c**** Installing service ****$c0"
+
+    # Detect Node.js version and path
+    local node_version=$(detect_node_version)
+    local node_path=$(find_node_path "$node_version")
+
+    # Get main entry point and service name
+    local main_file=$(parse_package_json "main")
+    local service_name=$(get_service_name)
+
+    echo -e "$c**** Service configuration ****$c0"
+    echo -e "$lc   Service name: $g$service_name$c0"
+    echo -e "$lc   Node.js version: $g$node_version$c0"
+    echo -e "$lc   Node.js path: $g$node_path$c0"
+    echo -e "$lc   Main file: $g$main_file$c0"
+    echo -e "$lc   Project root: $g$PROJECT_ROOT$c0"
+
+    # Check if service already exists
+    if service_exists "$service_name"; then
+        echo -e "$c**** Service $g$service_name$c already installed ****$c0"
+        return 0
+    fi
+
+    # Generate and install unit file
+    generate_unit_file "$service_name" "$node_path" "$main_file"
+
+    # Reload systemd and enable service
+    systemctl daemon-reload
+    systemctl enable --now "$service_name"
+
+    if [ $? -eq 0 ]; then
+        echo -e "$c**** Service $g$service_name$c installed and started ****$c0"
+        echo ""
+        echo -e "${m}View status: ${y}systemctl -l status $service_name$c0"
+        echo -e "${m}View logs: ${y}journalctl -o cat -xefu $service_name$c0"
+    else
+        echo -e "$r**** Error: Failed to install service $service_name ****$c0"
+        exit 1
+    fi
+}
+
+# Function to delete service
+delete_service() {
+    local service_name=$(get_service_name)
+    local port=$(detect_port)
+
+    echo -e "$c**** Removing service $g$service_name$c listening on port $g$port$c ****$c0"
+
+    if ! service_exists "$service_name"; then
+        echo -e "$c**** Service $g$service_name$c not found ****$c0"
+        return 0
+    fi
+
+    # Stop and disable service
+    systemctl stop "$service_name"
+    systemctl disable "$service_name"
+
+    # Remove unit file
+    rm -f "/etc/systemd/system/$service_name.service"
+
+    # Kill any remaining process on the port
+    local pid=$(lsof -i tcp:$port 2>/dev/null | grep $port | awk '{print $2}' | head -1)
+    if [ -n "$pid" ]; then
+        echo -e "$c**** Killing process $g$pid$c on port $g$port$c ****$c0"
+        kill -9 "$pid"
+    fi
+
+    # Reload systemd
+    systemctl daemon-reload
+
+    echo -e "$c**** Service $g$service_name$c removed ****$c0"
+}
+
+# Function to reinstall service
+reinstall_service() {
+    echo -e "$c**** Reinstalling service ****$c0"
+
+    # Delete existing service
+    delete_service
+
+    # Install service
+    install_service
+
+    local service_name=$(get_service_name)
+    echo -e "$c**** Service $g$service_name$c reinstalled ****$c0"
+
+    # Show status and logs
+    systemctl status "$service_name"
+    echo ""
+    echo -e "${m}Following logs (Ctrl+C to exit): ${y}journalctl -o cat -xefu $service_name$c0"
+    journalctl -o cat -xefu "$service_name"
+}
+
+# Parse command line arguments
+if [ $# -eq 0 ]; then
+    show_usage
+    exit 1
+fi
+
+# Parse command
+case "$1" in
+    i|install)
+        COMMAND="install"
+        shift
+        ;;
+    d|delete)
+        COMMAND="delete"
+        shift
+        ;;
+    r|reinstall)
+        COMMAND="reinstall"
+        shift
+        ;;
+    *)
+        echo -e "$r**** Error: Unknown command '$1' ****$c0"
+        show_usage
+        exit 1
+        ;;
+esac
+
+# Parse options
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -n)
+            SERVICE_NAME="$2"
+            shift 2
+            ;;
+        -v)
+            NODE_VERSION="$2"
+            shift 2
+            ;;
+        -p)
+            PORT="$2"
+            shift 2
+            ;;
+        *)
+            echo -e "$r**** Error: Unknown option '$1' ****$c0"
+            show_usage
+            exit 1
+            ;;
+    esac
+done
+
+# Execute command
+case "$COMMAND" in
+    install)
+        install_service
+        ;;
+    delete)
+        delete_service
+        ;;
+    reinstall)
+        reinstall_service
+        ;;
+esac

package/cli-template/deploy/srv.sh.readme.md

@@ -0,0 +1,347 @@
+# srv.sh - Unified systemd Service Management Script
+
+Universal script for managing systemd services for Node.js applications. Consolidates functionality from separate `deploy/systemd-service/` scripts into a single solution.
+
+## Features
+
+- ✅ **Universal execution**: Works the same when launched from project root or from `deploy/` folder
+- ✅ **Auto-detection of Node.js version**: Priority: parameter → .envrc → current version
+- ✅ **Smart Node.js search**: NVM paths → system paths
+- ✅ **Automatic configuration reading**: package.json, config for port
+- ✅ **systemd unit file generation**: Correct paths and settings
+- ✅ **Process management**: Stops processes on ports when removing
+
+## Operation Algorithm
+
+### Working Directory Determination
+
+```bash
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"    # Script folder: /path/to/project/deploy/
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"                      # Project root: /path/to/project/
+```
+
+**Result**: Regardless of launch location, the script always uses the project root for:
+- Reading `package.json`
+- Reading `.envrc`
+- Reading configuration
+- Setting `WorkingDirectory` in systemd unit
+
+### Node.js Version Detection Algorithm
+
+1. **Parameter `-v <version>`** (highest priority)
+   ```bash
+   ./deploy/srv.sh install -v 20.10.0
+   ```
+
+2. **`.envrc` file in project root**
+   ```bash
+   # Searches for line like:
+   nvm use 22.17.1
+   # Extracts: 22.17.1
+   ```
+
+3. **Current Node.js version** (fallback)
+   ```bash
+   node -v  # For example: v22.17.1 → 22.17.1
+   ```
+
+### Node.js Path Search Algorithm
+
+1. **NVM path** (priority)
+   ```bash
+   $HOME/.nvm/versions/node/v22.17.1/bin/node
+   ```
+
+2. **System path** (fallback)
+   ```bash
+   which node  # For example: /usr/bin/node
+   ```
+
+### Service Name Detection Algorithm
+
+1. **Parameter `-n <name>`** (priority)
+2. **`name` value from package.json** (default)
+
+### Port Detection Algorithm
+
+1. **Parameter `-p <port>`** (priority)
+2. **`config.webServer.port` value** (automatic)
+   ```javascript
+   // Executed from project root:
+   const config = require('config');
+   console.log(config.webServer?.port);
+   ```
+
+## Commands
+
+### Service Installation
+
+```bash
+# Basic installation (auto-detect all parameters)
+./deploy/srv.sh install
+./deploy/srv.sh i
+
+# With custom service name
+./deploy/srv.sh install -n my-custom-service
+
+# With specific Node.js version
+./deploy/srv.sh install -v 20.10.0
+
+# Combined parameters
+./deploy/srv.sh i -n custom-service -v 22.17.1
+```
+
+**What happens:**
+1. Node.js version and binary path are determined
+2. `package.json` is read to get `main` and `name`
+3. systemd unit file is generated in `/etc/systemd/system/<service_name>.service`
+4. `systemctl daemon-reload` is executed
+5. `systemctl enable --now <service_name>` is executed
+
+### Service Removal
+
+```bash
+# Auto-detect port from config
+./deploy/srv.sh delete
+./deploy/srv.sh d
+
+# With custom service name
+./deploy/srv.sh delete -n custom-service
+
+# With specific port
+./deploy/srv.sh delete -p 8080
+
+# Combined parameters
+./deploy/srv.sh d -n custom-service -p 9021
+```
+
+**What happens:**
+1. Port is determined from configuration or parameter
+2. `systemctl stop <service_name>` is executed
+3. `systemctl disable <service_name>` is executed
+4. Unit file `/etc/systemd/system/<service_name>.service` is removed
+5. Process on specified port is terminated (if exists)
+6. `systemctl daemon-reload` is executed
+
+### Service Reinstallation
+
+```bash
+# Complete reinstallation
+./deploy/srv.sh reinstall
+./deploy/srv.sh r
+
+# With parameters
+./deploy/srv.sh r -n custom-service -v 22.17.1 -p 9021
+```
+
+**What happens:**
+1. Complete service removal is performed (as in `delete`)
+2. Complete service installation is performed (as in `install`)
+3. Status is shown and log viewing is started
+
+## Execution Examples
+
+### From Project Root
+
+```bash
+# All commands work from root
+./deploy/srv.sh install
+./deploy/srv.sh delete -p 9021
+./deploy/srv.sh reinstall -n mcp-fin-office-dev
+```
+
+### From deploy Folder
+
+```bash
+cd deploy/
+
+# All commands work from deploy folder
+./srv.sh install
+./srv.sh delete -p 9021
+./srv.sh reinstall -n mcp-fin-office-dev
+```
+
+### Real-world Project Examples
+
+```bash
+# Development installation
+./deploy/srv.sh install -n mcp-fin-office-dev -v 22.17.1
+
+# Production installation with auto-detection
+./deploy/srv.sh install
+
+# Remove dev version
+./deploy/srv.sh delete -n mcp-fin-office-dev
+
+# Quick reinstall after changes
+./deploy/srv.sh reinstall
+```
+
+## Generated systemd Unit File
+
+```ini
+[Unit]
+Description=mcp-fin-office
+After=network.target
+StartLimitIntervalSec=0
+
+[Service]
+User=root
+WorkingDirectory=/path/to/project/root
+EnvironmentFile=/path/to/project/root/.env
+ExecStart=/root/.nvm/versions/node/v22.17.1/bin/node dist/src/_core/index.js
+Restart=always
+RestartSec=3
+StandardOutput=syslog
+StandardError=syslog
+
+[Install]
+WantedBy=multi-user.target
+```
+
+## Debugging and Monitoring
+
+### View Status
+
+```bash
+systemctl status mcp-fin-office
+```
+
+### View Logs
+
+```bash
+# Recent logs
+journalctl -u mcp-fin-office
+
+# Follow logs in real-time
+journalctl -u mcp-fin-office -f
+
+# Logs from last hour
+journalctl -u mcp-fin-office --since "1 hour ago"
+```
+
+### Manual Control
+
+```bash
+# Stop
+sudo systemctl stop mcp-fin-office
+
+# Start
+sudo systemctl start mcp-fin-office
+
+# Restart
+sudo systemctl restart mcp-fin-office
+
+# Disable autostart
+sudo systemctl disable mcp-fin-office
+```
+
+## Requirements
+
+- **Operating System**: Linux with systemd
+- **Permissions**: `sudo` privileges for managing systemd services
+- **Node.js**: Installed Node.js (NVM or system installation)
+- **Project Files**:
+  - `package.json` in project root
+  - Built application (file specified in `package.json` `main`)
+  - Optional: `.envrc` for Node.js version detection
+  - Optional: `config/` folder for port detection
+
+## File Structure
+
+```
+project-root/
+├── package.json              # Source: name, main
+├── .envrc                    # Optional: Node.js version
+├── config/
+│   └── default.yaml         # Optional: webServer.port
+├── deploy/
+│   ├── srv.sh              # ← This script
+│   └── srv.sh.readme.md    # ← This documentation
+└── dist/
+    └── src/
+        └── _core/
+            └── index.js     # Main application file
+```
+
+## Troubleshooting
+
+### Script Cannot Find Node.js
+
+```bash
+# Check Node.js availability
+node -v
+which node
+
+# Check NVM installation
+ls -la ~/.nvm/versions/node/
+```
+
+### package.json Reading Error
+
+```bash
+# Check JSON syntax
+cat package.json | jq .
+
+# Check for name and main fields
+node -e "const pkg = require('./package.json'); console.log('name:', pkg.name); console.log('main:', pkg.main);"
+```
+
+### Port Detection Error
+
+```bash
+# Check configuration
+node -e "const c = require('config'); console.log('port:', c.webServer?.port);"
+
+# Check configuration files
+ls -la config/
+cat config/default.yaml | grep -A5 webServer
+```
+
+### Access Permissions
+
+```bash
+# Check systemd management permissions
+sudo systemctl --version
+
+# Check write permissions for /etc/systemd/system/
+sudo ls -la /etc/systemd/system/
+```
+
+## CI/CD Integration
+
+### Automated Deployment
+
+```bash
+#!/bin/bash
+# deploy.sh
+
+# Build project
+npm ci
+npm run build
+
+# Install/reinstall service
+./deploy/srv.sh reinstall
+
+# Check successful startup
+sleep 5
+systemctl is-active --quiet mcp-fin-office && echo "Service started successfully"
+```
+
+### Rollback Script
+
+```bash
+#!/bin/bash
+# rollback.sh
+
+# Stop current service
+./deploy/srv.sh delete
+
+# Restore previous version
+git checkout HEAD~1
+npm ci
+npm run build
+
+# Start previous version
+./deploy/srv.sh install
+```