Metadata-Version: 2.4
Name: kot-attendance-bot
Version: 1.0.2
Summary: Autofill missing King of Time (KOT) time records using Selenium
Project-URL: Repository, https://git.sr.ht/~ivan-ustinov/kot-attendance-bot
Author-email: Ivan Ustinov <ivan.ustinov@gmx.com>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: attendance,automation,king-of-time,kot,selenium
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Utilities
Requires-Python: >=3.14
Requires-Dist: selenium>=4.43.0
Description-Content-Type: text/markdown

# kot-attendance-bot

Selenium helper for automating King of Time attendance tasks.

## Installation

```bash
pip install kot-attendance-bot
```

## Setup

On first run, the tool prompts for clock-in, break-start times, and browser selection, then asks whether to save them to `config.toml`.

Edit `config.toml` if you want different default times, auto-login, or proxy settings. `HTTP_PROXY` and `HTTPS_PROXY` environment variables override values in `config.toml`.

### Credentials

Login is manual unless configured via `config.toml` or environment variables:
- **Environment Variables**: Set `KOT_USERNAME` and `KOT_PASSWORD`. This automatically enables auto-login.
- **Config File**: Set `auto_login = true` and provide `username` and `password`.

**Note:** Auto-login stores the password in plaintext in `config.toml`. Using environment variables is recommended for better security.

## Commands

### Fill Missing Records

```bash
kot-attendance-bot fill [options]
```

Opens King of Time, prompts for login (if needed), switches to the requested month, and fills missing time records for weekdays.
- **Default visibility**: Visible (use `--headless` to run hidden).
- **Default month**: Current month (checks previous month first during the first work week).

### Holiday Lookup

```bash
kot-attendance-bot holiday [options]
```

Extracts holidays (system holidays and scheduled leaves) for a specific month.
- **Default visibility**: Headless (use `--visible` to see the browser).
- **Caching**: Results are saved in `kot-attendance-bot.json` to avoid redundant browser sessions.
- **Formats**: ASCII calendar (default), lines of text (`--text`), or JSONL (`--json`).

## AI Agent Integration

This project is "Agent-Ready," featuring the **King of Time Attendance** skill—a set of procedural instructions that allow AI agents to handle your attendance tasks autonomously. Whether you use **Gemini CLI**, **Claude Code**, **GitHub Copilot**, or **Codex**, you can simply ask the agent to "fill my missing records" or "check my April holidays," and it will know exactly how to execute the commands with the correct flags and environment variables.

### To use the skill:

- **Gemini CLI**: Install the packaged skill from [SkillHub](https://www.skillhub.club/skills/ivan.ustinov-king-of-time-attendance) or directly from source:
  ```bash
  gemini skills install https://git.sr.ht/~ivan-ustinov/king-of-time-attendance.skill --scope workspace
  /skills reload
  ```
- **Claude Code, Copilot, Cursor, etc.**: Point your agent to the instructions in the [skill repository](https://git.sr.ht/~ivan-ustinov/king-of-time-attendance.skill). The clear, imperative instructions help any LLM-based agent understand the CLI's nuances, headless requirements, and credential handling.

Now you can just delegate your King of Time tasks to your favorite AI assistant!

## Options

All commands support these shared options:
- `-c, --config PATH`: Path to `config.toml`.
- `-b, --browser BROWSER`: Browser to use (`firefox`, `chrome`, `edge`, `safari`).
- `--month MONTH`: Month number (1-12).
- `-y, --auto`: Skip runtime confirmations.
- `--headless`: Run browser in headless mode.
- `--visible`: Run browser in visible mode.

For `holiday` specifically:
- `--no-cache`: Force fresh data fetch from King of Time.
- `--text`: Output as simple text lines.
- `--json`: Output as JSONL.

## Output Redirection

In headless mode, status and progress messages are sent to `stderr`, while actual data results (like holiday lists) and interactive prompts are sent to `stdout`. This allows you to redirect logs without losing the output:

```bash
kot-attendance-bot holiday --json 2>/dev/null > holidays.jsonl
```

## Contribution

### Setup for Development

This project uses `uv` for dependency management.

```bash
uv sync
```

### Running Tests

```bash
uv run python -m unittest discover -s tests
```

### Local Execution

```bash
uv run python main.py [command] [options]
```
