hola-server 1.0.10 → 2.0.1

package/skills/array.md

@@ -0,0 +1,155 @@
+# Array Utilities Skill
+
+## Overview
+
+The `hola-server/core/array.js` module provides a set of utility functions for common array manipulations. This skill guide explains how to use these helpers effectively.
+
+## Importing
+
+```javascript
+const { 
+    shuffle, remove_element, pop_n, shift_n, 
+    sum, avg, map_array_to_obj, 
+    sort_desc, sort_asc, sort_by_key_seq, 
+    combine, unique 
+} = require("hola-server/core/array");
+```
+
+## API Reference
+
+### 1. Modification & Extraction
+
+#### `shuffle(arr)`
+Randomly shuffles array elements in place.
+- **param**: `arr` (Array) - The array to shuffle.
+- **returns**: `void` (Modifies array in place).
+
+```javascript
+const list = [1, 2, 3, 4, 5];
+shuffle(list);
+// list is now randomized, e.g., [3, 1, 5, 2, 4]
+```
+
+#### `remove_element(array, field, value)`
+Removes elements from an array of objects where the specified field matches the value.
+- **param**: `array` (Object[]) - Array of objects.
+- **param**: `field` (string) - Property name to match against.
+- **param**: `value` (*) - Value to look for.
+- **returns**: `void` (Modifies array in place).
+
+```javascript
+const users = [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}];
+remove_element(users, 'id', 1);
+// users is now [{id: 2, name: 'Bob'}]
+```
+
+#### `pop_n(array, n)` / `shift_n(array, n)`
+Extracts (removes and returns) `n` elements from the end (`pop_n`) or start (`shift_n`) of an array.
+- **param**: `array` (Array) - Source array (modified).
+- **param**: `n` (number) - Number of elements to extract.
+- **returns**: `Array` or `undefined` - Array of extracted elements, or undefined if array became empty before extracting `n` items? N.B. actually it tries to remove up to n. If returns undefined if result is empty.
+
+```javascript
+const nums = [1, 2, 3, 4, 5];
+const lastTwo = pop_n(nums, 2); // [5, 4] (Note: items come off one by one)
+// nums is now [1, 2, 3]
+
+const firstTwo = shift_n(nums, 2); // [1, 2]
+// nums is now [3]
+```
+
+### 2. Calculation
+
+#### `sum(arr)`
+Calculates the sum of an array of numbers.
+- **param**: `arr` (number[]) - Array of numbers.
+- **returns**: `number` - Sum rounded to 2 decimal places.
+
+```javascript
+sum([10.5, 20.3, 5.111]); // Returns 35.91
+```
+
+#### `avg(arr)`
+Calculates the average of an array of numbers.
+- **param**: `arr` (number[]) - Array of numbers.
+- **returns**: `number` - Average rounded to 2 decimal places.
+
+```javascript
+avg([10, 20, 30]); // Returns 20
+```
+
+### 3. Transformation & Combining
+
+#### `map_array_to_obj(arr, key_attr, value_attr)`
+Converts an array of objects into a single object (map) using specified properties for keys and values.
+- **param**: `arr` (Object[]) - Array of objects.
+- **param**: `key_attr` (string) - Property to use as object key.
+- **param**: `value_attr` (string) - Property to use as object value.
+- **returns**: `Object` - Key-value map.
+
+```javascript
+const users = [
+    {id: 1, name: 'Alice', role: 'admin'},
+    {id: 2, name: 'Bob', role: 'user'}
+];
+const userMap = map_array_to_obj(users, 'id', 'name');
+// Returns: { 1: 'Alice', 2: 'Bob' }
+```
+
+#### `combine(arr1, arr2)`
+Creates a Cartesian product of two arrays of objects, merging properties.
+- **param**: `arr1` (Object[]) - First array.
+- **param**: `arr2` (Object[]) - Second array.
+- **returns**: `Object[]` - Array of merged objects (length = arr1.length * arr2.length).
+
+```javascript
+const colors = [{ color: 'red' }, { color: 'blue' }];
+const sizes = [{ size: 'S' }, { size: 'M' }];
+const products = combine(colors, sizes);
+// Returns:
+// [
+//   { color: 'red', size: 'S' }, { color: 'red', size: 'M' },
+//   { color: 'blue', size: 'S' }, { color: 'blue', size: 'M' }
+// ]
+```
+
+#### `unique(array)`
+Removes duplicate values from an array. Handles primitives and objects (via stringification).
+- **param**: `array` (Array) - Source array.
+- **returns**: `Array` - New array with duplicates removed.
+
+```javascript
+unique([1, 2, 2, 3]); // [1, 2, 3]
+unique([{id:1}, {id:1}, {id:2}]); // [{id:1}, {id:2}]
+```
+
+### 4. Sorting
+
+#### `sort_asc(arr, attr)` / `sort_desc(arr, attr)`
+Sorts an array of objects by a numeric attribute in ascending or descending order.
+- **param**: `arr` (Object[]) - Array to sort.
+- **param**: `attr` (string) - Numeric property to sort by.
+- **returns**: `Object[]` - Sorted array (same reference).
+
+```javascript
+const items = [{ price: 10 }, { price: 5 }, { price: 20 }];
+sort_asc(items, 'price'); // [{price: 5}, {price: 10}, {price: 20}]
+```
+
+#### `sort_by_key_seq(arr, attr, keys)`
+Sorts an array of objects based on a specific sequence of values for an attribute.
+- **param**: `arr` (Object[]) - Array to sort.
+- **param**: `attr` (string) - Property to inspect.
+- **param**: `keys` (Array) - Ordered list of values defining the sort order.
+- **returns**: `Object[]` - Sorted array.
+
+```javascript
+const tasks = [
+    { status: 'done' }, 
+    { status: 'todo' }, 
+    { status: 'doing' }
+];
+const order = ['todo', 'doing', 'done'];
+sort_by_key_seq(tasks, 'status', order);
+// Result: [{status: 'todo'}, {status: 'doing'}, {status: 'done'}]
+```

package/skills/bash.md

@@ -0,0 +1,91 @@
+# Bash Utilities Skill
+
+## Overview
+
+The `hola-server/core/bash.js` module provides comprehensive utilities for executing local and remote (SSH) commands, handling file transfers (SCP), and managing processes. It includes built-in logging and error handling.
+
+## Importing
+
+```javascript
+const {
+    stop_process, scp, scpr,
+    run_script, run_script_extra, run_script_file,
+    run_simple_cmd, run_local_cmd, run_simple_local_cmd,
+    get_info, get_system_attributes,
+    read_key_value_line, read_obj_line
+} = require("hola-server/core/bash");
+```
+
+## API Reference
+
+### 1. Remote Execution (SSH)
+
+#### `run_script(host, script, log_extra)`
+Executes a script/command on a remote host via SSH.
+- **param**: `host` (Object) - Host info `{name, user, ip, port, auth}`.
+- **param**: `script` (string) - Shell commands to run.
+- **param**: `log_extra` (Object) - Optional context for logging.
+- **returns**: `Promise<{stdout, err}>`
+
+```javascript
+const host = { name: "web1", user: "root", ip: "10.0.0.1", port: 22, auth: "-i ~/.ssh/id_rsa" };
+const { stdout, err } = await run_script(host, "ls -la /var/www");
+```
+
+#### `run_simple_cmd(host, cmd, log_extra)`
+Wrapper around `run_script` that returns trimmed stdout or null on error.
+- **returns**: `Promise<string|null>`
+
+```javascript
+const uptime = await run_simple_cmd(host, "uptime");
+```
+
+#### `run_script_file(host, script_file, log_extra)`
+Reads a local script file and executes it on the remote host.
+- **param**: `script_file` (string) - Path to local script.
+- **returns**: `Promise<{stdout, err}>`
+
+#### `stop_process(host, process_name, stop_cmd, using_full, log_extra)`
+Checks if a process is running on remote host and stops it if found.
+- **param**: `process_name` (string) - Name to grep for.
+- **param**: `stop_cmd` (string) - Command to kill the process (e.g. `pkill node`).
+- **param**: `using_full` (boolean) - If true, uses `pgrep -f`.
+- **returns**: `Promise<boolean>` - True if process was running.
+
+### 2. File Transfer (SCP)
+
+#### `scp(host, remote_file, local_file, log_extra)`
+Downloads a file from remote to local.
+- **returns**: `Promise<{stdout, err}>`
+
+#### `scpr(host, local_file, remote_file, log_extra)`
+Uploads a file from local to remote.
+- **returns**: `Promise<{stdout, err}>`
+
+### 3. Local Execution
+
+#### `run_local_cmd(cmd, log_extra)`
+Executes a command on the local machine.
+- **returns**: `Promise<{stdout, err}>`
+
+#### `run_simple_local_cmd(cmd, log_extra)`
+Executes local command and returns trimmed stdout or null on error.
+- **returns**: `Promise<string|null>`
+
+### 4. Output Parsing
+
+#### `get_info(stdout, key, log_extra)`
+Extracts values from stdout using regex pattern `key: value`.
+- **returns**: `string[]` - Array of matched values.
+
+#### `read_key_value_line(stdout, delimiter, lines, config, exclude_mode)`
+Parses output lines into a key-value object.
+- **param**: `delimiter` (string) - Separator (default ":").
+- **param**: `lines` (number[]) - Specific line indices to read.
+- **returns**: `Object`
+
+#### `read_obj_line(stdout, keys, ignore, delimiter)`
+Parses columnar output into array of objects.
+- **param**: `keys` (string[]) - Property names for columns.
+- **param**: `ignore` (number) - Number of header lines to skip.
+- **returns**: `Object[]`

package/skills/chart.md

@@ -0,0 +1,54 @@
+# Chart Utilities Skill
+
+## Overview
+
+The `hola-server/core/chart.js` module provides helpers for manipulating chart data structures, typically represented as 2D arrays (array of rows, where the first row is headers).
+
+## Importing
+
+```javascript
+const { set_chart_header, merge_chart_data } = require("hola-server/core/chart");
+```
+
+## API Reference
+
+### `set_chart_header(arr, prefix)`
+Modifies chart headers in-place by prepending a prefix to all columns except the first one (usually the x-axis/category).
+- **param**: `arr` (Array[]) - 2D array [header_row, data_row1, ...].
+- **param**: `prefix` (string) - String to prepend to headers.
+- **returns**: `void` (Modifies array in place).
+
+```javascript
+const data = [
+    ["Date", "Value", "Cost"],
+    ["2023-01-01", 100, 50]
+];
+set_chart_header(data, "US_");
+// data[0] becomes ["Date", "US_Value", "US_Cost"]
+```
+
+### `merge_chart_data(arr1, arr2)`
+Merges two chart data sets (2D arrays) by appending columns from `arr2` (excluding its first ID column) to `arr1`. Handles mismatched lengths by padding with empty strings.
+- **param**: `arr1` (Array[]) - Base dataset (modified in place).
+- **param**: `arr2` (Array[]) - Dataset to merge.
+- **returns**: `void`.
+
+```javascript
+const chart1 = [
+    ["Date", "A"],
+    ["Jan", 10]
+];
+const chart2 = [
+    ["Date", "B"],
+    ["Jan", 20],
+    ["Feb", 25]
+];
+
+merge_chart_data(chart1, chart2);
+// chart1 becomes:
+// [
+//   ["Date", "A", "B"],
+//   ["Jan", 10, 20],
+//   ["Feb", "", 25]  <-- padded row for chart1
+// ]
+```