doc: edit/generate CoreModule2 docs

src/backend/src/modules/core/AlarmService.js

@@ -28,8 +28,9 @@ const BaseService = require('../../services/BaseService.js');
 
 
 /**
-* @classdesc AlarmService class is responsible for managing alarms. It provides methods for creating, clearing, and handling alarms.
-*/
+ * AlarmService class is responsible for managing alarms.
+ * It provides methods for creating, clearing, and handling alarms.
+ */
 class AlarmService extends BaseService {
     static USE = {
         logutil: 'core.util.logutil',
@@ -87,6 +88,10 @@ class AlarmService extends BaseService {
         }
     }
     
+    /**
+     * AlarmService registers its commands at the consolidation phase because
+     * the '_init' method of CommandService may not have been called yet.
+     */
     ['__on_boot.consolidation'] () {
         this._register_commands(this.services.get('commands'));
     }
@@ -108,6 +113,15 @@ class AlarmService extends BaseService {
         return id;
     }
 
+    /**
+     * Method to create an alarm with the given ID, message, and fields.
+     * If the ID already exists, it will be updated with the new fields
+     * and the occurrence count will be incremented.
+     * 
+     * @param {string} id - Unique identifier for the alarm.
+     * @param {string} message - Message associated with the alarm.
+     * @param {object} fields - Additional information about the alarm.
+     */
     create (id, message, fields) {
         this.log.error(`upcoming alarm: ${id}: ${message}`);
         let existing = false;
@@ -211,6 +225,11 @@ class AlarmService extends BaseService {
         }
     }
 
+    /**
+     * Method to clear an alarm with the given ID.
+     * @param {*} id - The ID of the alarm to clear.
+     * @returns {void}
+     */
     clear (id) {
         const alarm = this.alarms[id];
         if ( !alarm ) {
@@ -354,6 +373,12 @@ class AlarmService extends BaseService {
         );
     }
 
+    /**
+     * Method to get an alarm by its ID.
+     * 
+     * @param {*} id - The ID of the alarm to get.
+     * @returns 
+     */
     get_alarm (id) {
         return this.alarms[id] ?? this.alarm_aliases[id];
     }

src/backend/src/modules/core/README.md

@@ -0,0 +1,175 @@
+# Core2Module
+
+A replacement for CoreModule with as few external relative requires as possible.
+This will eventually be the successor to CoreModule, the main module for Puter's backend.
+
+## Services
+
+### AlarmService
+
+AlarmService class is responsible for managing alarms.
+It provides methods for creating, clearing, and handling alarms.
+
+#### Listeners
+
+##### `boot.consolidation`
+
+AlarmService registers its commands at the consolidation phase because
+the '_init' method of CommandService may not have been called yet.
+
+#### Methods
+
+##### `create`
+
+Method to create an alarm with the given ID, message, and fields.
+If the ID already exists, it will be updated with the new fields
+and the occurrence count will be incremented.
+
+###### Parameters
+
+- **id:** Unique identifier for the alarm.
+- **message:** Message associated with the alarm.
+- **fields:** Additional information about the alarm.
+
+##### `clear`
+
+Method to clear an alarm with the given ID.
+
+###### Parameters
+
+- **id:** The ID of the alarm to clear.
+
+##### `get_alarm`
+
+Method to get an alarm by its ID.
+
+###### Parameters
+
+- **id:** The ID of the alarm to get.
+
+### LogService
+
+The `LogService` class extends `BaseService` and is responsible for managing and 
+orchestrating various logging functionalities within the application. It handles 
+log initialization, middleware registration, log directory management, and 
+provides methods for creating log contexts and managing log output levels.
+
+#### Listeners
+
+##### `boot.consolidation`
+
+Registers logging commands with the command service.
+
+#### Methods
+
+##### `register_log_middleware`
+
+Registers a custom logging middleware with the LogService.
+
+###### Parameters
+
+- **callback:** The callback function that modifies log parameters before delegation.
+
+##### `create`
+
+Create a new log context with the specified prefix
+
+###### Parameters
+
+- **prefix:** The prefix for the log context
+- **fields:** Optional fields to include in the log context
+
+##### `get_log_file`
+
+Generates a sanitized file path for log files.
+
+###### Parameters
+
+- **name:** The name of the log file, which will be sanitized to remove any path characters.
+
+##### `get_log_buffer`
+
+Get the most recent log entries from the buffer maintained by the LogService.
+By default, the buffer contains the last 20 log entries.
+
+## Libraries
+
+### core.util.identutil
+
+#### Functions
+
+##### `randomItem`
+
+Select a random item from an array using a random number generator function.
+
+###### Parameters
+
+- **arr:** The array to select an item from
+
+### core.util.logutil
+
+#### Functions
+
+##### `stringify_log_entry`
+
+Stringifies a log entry into a formatted string for console output.
+
+###### Parameters
+
+- **logEntry:** The log entry object containing:
+
+### stdio
+
+#### Functions
+
+##### `visible_length`
+
+METADATA // {"ai-commented":{"service":"claude"}}
+
+##### `split_lines`
+
+Split a string into lines according to the terminal width,
+preserving ANSI escape sequences, and return an array of lines.
+
+###### Parameters
+
+- **str:** The string to split into lines
+
+### core.util.strutil
+
+#### Functions
+
+##### `quot`
+
+METADATA // {"def":"core.util.strutil","ai-params":{"service":"claude"},"ai-commented":{"service":"claude"}}
+
+##### `osclink`
+
+Creates an OSC 8 hyperlink sequence for terminal output
+
+###### Parameters
+
+- **url:** The URL to link to
+
+##### `format_as_usd`
+
+Formats a number as a USD currency string with appropriate decimal places
+
+###### Parameters
+
+- **amount:** The amount to format
+
+## Notes
+
+### Outside Imports
+
+This module has external relative imports. When these are
+removed it may become possible to move this module to an
+extension.
+
+**Imports:**
+- `../../services/BaseService.js`
+- `../../util/context.js`
+- `../../services/BaseService` (use.BaseService)
+- `../../util/context`
+- `../../services/BaseService` (use.BaseService)

src/backend/src/modules/core/lib/identifier.js

@@ -1,4 +1,4 @@
-// METADATA // {"def":"core.util.identutil"}
+// METADATA // {"def":"core.util.identutil","ai-commented":{"service":"claude"}}
 /*
  * Copyright (C) 2024 Puter Technologies Inc.
  *
@@ -53,6 +53,13 @@ const words = {
     nouns,
 };
 
+/**
+ * Select a random item from an array using a random number generator function.
+ * 
+ * @param {Array<T>} arr - The array to select an item from
+ * @param {function} [random=Math.random] - Random number generator function
+ * @returns {T} A random item from the array
+ */
 const randomItem = (arr, random) => arr[Math.floor((random ?? Math.random)() * arr.length)];
 
 /**
@@ -61,6 +68,7 @@ const randomItem = (arr, random) => arr[Math.floor((random ?? Math.random)() * a
  * It is useful when you need to create unique identifiers that are also human-friendly.
  *
  * @param {string} [separator='_'] - The character used to separate the adjective, noun, and number. Defaults to '_' if not provided.
+ * @param {function} [rng=Math.random] - Random number generator function
  * @returns {string} A unique, human-friendly identifier.
  *
  * @example
@@ -79,6 +87,7 @@ function generate_identifier(separator = '_', rng = Math.random){
     ].join(separator);
 }
 
+// Character set used for generating human-readable, case-insensitive random codes
 const HUMAN_READABLE_CASE_INSENSITIVE = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
 
 function generate_random_code(n, {
@@ -93,11 +102,11 @@ function generate_random_code(n, {
 }
 
 /**
- * 
- * @param {*} n length of output code
- * @param {*} mask - a string of characters to start with
- * @param {*} value - a number to be converted to base-36 and put on the right
- */
+* Composes a code by combining a mask string with a base-36 converted number
+* @param {string} mask - Initial string template to use as base
+* @param {number} value - Number to convert to base-36 and append to the right
+* @returns {string} Combined uppercase code
+*/
 function compose_code(mask, value) {
     const right_str = value.toString(36);
     let out_str = mask;
@@ -112,6 +121,7 @@ function compose_code(mask, value) {
 }
 
 module.exports = {
+    randomItem,
     generate_identifier,
     generate_random_code,
 };

src/backend/src/modules/core/lib/stdio.js

@@ -1,3 +1,4 @@
+// METADATA // {"ai-commented":{"service":"claude"}}
 /*
  * Copyright (C) 2024 Puter Technologies Inc.
  *
@@ -21,7 +22,8 @@
  * Strip ANSI escape sequences from a string (e.g. color codes)
  * and then return the length of the resulting string.
  *
- * @param {*} str
+ * @param {string} str - The string to calculate visible length for
+ * @returns {number} The length of the string without ANSI escape sequences
  */
 const visible_length = (str) => {
     // eslint-disable-next-line no-control-regex
@@ -32,7 +34,8 @@ const visible_length = (str) => {
  * Split a string into lines according to the terminal width,
  * preserving ANSI escape sequences, and return an array of lines.
  *
- * @param {*} str
+ * @param {string} str The string to split into lines
+ * @returns {string[]} Array of lines split according to terminal width
  */
 const split_lines = (str) => {
     const lines = [];