fa-mcp-sdk 0.2.84 → 0.2.92

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

@@ -1,187 +1,174 @@
-# 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.
+# srv.cjs
+Universal script for managing systemd services of Node.js applications.
 
 ## 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
+- ✅ **Universal invocation**: Works the same when run from the project root or from the `deploy/` folder
+- ✅ **Automatic Node.js version detection**: Priority is CLI param → .envrc → current version
+- ✅ **Smart Node.js lookup**: NVM paths → system paths
+- ✅ **Automatic config reading**: package.json, config for port
+- ✅ **systemd unit generation**: Correct paths and settings
+- ✅ **Process management**: Stops processes bound to ports on deletion
+- ✅ **Instance support**: Service name can be extended with suffix `--<instance>` from `.env` (variable `SERVICE_INSTANCE`)
 
-## Operation Algorithm
+## Requirements and how to run
 
-### Working Directory Determination
+- The file is executable: `deploy/srv.cjs` has a shebang `#!/usr/bin/env node`. On the server, make sure the file has execute permissions:
 
 ```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/
+chmod +x deploy/srv.cjs
 ```
 
-**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)
+- You can run it in two equivalent ways:
 
-### Port Detection Algorithm
+```bash
+# From the project root or from the deploy/ folder
+./deploy/srv.cjs <command> [options]
 
-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);
-   ```
+# Or via node
+node deploy/srv.cjs <command> [options]
+```
 
 ## Commands
 
-### Service Installation
+### Install service
 
 ```bash
-# Basic installation (auto-detect all parameters)
-./deploy/srv.sh install
-./deploy/srv.sh i
+# Basic install (auto-detect everything)
+./deploy/srv.cjs install
+./deploy/srv.cjs i
 
-# With custom service name
-./deploy/srv.sh install -n my-custom-service
+# With a custom service name
+./deploy/srv.cjs install -n my-custom-service
 
-# With specific Node.js version
-./deploy/srv.sh install -v 20.10.0
+# With a specific Node.js version
+./deploy/srv.cjs install -v 20.10.0
 
-# Combined parameters
-./deploy/srv.sh i -n custom-service -v 22.17.1
+# Combined params
+./deploy/srv.cjs i -n custom-service -v 22.17.1
 ```
 
 **What happens:**
-1. Node.js version and binary path are determined
+1. Node.js version and path to the binary 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`
+3. A systemd unit file is generated at `/etc/systemd/system/<service_name>.service`
 4. `systemctl daemon-reload` is executed
 5. `systemctl enable --now <service_name>` is executed
 
-### Service Removal
+### Delete service
 
 ```bash
 # Auto-detect port from config
-./deploy/srv.sh delete
-./deploy/srv.sh d
+./deploy/srv.cjs delete
+./deploy/srv.cjs d
 
-# With custom service name
-./deploy/srv.sh delete -n custom-service
+# With a custom service name
+./deploy/srv.cjs delete -n custom-service
 
-# With specific port
-./deploy/srv.sh delete -p 8080
+# With a specific port
+./deploy/srv.cjs delete -p 8080
 
-# Combined parameters
-./deploy/srv.sh d -n custom-service -p 9021
+# Combined params
+./deploy/srv.cjs d -n custom-service -p 8080
 ```
 
 **What happens:**
-1. Port is determined from configuration or parameter
+1. Port is determined from config or CLI param
 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)
+5. Process on the specified port is terminated (if exists)
 6. `systemctl daemon-reload` is executed
 
-### Service Reinstallation
+### Reinstall service
 
 ```bash
-# Complete reinstallation
-./deploy/srv.sh reinstall
-./deploy/srv.sh r
+# Full reinstall
+./deploy/srv.cjs reinstall
+./deploy/srv.cjs r
 
-# With parameters
-./deploy/srv.sh r -n custom-service -v 22.17.1 -p 9021
+# With params
+./deploy/srv.cjs r -n custom-service -v 22.17.1 -p 8080
 ```
 
 **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
+1. Performs a full deletion (as in `delete`)
+2. Performs a full installation (as in `install`)
+3. Shows status and starts tailing logs
 
-## Execution Examples
+## How it works
 
-### From Project Root
+### Resolving working directories
 
-```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
+The script computes directories by itself (within Node.js runtime):
+
+```javascript
+// deploy/srv.cjs
+const SCRIPT_DIR = __dirname;           // /path/to/project/deploy/
+const PROJECT_ROOT = path.resolve(SCRIPT_DIR, '..'); // /path/to/project/
+process.chdir(PROJECT_ROOT);
 ```
 
-### From deploy Folder
+**Result**: Regardless of where it's launched, the script always uses the project root for:
+- Reading `package.json`
+- Reading `.envrc`
+- Reading configuration
+- Setting `WorkingDirectory` in the systemd unit
 
-```bash
-cd deploy/
+### Node.js version detection algorithm
 
-# All commands work from deploy folder
-./srv.sh install
-./srv.sh delete -p 9021
-./srv.sh reinstall -n mcp-fin-office-dev
-```
+1. **CLI param `-v <version>`** (highest priority)
+   ```bash
+   ./deploy/srv.cjs install -v 20.10.0
+   ```
 
-### Real-world Project Examples
+2. **`.envrc` file in the project root**
+   ```bash
+   # Looks for a line like:
+   nvm use 22.17.1
+   # Extracts: 22.17.1
+   ```
 
-```bash
-# Development installation
-./deploy/srv.sh install -n mcp-fin-office-dev -v 22.17.1
+3. **Current Node.js version** (fallback)
+   ```bash
+   node -v  # For example: v22.17.1 → 22.17.1
+   ```
 
-# Production installation with auto-detection
-./deploy/srv.sh install
+### Node.js binary path lookup
 
-# Remove dev version
-./deploy/srv.sh delete -n mcp-fin-office-dev
+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 resolution
+
+1. **CLI param `-n <name>`** (priority)
+2. **`.env` → `SERVICE_NAME`** (if provided)
+3. **`name` value from package.json** (default)
+4. Additionally: if `SERVICE_INSTANCE` is set in `.env`, the final name becomes `<name>--<instance>`
+
+### Port resolution
+
+1. **CLI param `-p <port>`** (priority)
+2. **`config.webServer.port` value** (automatic)
+   ```javascript
+   // Executed from the project root:
+   const config = require('config');
+   console.log(config.webServer?.port);
+   ```
 
-# Quick reinstall after changes
-./deploy/srv.sh reinstall
-```
 
-## Generated systemd Unit File
+## Generated systemd unit file
 
 ```ini
 [Unit]
-Description=mcp-fin-office
+Description=<serviceName>
 After=network.target
 StartLimitIntervalSec=0
 
@@ -189,159 +176,35 @@ StartLimitIntervalSec=0
 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
+ExecStart=/root/.nvm/versions/node/v22.17.1/bin/node <package.json.main>
 Restart=always
 RestartSec=3
-StandardOutput=syslog
-StandardError=syslog
 
 [Install]
 WantedBy=multi-user.target
 ```
 
-## Debugging and Monitoring
+## 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
+### Viewing logs
 
 ```bash
-# Stop
-sudo systemctl stop mcp-fin-office
+# Short status with logs
+systemctl -l status <serviceName>
 
-# Start
-sudo systemctl start mcp-fin-office
+# Latest logs (compact output)
+journalctl -o cat -u <serviceName>
 
-# Restart
-sudo systemctl restart mcp-fin-office
+# Follow logs in real time (equivalent to what `reinstall` starts)
+journalctl -o cat -xefu <serviceName>
 
-# Disable autostart
-sudo systemctl disable mcp-fin-office
+# Logs for the last hour
+journalctl -u <serviceName> --since "1 hour ago"
 ```
 
-## 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
+### Manual control
 
 ```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
+sudo systemctl start|stop|restart|disable|status <serviceName>
 ```

package/cli-template/update.cjs

@@ -1,3 +1,5 @@
+#!/usr/bin/env node
+
 // noinspection UnnecessaryLocalVariableJS
 
 const fs = require('fs');
@@ -5,12 +7,12 @@ const path = require('path');
 const { execSync, spawn } = require('child_process');
 const os = require('os');
 
-const version = '2025.11.22-1800';
+const version = '2025.11.25-0506';
 console.log(`Update script version: ${version}`);
 
-// Имя этой папки
+// Name of this folder
 const scriptDirName = require('path').basename(__dirname);
-// Смена рабочей директории на директорию скрипта
+// Changing the working directory to a script directory
 process.chdir(__dirname);
 const CWD = process.cwd();
 const VON = path.resolve(path.join(CWD, '..'));
@@ -122,7 +124,7 @@ const truncateCumulativeLogIfNeeded = () => {
         const tailContent = buffer.toString('utf8').replace(/^[\r\n]*/, ''); // Remove leading newlines
         fs.writeFileSync(logFile, tailContent);
 
-        log(`Cumulative log truncated to ${Math.round(tailContent.length / 1024)}KB`);
+        logIt(`Cumulative log truncated to ${Math.round(tailContent.length / 1024)}KB`);
       }
     }
   } catch (error) {
@@ -152,10 +154,7 @@ function execCommand (command, options = {}, withSetupScript = false) {
     });
     return result;
   } catch (error) {
-    if (options.throwOnError !== false) {
-      throw error;
-    }
-    return error.stdout || '';
+    throw error;
   }
 }
 
@@ -322,7 +321,10 @@ function getServiceName () {
       serviceName = packageJson.name;
     }
 
-    return `${serviceName}${serviceInstance}`;
+    return {
+      serviceName,
+      serviceNamePM: `${serviceName}${serviceInstance}`,
+    };
   } catch (error) {
     console.error('Error getting service name:', error.message);
     process.exit(1);
@@ -334,7 +336,7 @@ function getServiceName () {
  */
 function systemctlServiceExists (serviceName) {
   try {
-    execCommand(`systemctl list-unit-files "${serviceName}.service"`);
+    const res = execCommand(`systemctl list-unit-files "${serviceName}.service"`);
     return true;
   } catch {
     return false;
@@ -343,8 +345,8 @@ function systemctlServiceExists (serviceName) {
 
 function pm2ServiceExists (serviceName) {
   try {
-    execCommand(`pm2 id "${serviceName}"`);
-    return true;
+    const res = execCommand(`pm2 id "${serviceName}"`);
+    return /\[\s*\d\s*]/.test(res);
   } catch {
     return false;
   }
@@ -374,7 +376,11 @@ function getRepoInfo () {
       upstreamHash,
     };
   } catch (error) {
-    console.error('Error getting repo info:', error.message);
+    const message = String(error.message).includes(error.stderr)
+      ? error.message
+      : [error.stderr, error.message].join('\n');
+
+    console.error('Error getting repo info:', message);
     return null;
   }
 }
@@ -423,7 +429,6 @@ ${colorizeHTML(clearColors(body))}
       logIt(`Sending update notification to: ${emailAddress}`);
       const subject = `${status} Update: ${serviceName} (on ${hostname})`;
 
-      // Подаем тело письма через stdin, задаем Content-Type
       const command = `mail -a "Content-Type: text/html; charset=UTF-8" -s "${subject.replace(/"/g, '\\"')}" "${emailAddress}"`;
       const child = spawn('/bin/bash', ['-lc', command], { stdio: ['pipe', 'inherit', 'inherit'] });
       child.stdin.write(htmlContent);
@@ -482,18 +487,18 @@ const buildQuasar = () => {
   logIt('Quasar build completed');
 };
 
-const restartService = (serviceName, args) => {
+const restartService = (serviceNamePM) => {
   let srvc = '';
-  if (systemctlServiceExists(serviceName)) {
+  if (systemctlServiceExists(serviceNamePM)) {
     srvc = 'systemctl';
-  } else if (pm2ServiceExists(serviceName)) {
+  } else if (pm2ServiceExists(serviceNamePM)) {
     srvc = 'pm2';
   } else {
-    logIt(`Service ${serviceName} not found in systemctl or PM2`);
+    logIt(`Service ${serviceNamePM} not found in systemctl or PM2`);
     return;
   }
-  logIt(`Restarting service ${serviceName} via ${srvc}`, true);
-  execCommand(`${srvc} restart "${serviceName}"`);
+  logIt(`Restarting service ${serviceNamePM} via ${srvc}`, true);
+  execCommand(`${srvc} restart "${serviceNamePM}"`);
   logIt(`Service restarted`);
 };
 
@@ -511,7 +516,7 @@ async function main () {
   }
 
   // Get service information
-  const serviceName = getServiceName();
+  const { serviceName, serviceNamePM } = getServiceName();
 
   logIt(`<status>Update <y>${colorG.y(serviceName)}</y> ${nowPretty()}`);
 
@@ -533,7 +538,7 @@ async function main () {
   const expectedBranch = args.expectedBranch || config.branch;
   let updateDeployedLogFile = false;
   try {
-    // 1) Если есть локальные изменения — откатить
+    // 1) If there are local changes, roll back
     const hasChanges = execCommand('git status --porcelain').trim().length > 0;
     if (hasChanges) {
       logIt(`Found uncommited changes. Reset to HEAD...`);
@@ -546,7 +551,7 @@ async function main () {
     const repoInfo = getRepoInfo();
     let { branch, headHash, upstreamHash } = repoInfo;
 
-    // 2) Если ветка не та — жестко переключиться на голову удаленной expectedBranch
+    // 2) If the branch is not the same, hard switch to the head of the deleted expectedBranch
     const expectedUpstream = `origin/${expectedBranch}`;
     if (branch !== expectedBranch) {
       needUpdate = true;
@@ -566,7 +571,7 @@ async function main () {
     }
 
     if (headHash !== upstreamHash) {
-      // 3) Ветка та же, но надо подтянуть изменения
+      // 3) The branch is the same, but we need to tighten up the changes
       needUpdate = true;
       updateReason += `${updateReason ? '. ' : ''}headHash !== upstreamHash (${headHash} != ${upstreamHash})`;
       printCurrenBranch();
@@ -584,7 +589,7 @@ async function main () {
       reinstallDependencies();
       compile();
       buildQuasar();
-      restartService(serviceName, args);
+      restartService(serviceNamePM);
 
       // Add completion info to build log
       logIt(`Update completed successfully at ${new Date().toISOString().replace('T', ' ').substring(0, 19)}`);
@@ -594,6 +599,8 @@ async function main () {
       } else {
         logIt('EMAIL not found');
       }
+    } else {
+      logIt('No changes detected. Update skipped.');
     }
   } catch (err) {
     const message = String(err.message).includes(err.stderr)

package/dist/core/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"AAKA,OAAO,EAAe,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAExE,QAAA,MAAe,aAAa,SAAqB,CAAC;AAKlD,QAAA,IAAI,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;AAC5B,QAAA,IAAI,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC;AA6CvC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,CAAC"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"AAKA,OAAO,EAAe,MAAM,EAAE,UAAU,EAAE,OAAO,EAAmB,MAAM,cAAc,CAAC;AAEzF,QAAA,MAAe,aAAa,SAAkC,CAAC;AAK/D,QAAA,IAAI,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;AAC5B,QAAA,IAAI,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC;AAiDvC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,CAAC"}

package/dist/core/logger.js

@@ -3,7 +3,7 @@
 import { red, reset } from 'af-color';
 import { appConfig } from './bootstrap/init-config.js';
 import { getAFLogger } from 'af-logger-ts';
-const { level, useFileLogger } = appConfig.logger;
+const { level, useFileLogger, dir: logDir } = appConfig.logger;
 // Check if we're in STDIO mode to disable console logging
 const isStdioMode = appConfig.mcp.transportType === 'stdio';
 let logger;
@@ -22,7 +22,7 @@ if (appConfig.mcp.transportType === 'stdio') {
     };
 }
 else {
-    const { logger: l, fileLogger: fl } = getAFLogger({
+    const settings = {
         level: isStdioMode ? 'error' : level, // Suppress most logs in STDIO mode
         maxSize: '500m',
         name: '\x1b[1P',
@@ -45,7 +45,11 @@ else {
             /https?:\/\/[^:]+:[^@]+@/gi,
         ],
         noFileLogger: !Boolean(useFileLogger),
-    });
+    };
+    if (useFileLogger && logDir) {
+        settings.logDir = logDir;
+    }
+    const { logger: l, fileLogger: fl } = getAFLogger(settings);
     logger = l;
     fileLogger = fl;
 }