LIMS Changelogger

Interactive CLI tool for creating LIMS (Laboratory Information Management System) deployment log entries and Telegram notifications. All data is stored in a PostgreSQL database for easy querying, reporting, and concurrent access.

Features

• 🎯 Interactive GUI prompts - Modern checkbox lists, confirmations, and selections powered by Inquirer
• 📝 Automatic versioning - Intelligently suggests version numbers based on update type
• 🗄️ PostgreSQL database - All updates stored in a production-ready, scalable database
• 📱 Telegram notifications - Generates formatted messages for Telegram channels
• ✨ Type-based versioning - Automatically increments versions based on semantic versioning
• 🔍 Powerful querying - Search, filter, and export deployment history
• 📊 Statistics - View deployment statistics and trends
• ☑️ Smart issue tracking - Interactive checkbox interface for managing known issues across updates
• ⚙️ Easy configuration - Interactive setup wizard with lims-logger --config

Installation

Global Installation

npm install -g lims-changelogger

Local Installation

npm install lims-changelogger

From Source

git clone <repository-url>
cd lims-changelogger
npm install
npm install -g .

Configuration

The tool uses a config.json file stored in your home directory at ~/.lims-changelogger/config.json. This location ensures your configuration persists across package updates.

Quick Setup (Recommended)

Use the interactive configuration wizard:

lims-logger --config

This will guide you through setting up your PostgreSQL connection with:

• Current values pre-filled for easy editing
• Validation to prevent configuration errors
• Summary before saving
• Automatic creation of the config directory

Manual Setup

1. Create the config directory (if it doesn't exist):

   mkdir -p ~/.lims-changelogger

2. Create config.json in ~/.lims-changelogger/config.json:

   {
     "database": {
       "host": "localhost",
       "port": 5432,
       "database": "lims_updates",
       "user": "your_username",
       "password": "your_password",
       "max": 20,
       "idleTimeoutMillis": 30000,
       "connectionTimeoutMillis": 2000
     }
   }

Note: If you have an existing config in the package directory, it will be automatically migrated to ~/.lims-changelogger/config.json on first use.

Configuration Options

• host: PostgreSQL server hostname (default: localhost)
• port: PostgreSQL port (default: 5432)
• database: Database name (default: lims_updates)
• user: Database user
• password: Database password
• max: Maximum connection pool size (default: 20)
• idleTimeoutMillis: Idle connection timeout in ms (default: 30000)
• connectionTimeoutMillis: Connection timeout in ms (default: 2000)

Environment Variables

You can also use environment variables for credentials:

export PGUSER=your_username
export PGPASSWORD=your_password

These will be used as fallback values if not specified in config.json.

Note: If config.json is not found, the tool will use default settings connecting to localhost:5432/lims_updates

Usage

Creating Updates

Run the logger command:

lims-logger

The tool will interactively prompt you for:

1. Update Type - Choose from:

   • Bug Fix (patch increment)
   • New Feature (minor increment)
   • Enhancement (minor increment)
   • Security Patch (patch increment)
   • Performance Improvement (patch increment)

2. Version Number - Automatically assigned based on update type (follows semantic versioning)

3. Date/Time - Defaults to current time (customizable)

4. Developer Name - Your name

5. Changes - List of changes (one per line)

6. Bug Fixes - List of bug fixes (one per line)

7. Action Required - Any action users need to take

8. Known Issues - Interactive checkbox GUI:

   • Shows all currently active known issues as checkboxes (checked by default)
   • Use arrow keys to navigate, spacebar to uncheck fixed issues
   • Fixed issues will be shown with strikethrough and checkmark in Telegram
   • Add new known issues after the checkbox list
   • Fixed issues won't appear in future updates

9. Emergency Flag - Whether this is an emergency update

Querying Updates

Run the query command:

lims-query

Available query options:

1. List all updates - View recent updates (configurable limit)
2. Search by version - Find a specific version
3. Filter by type - Show only specific update types
4. Filter by developer - Show updates by a specific developer
5. Show emergency updates - View only emergency updates
6. View statistics - See database statistics and trends
7. Export to markdown - Generate a markdown file of all updates
8. Show Telegram message - Display the Telegram message for a specific version

Output

Database Storage

All updates are stored in PostgreSQL with the following structure:

• updates table - Main update information
• update_changes table - Individual changes for each update
• update_bugfixes table - Individual bug fixes for each update
• known_issues table - Temporal tracking of known issues

Telegram Message Format

The tool generates formatted messages that can be copied directly to Telegram:

🔔 LIMS UPDATE NOTIFICATION

Version: v1.2.3
Date: 19-11-2025 14:30
Developer: John Doe

━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 UPDATE TYPE: New Feature

✨ WHAT'S NEW:
• Added user authentication
• Improved error handling

🐛 BUG FIXES:
• Fixed login timeout issue

⚠️ ACTION REQUIRED:
None

⚙️ KNOWN ISSUES:
None

Markdown Export

Use lims-query to export all updates to a markdown file compatible with the original format:

## v1.2.3 - 19-11-2025 14:30

**Developer:** John Doe
**Type:** New Feature

### Changes
- Added user authentication
- Improved error handling

### Bug Fixes
- Fixed login timeout issue

### Action Required
None

### Known Issues
None

Semantic Versioning

The tool follows semantic versioning (MAJOR.MINOR.PATCH):

• New Features & Enhancements → Increment MINOR version
• Bug Fixes, Security Patches & Performance Improvements → Increment PATCH version
• Breaking Changes → Manually specify MAJOR version

Database Schema

updates table

• id - Primary key
• version - Version string (unique)
• date - Deployment date
• time - Deployment time
• developer - Developer name
• type - Update type
• action_required - Required actions
• known_issues - Known issues
• is_emergency - Emergency flag (0 or 1)
• telegram_message - Generated Telegram message
• created_at - Timestamp

update_changes table

• id - Primary key
• update_id - Foreign key to updates
• change_text - Change description

update_bugfixes table

• id - Primary key
• update_id - Foreign key to updates
• bugfix_text - Bug fix description

known_issues table

• id - Primary key
• issue_text - Issue description
• status - Status ('active' or 'fixed')
• created_in_update_id - Foreign key to updates (when issue was created)
• fixed_in_update_id - Foreign key to updates (when issue was fixed)
• created_at - Timestamp when issue was created
• fixed_at - Timestamp when issue was fixed

Known Issues Tracking

The tool tracks known issues across updates with intelligent status management:

How It Works

1. Creating Issues: When you create an update, you can add new known issues
2. Active Issues: All active known issues are shown in subsequent update creations
3. Fixing Issues: Check/uncheck issues during update creation to mark them as fixed
4. Fixed Display: Fixed issues appear with strikethrough (~~like this~~) and a checkmark ✓
5. History: Each issue tracks when it was created and when it was fixed

Example Workflow

Update v1.0.0: Add known issue "Login timeout on slow connections"

• Issue is now active

Update v1.1.0: Issue still active, shown in checklist

• Keep checked (still active)
• Add another issue: "Dashboard not responsive on mobile"

Update v1.2.0: Fix the login timeout

• Use arrow keys to navigate, spacebar to uncheck "Login timeout on slow connections"
• Telegram message shows: ✓ ~~Login timeout on slow connections~~ (Fixed in this update)
• Issue won't appear in future updates
• "Dashboard not responsive on mobile" still active

Interactive Interface

The tool uses Inquirer.js to provide a modern, user-friendly CLI experience:

• List Selection: Navigate update types with arrow keys
• Checkboxes: Multi-select interface for known issues (Space to toggle, Enter to confirm)
• Confirmations: Y/n prompts with clear defaults
• Input Fields: Smart validation and default values
• Error Prevention: Required field validation

Example checkbox interface:

? Current Known Issues (uncheck any that are fixed in this update):
 ◉ Login timeout on slow connections
 ◯ Dashboard not responsive on mobile  ← Unchecked (fixed)
 ◉ File upload size limit

Examples

Create a new update

lims-logger

View last 5 updates

lims-query
# Select option 1, enter 5 when prompted

Export all updates to markdown

lims-query
# Select option 7

Search for a specific version

lims-query
# Select option 2, enter version (e.g., v1.2.3)

Requirements

• Node.js >= 12.0.0
• PostgreSQL >= 12.0

Dependencies

• pg (node-postgres) - PostgreSQL client for Node.js
• inquirer - Interactive CLI prompts with checkbox support

All dependencies are automatically installed with npm install.

PostgreSQL Setup

Before using the tool, ensure PostgreSQL is installed and running:

Ubuntu/Debian

sudo apt-get install postgresql postgresql-contrib
sudo systemctl start postgresql

macOS

brew install postgresql
brew services start postgresql

Windows

Download from https://www.postgresql.org/download/

Create Database

sudo -u postgres psql
CREATE DATABASE lims_updates;
CREATE USER lims_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE lims_updates TO lims_user;
\q

Then run lims-logger --config to configure the connection.

License

MIT

Author

Created for LIMS deployment tracking and team communication.