drunken-chunk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antigravity Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the software, and to permit persons to whom the software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,266 @@
+# 💧 Drunken Chunk (drunken-chunk)
+
+[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Platform](https://img.shields.io/badge/platform-windows%20%7C%20macos%20%7C%20linux-lightgrey.svg)](#-supported-platforms--native-mechanics)
+[![Dependencies](https://img.shields.io/badge/dependencies-zero-orange.svg)](#-technical-implementation-highlights)
+
+A beautiful, premium, cross-platform CLI-based water tracking tool, smart background reminder service, and behavioral analytics dashboard. Written in 100% pure Python with **zero external dependencies**, Drunken Chunk leverages native OS mechanisms to keep you healthy, hydrated, and productive.
+
+---
+
+## 📖 Table of Contents
+
+- [✨ Features](#-features)
+- [🖥️ Supported Platforms & Native Mechanics](#%EF%B8%8F-supported-platforms--native-mechanics)
+- [🚀 Installation & Quick Start](#-installation--quick-start)
+  - [Prerequisites](#prerequisites)
+  - [Global Installation (Recommended)](#global-installation-recommended)
+  - [Local Development & Source Running](#local-development--source-running)
+- [🛠️ CLI Commands & Usage](#%EF%B8%8F-cli-commands--usage)
+  - [1. Initialization (`init`)](#1-initialization-init)
+  - [2. Interactive Console Logging (`log` / `log-custom`)](#2-interactive-console-logging-log--log-custom)
+  - [3. Dashboard Progress (`status`)](#3-dashboard-progress-status)
+  - [4. Vessel Shortcuts (`shortcut`)](#4-vessel-shortcuts-shortcut)
+  - [5. Historical Log View (`history`)](#5-historical-log-view-history)
+  - [6. Behavioral Analytics (`analyze`)](#6-behavioral-analytics-analyze)
+  - [7. Reminder Controls (`start` / `stop` / `snooze`)](#7-reminder-controls-start--stop--snooze)
+  - [8. Startup Integration (`autostart`)](#8-startup-integration-autostart)
+- [📂 Project Directory Layout](#-project-directory-layout)
+- [⚙️ How It Works under the Hood](#%EF%B8%8F-how-it-works-under-the-hood)
+- [🤝 Contributing](#-contributing)
+- [📄 License](#-license)
+
+---
+
+## ✨ Features
+
+* **Smart Reminder Service**: Notifies you to drink water based on your waking hours and consumption frequency. Unlike rigid timer tools, Drunken Chunk is **context-aware**—logging a drink automatically pushes your next notification out by one full interval.
+* **Rich Terminal UI**: Beautiful, premium gradient styling, custom ASCII banners, and dynamic progress bars without requiring external packages like `rich` or `colorama`.
+* **Platform-Native Notifications**: Zero-dependency notifications that natively slide in on Windows (WinRT toast alerts), macOS (AppleScript alerts), and Linux (D-Bus `notify-send` alerts).
+* **Behavioral Telemetry**: Tracks your hydration rates across weekdays, details diurnal drinking spreads (morning, afternoon, evening), calculates target consistency indices, and surfaces actionable sleep/health recommendations.
+* **SQL Log Storage**: Leverages a local, lightweight SQLite database to manage user dimensions, drink vessel shortcuts, logging history, and daemon state.
+
+---
+
+## 🖥️ Supported Platforms & Native Mechanics
+
+Drunken Chunk is built to operate with lightweight, native OS components instead of heavy third-party system libraries:
+
+| Platform | Native Desktop Notifications | Background Daemon Detaching | Autostart Boot Entry |
+| :--- | :--- | :--- | :--- |
+| 🪟 **Windows** | PowerShell WinRT XML API Toast | `DETACHED_PROCESS` + `CREATE_NO_WINDOW` flags | Windows Startup batch launcher script (`shell:startup`) |
+| 🍎 **macOS** | AppleScript `display notification` | `start_new_session` (`setsid`) background process | User Launch Agent (`~/Library/LaunchAgents/*.plist`) |
+| 🐧 **Linux** | Desktop D-Bus `notify-send` utility | `start_new_session` (`setsid`) background process | XDG Desktop Entry (`~/.config/autostart/*.desktop`) |
+
+---
+
+## 🚀 Installation & Quick Start
+
+### Prerequisites
+* Python **3.8** or newer installed.
+* Standard command-line terminal environment.
+
+### Global Installation (Recommended)
+You can install Drunken Chunk in editable mode or globally from source. Open your terminal in this repository folder and run:
+
+```bash
+pip install -e .
+```
+
+Once installed, the main command is linked globally. Test the installation by running:
+```bash
+drunken-chunk --help
+```
+
+### Local Development & Source Running
+If you prefer not to install the package globally, you can invoke the CLI using the platform-specific execution wrappers located at the repository root:
+
+* **Windows PowerShell/Command Prompt:**
+  ```cmd
+  drunken-chunk.bat --help
+  ```
+* **macOS / Linux terminal:**
+  Ensure the wrapper script has execute permissions:
+  ```bash
+  chmod +x drunken-chunk
+  ./drunken-chunk --help
+  ```
+
+---
+
+## 🛠️ CLI Commands & Usage
+
+### 1. Initialization (`init`)
+Sets up your personal physical profile and hydration constraints. Drunken Chunk will calculate a customized daily intake target based on your metabolic demands (weight, height, and BMI metadata).
+```bash
+drunken-chunk init
+```
+During initialization, you will be prompted for:
+1. Your name.
+2. Weight in kg (for metabolic calculation).
+3. Height in cm (for BMI classification).
+4. Wake-up and Sleep times (defines **Quiet Hours** to prevent middle-of-the-night notifications).
+5. Notification interval in minutes.
+6. Optional custom target override (e.g. 3000 ml).
+
+> [!NOTE]
+> **Automatic Setup Trigger**: If you run any other CLI subcommand on a fresh database before running `init`, the program will automatically launch the setup wizard first to ensure your database is initialized.
+
+---
+
+### 2. Interactive Console Logging (`log` / `log-custom`)
+Log your water intake instantly using direct integers, custom shortcuts, or relative timestamps.
+
+* **Log by Volume (milliliters):**
+  ```bash
+  drunken-chunk log 350
+  ```
+* **Log using a Vessel Shortcut:**
+  ```bash
+  drunken-chunk log glass
+  ```
+* **Log in the Past (Relative/Absolute):**
+  Useful if you forgot to log a drink earlier:
+  ```bash
+  drunken-chunk log-custom 250 "15m ago"     # 15 minutes ago
+  drunken-chunk log-custom 500 "2h ago"      # 2 hours ago
+  drunken-chunk log-custom 300 "14:30"       # At exactly 2:30 PM today
+  ```
+* **Undo Last Log Entry:**
+  Quickly undo your last recorded log if you made a typo:
+  ```bash
+  drunken-chunk undo
+  ```
+
+---
+
+### 3. Dashboard Progress (`status`)
+Presents a status breakdown including your hydration progress bar, current intake totals, hydration level metrics, and notification service status.
+```bash
+drunken-chunk status
+```
+
+* **Compact Prompts & Status Bars (`--mini`):**
+  Perfect for loading into status widgets (like tmux, polybar, or zsh prompts):
+  ```bash
+  drunken-chunk status --mini
+  ```
+  *Output Example:* `[████████░░░░░░] 66.7%`
+
+---
+
+### 4. Vessel Shortcuts (`shortcut`)
+Configure convenient, memorable shortcuts for drink vessels to speed up logging.
+
+* **List active vessel shortcuts:**
+  ```bash
+  drunken-chunk shortcut list
+  ```
+* **Add or update a shortcut (e.g., custom `mug` holding 300ml):**
+  ```bash
+  drunken-chunk shortcut add mug 300
+  ```
+* **Remove a shortcut:**
+  ```bash
+  drunken-chunk shortcut remove bottle
+  ```
+
+---
+
+### 5. Historical Log View (`history`)
+Review your logged intake and check if targets were reached over the past week.
+```bash
+drunken-chunk history --days 7
+```
+
+---
+
+### 6. Behavioral Analytics (`analyze`)
+Executes behavior analysis on your historical SQL registry to map habits and discover dehydration triggers.
+```bash
+drunken-chunk analyze
+```
+Surfaces telemetry analytics for:
+* **Target Consistency**: Hit rates and consistency indices over the last fortnight.
+* **Temporal Spread**: Diurnal breakdown showing what percentage of water you log in the Morning, Afternoon, Evening, and Night.
+* **Weekday Variance**: Visualizes which days of the week your intake drops.
+* **Intake Frequency Gaps**: Calculates the average time gap between drinks to determine if you are "chugging" vs "sipping".
+* **Personalized Health Warnings**: Actionable alerts based on drinking patterns (e.g. drinking too close to bed).
+
+---
+
+### 7. Reminder Controls (`start` / `stop` / `snooze`)
+Manage the background notification process.
+
+* **Start the background daemon:**
+  ```bash
+  drunken-chunk start
+  ```
+* **Stop the background daemon:**
+  ```bash
+  drunken-chunk stop
+  ```
+* **Snooze reminders (e.g., temporarily silence popups for 45 minutes):**
+  ```bash
+  drunken-chunk snooze 45
+  ```
+
+---
+
+### 8. Startup Integration (`autostart`)
+Configure the background hydration daemon to boot up automatically when your computer starts.
+
+* **Toggle or check autostart registration:**
+  ```bash
+  drunken-chunk autostart status
+  drunken-chunk autostart enable
+  drunken-chunk autostart disable
+  ```
+
+---
+
+## 📂 Project Directory Layout
+
+```
+drunken-chunk/
+├── drunken_chunk/
+│   ├── __init__.py
+│   ├── analytics.py        # Telemetry calculations and diurnal spreading analysis
+│   ├── cli.py              # CLI argument parser and routing commands
+│   ├── db.py               # SQLite database setup and profile/log queries
+│   ├── profile.py          # Metabolic calculations and BMI indexing
+│   ├── reminder.py         # Cross-platform background daemon and notification dispatching
+│   ├── shortcut.py         # Shortcut validation and registry updates
+│   └── utils.py            # ANSI colors, banners, and table visual formatters
+├── setup.py                # Package metadata and installation script
+├── drunken-chunk           # Linux & macOS shell executable wrapper
+├── drunken-chunk.bat       # Windows cmd batch executable wrapper
+├── README.md               # User manual and documentation
+└── .gitignore
+```
+
+---
+
+## ⚙️ How It Works under the Hood
+
+* **Data Isolation**: User profiles, custom shortcuts, daemon states, and hydration registries are stored securely in a local directory `~/.drunken_chunk/drunken_chunk.db`.
+* **Zero-Library Color Sequences**: Windows Console colors are configured using standard ANSI escapes combined with native Win32 `ctypes` bindings that enable Virtual Terminal Processing on Windows consoles. Non-Windows systems support standard ANSI styling natively.
+* **Low Overhead Polling Loop**: The reminder daemon process runs a lightweight background loop polling every 20 seconds. It reads the database directly to check if a notification is due and goes to sleep without loading CPU resources.
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome to make Drunken Chunk even better! If you have suggestions or bug fixes:
+1. Fork this repository.
+2. Create your feature branch (`git checkout -b feature/amazing-feature`).
+3. Commit your changes (`git commit -m 'Add some amazing feature'`).
+4. Push to the branch (`git push origin feature/amazing-feature`).
+5. Open a Pull Request.
+
+---
+
+## 📄 License
+
+Distributed under the MIT License. See [LICENSE](LICENSE) for more information.

package/bin/index.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+const { spawn, spawnSync } = require('child_process');
+const path = require('path');
+
+function getPythonCommand() {
+    const cmds = process.platform === 'win32' ? ['python', 'py'] : ['python3', 'python'];
+    for (const cmd of cmds) {
+        try {
+            const res = spawnSync(cmd, ['--version'], { stdio: 'ignore' });
+            if (res.status === 0) {
+                return cmd;
+            }
+        } catch (e) {
+            // Ignore error and try next
+        }
+    }
+    // Fallback to python
+    return process.platform === 'win32' ? 'python' : 'python3';
+}
+
+const pythonCmd = getPythonCommand();
+
+// The module root is one folder up from `bin/index.js`
+const packageRoot = path.dirname(__dirname);
+
+// Set up PYTHONPATH environment variable so python can find the `drunken_chunk` module
+const env = { ...process.env };
+env.PYTHONPATH = env.PYTHONPATH 
+    ? `${packageRoot}${path.delimiter}${env.PYTHONPATH}`
+    : packageRoot;
+
+// Run the python module
+const args = ['-m', 'drunken_chunk.cli', ...process.argv.slice(2)];
+
+const child = spawn(pythonCmd, args, {
+    stdio: 'inherit',
+    env: env
+});
+
+child.on('close', (code) => {
+    process.exit(code !== null ? code : 1);
+});
+
+child.on('error', (err) => {
+    console.error(`Failed to start the drunken-chunk command: ${err.message}`);
+    console.error(`Please ensure Python 3.8+ is installed on your system.`);
+    process.exit(1);
+});

package/drunken_chunk/__init__.py

@@ -0,0 +1,2 @@
+# Drunken Chunk - Water reminder and behavior analytics tool
+__version__ = "1.0.0"

package/drunken_chunk/analytics.py

@@ -0,0 +1,172 @@
+from datetime import datetime
+import collections
+import statistics
+
+from .db import get_all_logs, get_profile
+from .profile import calculate_recommended_intake
+
+def get_day_name(date_str):
+    return datetime.strptime(date_str, "%Y-%m-%d").strftime("%A")
+
+def analyze_drinking_behavior():
+    """
+    Analyzes historical drinking behavior.
+    Returns a dict with processed analytics metrics or None if not enough data.
+    """
+    logs = get_all_logs()
+    profile = get_profile()
+    
+    if not profile:
+        return {"error": "Profile not configured. Please run 'drunken-chunk init'."}
+        
+    if not logs:
+        return {"error": "No water logs recorded yet. Start logging with 'drunken-chunk log'!"}
+
+    target = profile['custom_target'] if profile['custom_target'] else calculate_recommended_intake(profile['weight'], profile['height'])
+
+    # 1. Basic Stats
+    total_consumed = sum(log['amount'] for log in logs)
+    total_entries = len(logs)
+    
+    # Group logs by date
+    daily_totals = collections.defaultdict(int)
+    daily_entries = collections.defaultdict(list)
+    
+    for log in logs:
+        # timestamp format: "YYYY-MM-DD HH:MM:SS"
+        dt = datetime.strptime(log['timestamp'], "%Y-%m-%d %H:%M:%S")
+        date_str = dt.strftime("%Y-%m-%d")
+        daily_totals[date_str] += log['amount']
+        daily_entries[date_str].append(dt)
+
+    unique_days_logged = len(daily_totals)
+    avg_daily_consumption = total_consumed / unique_days_logged
+    
+    days_met_target = sum(1 for amount in daily_totals.values() if amount >= target)
+    target_hit_rate = (days_met_target / unique_days_logged) * 100
+
+    # 2. Weekday Analysis
+    # To get proper averages, count unique weekday occurrences in the logged period
+    weekday_occurrences = collections.defaultdict(set)
+    weekday_totals = collections.defaultdict(int)
+    
+    for date_str, amount in daily_totals.items():
+        day_name = get_day_name(date_str)
+        weekday_totals[day_name] += amount
+        weekday_occurrences[day_name].add(date_str)
+        
+    weekday_averages = {}
+    for day in ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]:
+        occurrences = len(weekday_occurrences[day])
+        if occurrences > 0:
+            weekday_averages[day] = weekday_totals[day] / occurrences
+        else:
+            weekday_averages[day] = 0.0
+
+    # 3. Time of Day Analysis
+    time_blocks = {
+        "Early Morning (5am - 9am)": 0,
+        "Late Morning (9am - 12pm)": 0,
+        "Afternoon (12pm - 5pm)": 0,
+        "Evening (5pm - 9pm)": 0,
+        "Night (9pm - 5am)": 0
+    }
+    
+    for log in logs:
+        dt = datetime.strptime(log['timestamp'], "%Y-%m-%d %H:%M:%S")
+        hour = dt.hour
+        if 5 <= hour < 9:
+            time_blocks["Early Morning (5am - 9am)"] += log['amount']
+        elif 9 <= hour < 12:
+            time_blocks["Late Morning (9am - 12pm)"] += log['amount']
+        elif 12 <= hour < 17:
+            time_blocks["Afternoon (12pm - 5pm)"] += log['amount']
+        elif 17 <= hour < 21:
+            time_blocks["Evening (5pm - 9pm)"] += log['amount']
+        else:
+            time_blocks["Night (9pm - 5am)"] += log['amount']
+            
+    # Calculate percentage for each time block
+    total_time_blocked = sum(time_blocks.values())
+    time_block_pct = {}
+    for block, val in time_blocks.items():
+        time_block_pct[block] = (val / total_time_blocked * 100) if total_time_blocked > 0 else 0.0
+
+    # 4. Drink Gaps / Frequency Analysis
+    all_gaps_mins = []
+    
+    for date_str, dts in daily_entries.items():
+        # Sort chronologically for the day
+        dts.sort()
+        if len(dts) < 2:
+            continue
+            
+        for i in range(len(dts) - 1):
+            gap = dts[i+1] - dts[i]
+            gap_mins = gap.total_seconds() / 60.0
+            all_gaps_mins.append(gap_mins)
+            
+    avg_gap_mins = statistics.mean(all_gaps_mins) if all_gaps_mins else 0
+    median_gap_mins = statistics.median(all_gaps_mins) if all_gaps_mins else 0
+    
+    # 5. Consistency Index (last 14 days or fewer if newly joined)
+    # Target 80% completion of recommended intake
+    consistency_days = list(daily_totals.values())[-14:]
+    active_days_count = len(consistency_days)
+    met_80_percent_count = sum(1 for amount in consistency_days if amount >= (target * 0.8))
+    consistency_index = (met_80_percent_count / active_days_count * 100) if active_days_count > 0 else 0.0
+
+    # 6. Narrative Insights & Suggestions
+    suggestions = []
+    
+    if avg_gap_mins > 0:
+        gap_h = int(avg_gap_mins // 60)
+        gap_m = int(avg_gap_mins % 60)
+        suggestions.append(f"• Your average drinking gap is {gap_h}h {gap_m}m.")
+        
+        # Compare with reminder interval
+        reminder_interval = profile['reminder_interval']
+        if avg_gap_mins > reminder_interval + 15:
+            suggestions.append(f"  - This is {int(avg_gap_mins - reminder_interval)} mins slower than your reminder setting. Consider checking notifications more closely.")
+        elif avg_gap_mins < reminder_interval:
+            suggestions.append(f"  - Great job! You are drinking water more frequently than the alarm interval.")
+    else:
+        suggestions.append("• Drink multiple times a day to calculate gap frequency analysis.")
+        
+    # Analyze best and worst days
+    valid_weekday_averages = {k: v for k, v in weekday_averages.items() if v > 0}
+    if valid_weekday_averages:
+        best_day = max(valid_weekday_averages, key=valid_weekday_averages.get)
+        worst_day = min(valid_weekday_averages, key=valid_weekday_averages.get)
+        
+        if best_day != worst_day:
+            suggestions.append(f"• Hydration Champion Day: {best_day} (avg: {int(weekday_averages[best_day])} ml).")
+            suggestions.append(f"• Dehydration Danger Day: {worst_day} (avg: {int(weekday_averages[worst_day])} ml). Watch out on {worst_day}s!")
+            
+    # Analyze time blocks
+    if time_block_pct:
+        best_block = max(time_block_pct, key=time_block_pct.get)
+        suggestions.append(f"• Peak drinking period: {best_block} ({time_block_pct[best_block]:.1f}% of total).")
+        
+        # Check if night drinking is too high (may affect sleep)
+        if time_block_pct.get("Night (9pm - 5am)", 0.0) > 30.0:
+            suggestions.append("  - Warning: You drink more than 30% of your water at night. This can disrupt your sleep cycle. Try drinking more during the day.")
+        
+        # Check if early morning is too low (important to kickstart metabolism)
+        if time_block_pct.get("Early Morning (5am - 9am)", 0.0) < 5.0:
+            suggestions.append("  - Suggestion: Start your day with a glass of water immediately after waking to wake up your organs.")
+
+    return {
+        "target": target,
+        "total_consumed": total_consumed,
+        "total_entries": total_entries,
+        "unique_days": unique_days_logged,
+        "avg_daily": avg_daily_consumption,
+        "hit_rate": target_hit_rate,
+        "weekday_averages": weekday_averages,
+        "time_block_pct": time_block_pct,
+        "avg_gap_mins": avg_gap_mins,
+        "median_gap_mins": median_gap_mins,
+        "consistency_index": consistency_index,
+        "suggestions": suggestions
+    }